How to release a new Mir version

Versions 2.26 and later

Mir releases are now driven by two GitHub Actions workflows:

• Start Release

• Finalize Release

This guide explains when to run each workflow and what to verify around them.

Embargoed security remediations

If releasing an embargoed security fix, perform this in a dedicated private repository before merging into main and making the GitHub release once the embargo lifts.

Start a release candidate

Run the Start Release workflow from GitHub Actions:

• version (required): the target release version (for example, 2.26.1)

• sha (optional): commit-ish to release, defaults to the selected ref tip (this can also be a tag for which a patch release is being prepared)

This workflow prepares the release candidate across git, packaging and GitHub. If the new release is started from main without a custom sha, the next development release will also be bootstrapped on main.

After it completes, verify:

1. A release/X.Y branch exists and contains the RC changes.

2. A vX.Y.Z-rc tag exists.

3. The release PR was created when run from main, with a comment containing the GitHub-generated release notes.

The release PR should have minimal changes on top of main, but if bugs or features are deemed to fit the release, they can be cherry-picked into the release branch.

Then run the release testing in How to test Mir for a release.

Prepare the release notes

Edit the release’s section in doc/sphinx/release-notes/X.Y.md and the corresponding debian/changelog entry on the release branch. The refine-release-notes skill can be used to prepare both using the GitHub-generated release notes comment and the git history and diff since the last release. Finalize Release uses the documentation section for the GitHub release body and the Debian entry for the RPM changelog.

Cherry-pick any needed changes

Use git cherry-pick --mainline 1 <ref> to commit any changes to the release branch.

Finalize the release

After RC testing passes, run Finalize Release:

• release_branch (required): release branch name, for example release/2.26

This workflow finalizes the release across git, packaging and GitHub, creating the GitHub release for vX.Y.Z.

After it completes, verify:

1. Tag vX.Y.Z exists on the release branch tip.

2. The GitHub release is published.

3. The GitHub release body matches the release’s documentation section, and the RPM changelog matches the Debian entry.

Merge the release branch into main

Finally, manually merge and push the release branch into main, resolving conflicts to ensure the correct ordering and dates in debian/changelog and rpm/mir.spec.

Back out a release

If a release is wrong or incomplete, didn’t reach main and the team decides to abandon it, remove it entirely before starting again. This is a destructive cleanup step: remove the release tags from Git and the release from GitHub, and remove references to it from packaging so the repository no longer points at a non-existent or invalid release.

1. Delete the temporary branch and any tags that were created for the release:

   git checkout main
   git tag -d vX.Y.Z vX.Y.Z-rc
   git push origin --delete vX.Y.Z
   git push origin --delete vX.Y.Z-rc
   
   # If this was a new MAJOR.MINOR series
   git branch -D release/X.Y
   git push origin --delete release/X.Y
   

2. Delete any corresponding GitHub release from the repository’s Releases page. This removes the published release entry and keeps the repository history aligned with the deleted tags and branch.

3. The automated release workflows update Mir release notes, including the per-series page and landing index. If abandoning a release, remove its entry and references to the abandoned version from both.

4. Update debian/control and rpm/mir.spec to remove references to the removed release.

After the removal is complete, start a new release with a higher patch number within the series, or a higher minor number for a new series.

Versions before 2.26

Before these workflows were introduced, releases were performed manually. At a high level, the manual process mirrored what the workflows now automate:

1. Create/update release/X.Y from the last patch release on the series.

2. Update Mir release notes, CMakeLists.txt, debian/changelog and rpm/mir.spec to the target release.

3. Commit any appropriate changes to the release branch and

   • push to the origin

   • or if it’s an embargoed change:

     • push to the dedicated repository

     • modify tools/ppa-upload.sh to point at the dedicated PPA rather than ~mir-team/rc

     • run RELEASE=XX.YY tools/ppa-upload.sh to upload to the relevant PPA

4. If not embargoed, open a Pull Request into main.

5. Run release testing and collect sign-off.

6. Commit, sign, and tag vX.Y.Z; push to the appropriate targets as above.

7. If not embargoed, or once that’s lifted:

   1. Merge the release branch into main.

   2. Publish the GitHub release.