Making a release

This page describes the steps for making a new MUSE2 release.

Before you start

Before preparing the release, manually run the Test with MUSE2 workflow on the main branch of the muse2_data_analysis repository and check that all jobs pass. This workflow tests the analysis repository’s main branch against MUSE2’s main branch. If it does not pass, identify and fix the errors there before proceeding with the release.

Choose a version number

MUSE2 version numbers have the form 2.X.Y. The first digit is fixed at 2 to distinguish MUSE2 releases from the Python-based MUSE_OS. The second digit represents major changes, while the third digit represents minor changes. This is a looser versioning scheme than Semantic Versioning, where “major” and “minor” have stricter definitions.

Finalise the release notes

All releases should have comprehensive release notes explaining the main user-facing changes since the last release.

Developers are encouraged to add a note to docs/release_notes/upcoming.md for each user-facing change as it is made. This file should therefore provide a good starting point, but it should not be assumed to be complete or up to date. Review the full PR history since the last release and make sure that all user-facing changes introduced since then are included. Do not include changes that are only relevant to developers, or fixes for bugs that were introduced after the previous release.

Structure the notes in a user-friendly way, highlighting the main user-facing changes at the top and listing minor changes below. The release notes for v2.1.0 provide a useful example for a major release.

Once the release notes in docs/release_notes/upcoming.md are finalised:

Copy docs/release_notes/upcoming.md to docs/release_notes/v2.X.Y.md.
Update the heading in the new file to include the version and the date on which the release will be published, for example:
```
# Release notes for MUSE2 v2.3.4 (January 3, 2027)
```
Link the new release notes in docs/SUMMARY.md and docs/release_notes/README.md
Remove the release-note content from docs/release_notes/upcoming.md, while retaining the headings so it is ready to track changes for the next release.

Update version metadata

Update all release metadata together:

Set the package version in Cargo.toml.
Set version and date-released in CITATION.cff.

Publish the release

Once the preparation changes have been merged to main and CI has passed, create and publish a GitHub Release with the exact v2.X.Y tag, such as v2.3.4.

The published release triggers the workflows that build and attach binaries, publish the crate to crates.io, and deploy the documentation. Tags must use the v2.X.Y format so that the documentation tooling recognises them as MUSE2 releases.

After publishing, manually check the GitHub releases page, the MUSE2 crates.io page, and the published documentation to confirm that the release is available in each location.

Create a release for the analysis repository

After publishing the MUSE2 release, create and publish a release in the muse2_data_analysis repository with the same name as the MUSE2 release, such as v2.3.4. The analysis repository derives its package version from the Git tag, so this tag must exactly match the MUSE2 release tag.

Keyboard shortcuts