Add release notes to docs #1071

alexdewar · 2026-01-13T11:36:05Z

Description

As suggested by @tsmbland, I've added a release notes section to the documentation, modelled on MUSE1's documentation.

I populated the release notes for the previous release (v2.0.0) from the existing notes on the GitHub releases page. I've started a new doc for the next release (v2.1.0) and I've populated it based on issues closed since the last release. Going forward, we should fill this out as we go along. I haven't included it in SUMMARY.md, so it won't be built along with the other docs for now -- I figured it would be better to wait until we actually release it, but I suppose we could have the notes for in-progress releases in the docs too, if we want.

I added a couple of tests to check that release notes have been added for the latest release in case we forget.

Closes #1068.

Type of change

Bug fix (non-breaking change to fix an issue)
New feature (non-breaking change to add functionality)
Refactoring (non-breaking, non-functional change to improve maintainability)
Optimization (non-breaking change to speed up the code)
Breaking change (whatever its nature)
Documentation (improve or add documentation)

Key checklist

All tests pass: $ cargo test
The documentation builds and looks OK: $ cargo doc

Further checks

Code is commented, particularly in hard-to-understand areas
Tests added that prove fix is effective or that feature works

I copy-pasted these from the release notes on GitHub and tweaked the markdown to format correctly with `mdbook`.

codecov · 2026-01-13T11:39:04Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.09%. Comparing base (c65a789) to head (c0a6cbf).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1071   +/-   ##
=======================================
  Coverage   82.09%   82.09%           
=======================================
  Files          53       53           
  Lines        7310     7310           
  Branches     7310     7310           
=======================================
  Hits         6001     6001           
  Misses       1019     1019           
  Partials      290      290

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR adds a release notes section to the documentation, following the pattern used in MUSE1's documentation. It includes release notes for v2.0.0 (the current release), prepares a draft for v2.1.0 (the next release), and adds automated tests to ensure release notes are maintained for future releases.

Changes:

Refactored citation verification tests by moving them from tests/citation_cff.rs to tests/release.rs and adding new tests for release note validation
Added release notes documentation files for v2.0.0 and v2.1.0 (draft)
Updated the PR template to remind contributors to update release notes
Integrated release notes into the documentation structure via SUMMARY.md

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/release.rs	New test file combining citation version checks with new tests that verify release notes exist and are properly linked
tests/citation_cff.rs	Deleted file - functionality moved to tests/release.rs
docs/release_notes/v2.1.0.md	Draft release notes for the upcoming v2.1.0 release with features, bug fixes, and experimental features
docs/release_notes/v2.0.0.md	Release notes for the current v2.0.0 release, populated from GitHub releases
docs/release_notes/README.md	Index page for release notes section with link to v2.0.0
docs/SUMMARY.md	Updated to include release notes section in the documentation navigation
.github/PULL_REQUEST_TEMPLATE.md	Added checklist item reminding contributors to update release notes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/release.rs

docs/release_notes/v2.1.0.md

.github/PULL_REQUEST_TEMPLATE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/release_notes/v2.1.0.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-13T11:48:57Z

tests/release.rs

+    check_link_to_release_notes(Path::new("docs/SUMMARY.md"));
+    check_link_to_release_notes(Path::new("docs/release_notes/README.md"));


The test release_notes_file_exists will fail if the release notes file exists but is not yet linked in SUMMARY.md or README.md. This is problematic because the PR description mentions that unreleased version notes (like v2.1.0) are intentionally not included in SUMMARY.md until they are actually released. Consider making the test more flexible to handle this scenario, perhaps by checking if the version has been released before requiring it to be in SUMMARY.md, or by allowing the test to be skipped for pre-release versions.

Suggested change

check_link_to_release_notes(Path::new("docs/SUMMARY.md"));

check_link_to_release_notes(Path::new("docs/release_notes/README.md"));

// Only require links from SUMMARY/README for non-pre-release versions.

// Pre-release versions typically contain a '-' suffix in their SemVer string

