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.

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

Prepare the release notes

Edit Release notes on the release branch to include crafted notes for relevant changes included in the release. Release notes is the single source of truth: it drives the Debian changelog, RPM spec and GitHub release body generated by Finalize Release, so this is the only file that needs manual editing. Use the GitHub-generated release notes comment on the release PR, along with the git history and diff since the last release, as a reference — the refine-release-notes skill automates gathering this context.

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 release notes body on GitHub and in packaging matches the extracted section from Release notes.

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 Release notes, 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, release from GitHub, and from release-notes and 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. Update Release notes to remove the release entry and any references to the abandoned version. This includes removing the section for that release, and any release notes or PR comments that mention it so main does not retain stale references after the burn.

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 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.