Merge pull request #1071 from EnergySystemsModellingLab/add-release-notes-to-docs

Add release notes to docs

Author: alexdewar

.github/PULL_REQUEST_TEMPLATE.md

@@ -19,6 +19,8 @@ Fixes # (issue)
 
 - [ ] All tests pass: `$ cargo test`
 - [ ] The documentation builds and looks OK: `$ cargo doc`
+- [ ] Update release notes for the latest release if this PR adds a new feature or fixes a bug
+      present in the previous release
 
 ## Further checks
 

README.md

@@ -112,4 +112,4 @@ specification. Contributions of any kind welcome!
 
 ## Copyright
 
-Copyright © 2025 Imperial College London
+Copyright © 2026 Imperial College London

docs/SUMMARY.md

@@ -19,3 +19,6 @@
   - [Building and developing MUSE2](developer_guide/coding.md)
   - [Developing the documentation](developer_guide/docs.md)
 - [API documentation](./api/muse2/README.md)
+- [Release notes](release_notes/README.md)
+  - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md)
+  - [Next unreleased version](release_notes/upcoming.md)

docs/release_notes/README.md

@@ -0,0 +1,11 @@
+# Release notes
+
+This is the list of changes for each release of MUSE2.
+
+To download the latest release for your platform, please see our [GitHub releases page].
+
+To see the list of changes for the current, in-progress version of MUSE2, [see here](./upcoming.md).
+
+- [MUSE2 v2.0.0 (October 14, 2025)](./v2.0.0.md)
+
+[GitHub releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases

docs/release_notes/upcoming.md

@@ -0,0 +1,72 @@
+# Upcoming release of MUSE2
+
+<!-- Instructions for developers:
+
+This file contains information about the current in-progress version of MUSE2. Once that version is
+ready to be released, carry out the following steps:
+
+- Copy this file, giving it a name corresponding to its version (e.g. v2.3.4)
+- Change the heading to be in the form "Release notes for MUSE2 v2.3.4 (January 3, 2027)"
+- Remove this comment 😀
+- Add the new file to docs/SUMMARY.md and docs/release_notes/README.md
+- Empty the sections below in *this* file (upcoming.md) ready for us to add changes for the next
+  version
+
+-->
+
+## New features
+
+- You can now set both upper and lower bounds for process availabilities ([#1018])
+- Default output root path is now configurable in `settings.toml` ([#1003])
+- If demand cannot be satisfied by the simulation, we now inform users what the offending
+  commodities and time slices are ([#767])
+- Trim whitespace from fields when reading in CSV files ([#976])
+- Assets can now be commissioned after a specified number of years with the `mothball_years`
+  parameter ([#1022])
+- Default to no availability limits if user doesn't provide any for a process ([#1018])
+- Allow user to specify ranges of years in input files ([#1017])
+- Users can now omit empty CSV files ([#961])
+- Users can now optionally specify an explicit decommission year for an asset in `assets.csv` input
+  file ([#966])
+- Allow for adding both a `prod` and `cons` levy to a commodity ([#969])
+- Availability limits can now be provided at multiple levels for a process ([#1018])
+- Pricing strategy can now vary by commodity ([#1021])
+
+## Experimental features
+
+- Assets can now be made divisible to represent many individual assets, such as a fleet of gas
+  boilers (albeit the current implementation is slow; [#1030]). These fleets can be partially
+  decommissioned.
+- Users can now have circular dependencies between commodities, such as a hydrogen power plant that
+  itself requires electricity (though the current solution likely won't work in every situation;
+  [#986])
+- There are new options for pricing strategy (`full` and `marginal`), which take capital costs into
+  account ([#1021])
+
+## Bug fixes
+
+- Fix: process availability constraints were wrongly being applied to individual time slices,
+  regardless of time slice level ([#1018])
+- Various fixes to process flows and availabilities input code for non-milestone years ([#868],
+  [#1000], [#1010])
+- Users can now set demand to zero in `demand.csv` ([#871])
+- Fix: sign for levies of type `net` was wrong for inputs ([#969])
+- Fix `--overwrite` option for `save-graphs` command ([#1001])
+
+[#767]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/767
+[#868]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/868
+[#871]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/871
+[#961]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/961
+[#966]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/966
+[#969]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/969
+[#976]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/976
+[#986]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/986
+[#1000]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1000
+[#1001]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1001
+[#1003]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1003
+[#1010]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1010
+[#1017]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1017
+[#1018]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1018
+[#1021]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1021
+[#1022]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1022
+[#1030]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1030

docs/release_notes/v2.0.0.md

@@ -0,0 +1,27 @@
+# Release notes for MUSE2 v2.0.0 (October 14, 2025)
+
+After nearly 18 months of development and 464 PRs, we are pleased to announce the first release of
+the all-new MUSE2 🎉! A big thank you to [everyone who contributed to this amazing
+milestone](https://github.com/EnergySystemsModellingLab/MUSE2?tab=readme-ov-file#contributors-).
+
+MUSE2 is a tool written in Rust for running simulations of energy systems, which is planned to be
+the eventual successor to the original [MUSE](https://github.com/EnergySystemsModellingLab/MUSE_OS).
+Note that this is a completely new project written from scratch, with both the code and the model
+underlying it redesigned from the ground up to be simpler and faster. By design, we do not wish to
+add every feature that MUSE1 has, but we hope to eventually support all the common use cases for
+those who run these types of models.
+
+As there are some important features still missing from MUSE2 (e.g. [#794], [#509]), we do not
+recommend that you attempt to use it for research at this stage. However, please do give it a spin!
+If there are any features missing that you feel are important, let us know by [opening an
+issue](https://github.com/EnergySystemsModellingLab/MUSE2/issues).
+
+It is rather unusual to have the first release of a piece of software be 2.0.0. The reason for this
+is to avoid confusion with the previous MUSE program. Be aware that this project does not follow
+[semantic versioning](https://semver.org/).
+
+To get started, you can download MUSE2 for your platform below. For more information, please consult
+[the documentation](https://energysystemsmodellinglab.github.io/MUSE2/).
+
+[#794]: https://github.com/EnergySystemsModellingLab/MUSE2/issues/794
+[#509]: https://github.com/EnergySystemsModellingLab/MUSE2/issues/509

tests/citation_cff.rs

@@ -0,0 +1,57 @@
+//! Check the CITATION.cff file and release notes
+use anyhow::{Context, Result};
+use std::fs;
+use std::path::Path;
+use yaml_rust2::{Yaml, YamlLoader};
+
+/// Version string for the current version of MUSE2
+const MUSE2_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+fn get_version_from_citation_cff() -> Result<String> {
+    let citation = fs::read_to_string("CITATION.cff")?;
+    let yaml = YamlLoader::load_from_str(&citation)?;
+    let yaml = yaml
+        .first()
+        .context("Empty YAML file")?
+        .as_hash()
+        .context("Not YAML object")?;
+    let version = yaml
+        .get(&Yaml::from_str("version"))
+        .context("version key not found")?
+        .as_str()
+        .context("version should be string")?;
+
+    Ok(version.to_string())
+}
+
+#[test]
+fn citation_cff_version() {
+    assert_eq!(
+        MUSE2_VERSION,
+        get_version_from_citation_cff().unwrap(),
+        "Software version in Cargo.toml and CITATION.cff must match. If you are making a new \
+        release, please also update the CITATION.cff file."
+    );
+}
+
+/// A crude check that release notes for the current version are referenced in the given path
+fn check_link_to_release_notes(path: &Path) {
+    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",
+        path.display()
+    );
+}
+
+#[test]
+fn release_notes_exist_and_linked() {
+    let path = format!("docs/release_notes/v{MUSE2_VERSION}.md");
+    assert!(
+        Path::new(&path).exists(),
+        "Release notes doc doesn't exist: {path}"
+    );
+
+    check_link_to_release_notes(Path::new("docs/SUMMARY.md"));
+    check_link_to_release_notes(Path::new("docs/release_notes/README.md"));
+}