// (e.g., "2.1.0-alpha.1"), and for those it's acceptable for the notes file

// to exist without yet being linked in the docs indices.

if !MUSE2_VERSION.contains('-') {

check_link_to_release_notes(Path::new("docs/SUMMARY.md"));

check_link_to_release_notes(Path::new("docs/release_notes/README.md"));

}

I guess this makes sense. The other check in this test also doesn't apply to -dev releases though, so we should probably just skip the test altogether in this case.

Copilot · 2026-01-13T11:48:58Z

.github/PULL_REQUEST_TEMPLATE.md

+- [ ] Update release notes for the latest release if this PR adds a new feature or fixes a bug
+      present in the previous release


The checklist item mentions updating release notes "if this PR adds a new feature or fixes a bug present in the previous release". This wording could be clearer. It's ambiguous whether "fixes a bug present in the previous release" means a bug that existed in the previous release (which would warrant a note) or only bugs introduced after the previous release (which wouldn't). Consider rephrasing to make it clear that any user-facing bug fix should be documented in release notes.

Suggested change

- [ ] Update release notes for the latest release if this PR adds a new feature or fixes a bug

present in the previous release

- [ ] Update release notes for the latest release if this PR adds a new feature or fixes a user-facing bug

I actually think the current wording makes more sense. You could have user-facing bugs that were both added and fixed since the last release (not uncommon!) and those don't need documenting.

tsmbland

Looks good!

I've started a new doc for the next release (v2.1.0) and I've populated it based on issues closed since the last release.

Since we won't necessarily know what number the next release will be (it's obvious now, but won't always be), could I propose renaming this to something like upcoming.md. Then when it comes to making a release we can rename the file to whatever release number we decide and create a fresh upcoming.md for the next release. We could also link this in relase_notes/README.md, like "Here is a list of work in progress features which will be available in the next release of MUSE"

Going forward, we should fill this out as we go along.

Don't disagree. I don't really do this for MUSE1 because I find it's easier to put together something cohesive and user-friendly if I write it at the time of release (rather than just collecting a list of bullet points as I go along), but by all means we can do something in-between here.

Also, side point, but apart from now in relase_notes/README.md I don't think we mention anywhere else in the documentation how to actually install MUSE/where to download the executable. It's in the GitHub README, but I think it would be good to make this clearer on the documentation site because this is likely the first thing people will want to know when looking at the documentation!

Another side point, but is it possible to have a documentation page for each release, like we do in MUSE1 (/do we want this?)

tsmbland · 2026-01-13T12:09:45Z

docs/release_notes/upcoming.md

+- Fix: sign for levies of type `net` was wrong for inputs ([#944])
+- Fix `--overwrite` option for `save-graphs` command ([#982])
+
+[#363]: https://github.com/EnergySystemsModellingLab/MUSE2/issues/363


In MUSE1 I've set things up so you can write "{github}461" inline to automatically generate links for github issues/PRs. Do you want me to see if I can do something similar here?

Also, do you think it's better to link to the issue, or to the pull request that fixed the issue? I generally do the latter with MUSE1, becuase it's usually more descriptive of the actual change that was made, but what do you think?

I've obvs gone for linking to the issue, but now that you mention it, linking PRs might make more sense. Will be a faff to change, but we do want to be consistent... maybe I can script it 😄

We probably could automatically generate the links, but I think it might be more trouble than it's worth with mdbook. I think the way you'd have to do it is by invoking a script as a preprocessor, which could mean we end up with a dependency on Python for building the docs, which isn't ideal.

We probably could automatically generate the links, but I think it might be more trouble than it's worth with mdbook. I think the way you'd have to do it is by invoking a script as a preprocessor, which could mean we end up with a dependency on Python for building the docs, which isn't ideal.

Ah fair enough. Looks like you can write preprocessors in rust (https://rust-lang.github.io/mdBook/for_developers/preprocessors.html), but might be more effort than it's worth

Good to know! Might be handy for something. I suspect it will be a bit faffier given that Rust isn't really a scripting language though.

I'm not totally averse to having Python be a requirement to work with the docs btw (it already is for the file format stuff anyway). It just seems a bit unnecessary for the mdbook part of the docs -- don't want to end up having to help someone install a Python toolchain just to tweak an equation or something. That said, it might be fine if there's a way to just skip the preprocessing step if Python doesn't exist or whatever.

I've obvs gone for linking to the issue, but now that you mention it, linking PRs might make more sense. Will be a faff to change, but we do want to be consistent... maybe I can script it 😄

In the end I got Copilot to write a script to do this. It did muck it up the first couple of times, but we got there in the end!

alexdewar · 2026-01-13T13:08:18Z

Since we won't necessarily know what number the next release will be (it's obvious now, but won't always be), could I propose renaming this to something like upcoming.md. Then when it comes to making a release we can rename the file to whatever release number we decide and create a fresh upcoming.md for the next release. We could also link this in relase_notes/README.md, like "Here is a list of work in progress features which will be available in the next release of MUSE"

Good idea! I'll do that.

Going forward, we should fill this out as we go along.

Don't disagree. I don't really do this for MUSE1 because I find it's easier to put together something cohesive and user-friendly if I write it at the time of release (rather than just collecting a list of bullet points as I go along), but by all means we can do something in-between here.

I was thinking we could maybe write some longer sections about anything noteworthy. Maybe like the Linux kernel changelog (though ours will probably be shorter 😄): https://kernelnewbies.org/LinuxChanges

Also, side point, but apart from now in relase_notes/README.md I don't think we mention anywhere else in the documentation how to actually install MUSE/where to download the executable. It's in the GitHub README, but I think it would be good to make this clearer on the documentation site because this is likely the first thing people will want to know when looking at the documentation!

Good point. A lot of users might land on docs/README.md first. I'll add some more details.

Another side point, but is it possible to have a documentation page for each release, like we do in MUSE1 (/do we want this?)

I don't think there's an easy way to do this with mdbook, so we would have to do some CI shenanigans to build the docs for every version of MUSE2. It is possible and maybe there's some value to it, but the docs are a bit incomplete/wrong in places as it is. We could open an issue for this though -- could be useful in future when the docs are a bit more mature. You can get old versions of the API docs on docs.rs: https://docs.rs/muse2/latest/muse2/

tsmbland · 2026-01-13T13:17:32Z

Another side point, but is it possible to have a documentation page for each release, like we do in MUSE1 (/do we want this?)

I don't think there's an easy way to do this with mdbook, so we would have to do some CI shenanigans to build the docs for every version of MUSE2. It is possible and maybe there's some value to it, but the docs are a bit incomplete/wrong in places as it is. We could open an issue for this though -- could be useful in future when the docs are a bit more mature. You can get old versions of the API docs on docs.rs: https://docs.rs/muse2/latest/muse2/

My worry is that if we update the documentation as we go along (which we are trying to do, as we should), then it won't necessarily be accurate for users using the latest version, which could end up really confusing. If we don't have a page for every release then I think at least having a "dev" site and a "release" site would be useful. Could also package a documentation build in the download so users have something persistent.

tsmbland · 2026-01-13T13:23:41Z

Another side point, but is it possible to have a documentation page for each release, like we do in MUSE1 (/do we want this?)

I don't think there's an easy way to do this with mdbook, so we would have to do some CI shenanigans to build the docs for every version of MUSE2. It is possible and maybe there's some value to it, but the docs are a bit incomplete/wrong in places as it is. We could open an issue for this though -- could be useful in future when the docs are a bit more mature. You can get old versions of the API docs on docs.rs: https://docs.rs/muse2/latest/muse2/

My worry is that if we update the documentation as we go along (which we are trying to do, as we should), then it won't necessarily be accurate for users using the latest version, which could end up really confusing. If we don't have a page for every release then I think at least having a "dev" site and a "release" site would be useful. Could also package a documentation build in the download so users have something persistent.

Do you think we could set things up in a way so that users could run muse2 docs and it magically loads the documentation for the version they're using (i.e. by somehow including the docs within the executable)?

alexdewar · 2026-01-13T13:27:32Z

I'm wondering whether it might actually be worth moving most (but not all) of the content from README.md to docs/README.md and then pointing users at that instead. It seems a bit wrong to duplicate content between them as one or other is liable to end up out of date... What do you think?

tsmbland · 2026-01-13T13:34:16Z

I'm wondering whether it might actually be worth moving most (but not all) of the content from README.md to docs/README.md and then pointing users at that instead. It seems a bit wrong to duplicate content between them as one or other is liable to end up out of date... What do you think?

I see your point. I still think it looks quite good to have a fleshed-out GitHub readme, even if there's some repetition with the docs. And realistically this isn't the sort of thing we'd be changing very often. I'll leave it up to you though.

alexdewar · 2026-01-13T14:20:44Z

I see your point. I still think it looks quite good to have a fleshed-out GitHub readme, even if there's some repetition with the docs. And realistically this isn't the sort of thing we'd be changing very often. I'll leave it up to you though.

Yeah, fair enough. Don't want the GitHub readme to be too bare either. Another option is to include the GitHub readme from docs/README.md (mdbook lets you do this) which would mean they would be perfectly in sync. Not sure we want that either though...

My worry is that if we update the documentation as we go along (which we are trying to do, as we should), then it won't necessarily be accurate for users using the latest version, which could end up really confusing. If we don't have a page for every release then I think at least having a "dev" site and a "release" site would be useful. Could also package a documentation build in the download so users have something persistent.

Hmm... good point. Maybe it is worth doing sooner rather than later then. Could you open an issue for it? I think there are various technical issues to be worked out here.

Do you think we could set things up in a way so that users could run muse2 docs and it magically loads the documentation for the version they're using (i.e. by somehow including the docs within the executable)?

Totally. One option would be to bundle the docs, like you suggest, and another would be to have muse2 docs open the URL for the relevant version of the docs on the web. The downside of bundling the docs is that it could increase the build time considerably and would mean anyone wanting to do this would need Python installed. HOWEVER, we could easily make this an opt-in feature (see here) if we wanted and just do it for the release builds we publish. That said, maybe having it all be online is a more sensible option.

tsmbland · 2026-01-13T14:26:39Z

Hmm... good point. Maybe it is worth doing sooner rather than later then. Could you open an issue for it? I think there are various technical issues to be worked out here.

Sounds good, I'll open two issues: one for versioning the documentation, and one for adding a muse2 docs command

I had Copilot generate a script to automate this. I checked most of the results and tweaked things a little.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-13T15:30:21Z

tests/release.rs

+    let contents = fs::read_to_string(path).unwrap();
+    assert!(
+        contents.contains(&format!("v{MUSE2_VERSION}.md")),
+        "File {} does not contain a link to the latest version's release notes",


The error message could be more helpful by including the expected filename that should be present. Consider including the format string "v{MUSE2_VERSION}.md" in the error message to make it clear what link is expected.

Suggested change

"File {} does not contain a link to the latest version's release notes",

"File {} does not contain a link to the latest version's release notes (expected link text: v{{MUSE2_VERSION}}.md)",

tests/release.rs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

alexdewar added 6 commits January 13, 2026 10:27

Add placeholder doc for release notes

f315357

Add release notes for v2.0.0

3dff9d4

I copy-pasted these from the release notes on GitHub and tweaked the markdown to format correctly with `mdbook`.

Add test that release notes doc exists

1bb171a

Also test that the release is linked to in the relevant places

f35ac3c

Add in-progress release notes for unreleased v2.1.0

62e23b9

PULL_REQUEST_TEMPLATE.md: Add reminder to update release notes

2c5a408

Copilot AI review requested due to automatic review settings January 13, 2026 11:36

Copilot started reviewing on behalf of alexdewar January 13, 2026 11:36 View session

Copilot AI reviewed Jan 13, 2026

View reviewed changes

tests/release.rs Outdated Show resolved Hide resolved

tests/release.rs Outdated Show resolved Hide resolved

docs/release_notes/v2.1.0.md Outdated Show resolved Hide resolved

.github/PULL_REQUEST_TEMPLATE.md Outdated Show resolved Hide resolved

alexdewar requested review from Aurashk, Copilot and tsmbland January 13, 2026 11:40

Copilot started reviewing on behalf of alexdewar January 13, 2026 11:41 View session

Apply Copilot suggestions about wording etc.

ee3b564

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

alexdewar force-pushed the add-release-notes-to-docs branch from 3457c46 to ee3b564 Compare January 13, 2026 11:43

Copilot AI reviewed Jan 13, 2026

View reviewed changes

docs/release_notes/v2.1.0.md Outdated Show resolved Hide resolved

Another suggestion about wording

a3d9461

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 13, 2026 11:45

Copilot started reviewing on behalf of alexdewar January 13, 2026 11:45 View session

Copilot AI reviewed Jan 13, 2026

View reviewed changes

tsmbland approved these changes Jan 13, 2026

View reviewed changes

Rename v2.1.0.md to upcoming.md and link in docs

80d35eb

tsmbland mentioned this pull request Jan 13, 2026

muse2 docs command #1073

Open

upcoming.md: Replace issue numbers with PR numbers

e516be7

I had Copilot generate a script to automate this. I checked most of the results and tweaked things a little.

Copilot AI review requested due to automatic review settings January 13, 2026 15:24

Copilot started reviewing on behalf of alexdewar January 13, 2026 15:24 View session

Copilot AI reviewed Jan 13, 2026

View reviewed changes

Improve test name

c0a6cbf

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 13, 2026 15:31

alexdewar enabled auto-merge January 13, 2026 15:31

Copilot started reviewing on behalf of alexdewar January 13, 2026 15:31 View session

alexdewar merged commit 0e0e2fa into main Jan 13, 2026
11 checks passed

alexdewar deleted the add-release-notes-to-docs branch January 13, 2026 15:33

Copilot AI reviewed Jan 13, 2026

View reviewed changes

		check_link_to_release_notes(Path::new("docs/SUMMARY.md"));
		check_link_to_release_notes(Path::new("docs/release_notes/README.md"));

-    check_link_to_release_notes(Path::new("docs/SUMMARY.md"));
-    check_link_to_release_notes(Path::new("docs/release_notes/README.md"));
+    // Only require links from SUMMARY/README for non-pre-release versions.
+    // Pre-release versions typically contain a '-' suffix in their SemVer string
+    // (e.g., "2.1.0-alpha.1"), and for those it's acceptable for the notes file
+    // to exist without yet being linked in the docs indices.
+    if !MUSE2_VERSION.contains('-') {
+        check_link_to_release_notes(Path::new("docs/SUMMARY.md"));
+        check_link_to_release_notes(Path::new("docs/release_notes/README.md"));
+    }

		- [ ] Update release notes for the latest release if this PR adds a new feature or fixes a bug
		present in the previous release

	"File {} does not contain a link to the latest version's release notes",
	"File {} does not contain a link to the latest version's release notes (expected link text: v{{MUSE2_VERSION}}.md)",

Add release notes to docs #1071

Add release notes to docs #1071

Uh oh!

Conversation

alexdewar commented Jan 13, 2026

Description

Type of change

Key checklist

Further checks

Uh oh!

codecov bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tsmbland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexdewar commented Jan 13, 2026

Uh oh!

tsmbland commented Jan 13, 2026

Uh oh!

tsmbland commented Jan 13, 2026

Uh oh!

alexdewar commented Jan 13, 2026

Uh oh!

tsmbland commented Jan 13, 2026

Uh oh!

alexdewar commented Jan 13, 2026

Uh oh!

tsmbland commented Jan 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 13, 2026 •

edited

Loading