Branch-off

For these steps "24.05" represents the current release tag and "24.11" represents the next (6 months in the future) release tag. "23.11" is the last release which was released 6 months ago.

Jobset creation

The infrastructure team can create the necessary jobsets in advance. They will not evaluate because the release branch doesn't exist but it allows the infrastructure team and the release team to work more asynchronously. Reach out to them 1-2 days before release to create the necessary Hydra Jobsets. You can link them this section.

• https://hydra.nixos.org/project/nixos
  • release-24.05
  • release-24.05-small
  • staging-next-24.05-small
• https://hydra.nixos.org/project/nixpkgs
  • nixpkgs-24.05-darwin
  • staging-next-24.05
  • staging-24.05

The easiest way to create the new jobsets is to clone the ones from the previous release and rewrite the version number.

Example configuration: nixos:release-25.11

Inputs for nixos/release-24.05, nixos/release-24.05-small:

stableBranch influences the versionSuffix in NixOS and the channel tarball.

• true leads to 24.05.1234.0abs3fe
• false leads to 24.05pre1234.0abs3fe

Note that changing this leads to a rebuild of most NixOS tests!

Inputs for nixpkgs/nixpkgs-24.05-darwin:

officialRelease influences the versionSuffix of the release tarball

• true leads to 24.05.1234.0abs3fe
• false leads to 24.05pre1234.0abs3fe

Nixpkgs branch protection ruleset

The same as for the jobsets applies to Nixpkgs branch protection rulesets, which can be updated by NixOS org owners in advance. You can propose the changes as a Pull Request to the NixOS/org repository.

New release branches should be added to the includes list in:

• https://github.com/NixOS/org/blob/main/rulesets/nixpkgs/require-merge-queue.json

Actual branch-off

Set NEWVER to the new release version (i.e. the version you release):

export NEWVER=24.05

On the master branch

Pull in the final changes before performing the actual branch-off.

1. Wait for the staging team to merge the final staging-next iteration

2. Fetch and check out the master branch

3. Create the release branch:

   git switch -c release-$NEWVER
   

On the release branch

Update metadata on the release branch, create its staging branches and tag the release.

1. Update the system.defaultChannel option default in nixos/modules/config/nix-channel.nix

2. Update the versionSuffix attribute in nixos/release.nix

   To get the commit count, use the following command:

   git rev-list --count release-$NEWVER
   

3. Add SUPPORT_END = "YYYY-MM-DD"; to osReleaseContents in nixos/modules/misc/version.nix.

4. Run treefmt

   nix-shell --run treefmt
   

5. Test that the tested "job" still evals

   nix eval -f nixos/release-combined.nix tested
   

6. Commit the changes from the previous steps

   git commit -m "$NEWVER beta release" -S
   

7. Update the staging branches

   git checkout staging-$NEWVER
   git merge release-$NEWVER
   git checkout staging-next-$NEWVER
   git merge release-$NEWVER
   

8. Tag the release and push everything

   git switch release-$NEWVER
   git tag --annotate --message="Release $NEWVER-beta" $NEWVER-beta
   git push upstream release-$NEWVER $NEWVER-beta staging-$NEWVER staging-next-$NEWVER
   

9. Create jobsets on hydra by contacting the infrastructure team and start the evaluation on all new jobsets.

10. Switch back to the master branch

    git switch master
    

11. Create the backport label for the new release branch:

    • backport release-24.05

    Use the description Backport PR automatically and the color value #0fafaa

Back on the master branch

Now we prepare the master branch for the next release after this one. We do this in two steps, error-prone changes thorugh a PR and direct to allow for proper tagging.

Set NEXTVER to the release number after the one you released (i.e. when you release 24.05, NEXTVER=24.11).

export NEXTVER=24.11

PR changes 1

1. Checkout a branch you want for the first PR, e.g.

   git switch -c rm-branchoff-documentation-changes
   

2. Add the release name to nixos/doc/manual/release-notes/rl-2411.section.md, doc/release-notes/rl-2411.section.md. Replace 2411 with your release number without the dot.

3. Include rl-2411.section.md in nixos/doc/manual/release-notes/release-notes.md, doc/release-notes/release-notes.md. Replace 2411 with your release number without the dot.

4. Update nixos/manual/doc/redirects.json, doc/redirects.json and to include the new sections.

5. Go through .github/ISSUE_TEMPLATE, and edit them to include the new version as beta.

   Example 25.11

6. Commit the changes and create a PR. Wait for the CI to finish and merge.

PR changes 2

You can create this PR while waiting for the CI of the first one.

1. Checkout a branch you want for the second PR, e.g.

   git switch -c rm-branchoff-ci-changes
   

2. Update .github/workflows/periodic-merge-24h.yml so that

   • release-$NEWVER (instead of master) gets merged into staging-next-$NEWVER

3. Update .github/labeler-no-sync.yml so that it includes backport release-25.11.

Direct changes

These changes should be done when the two PRs are already merged.

1. Switch back to the master branch

git switch master

1. Update the branch to get the changes from the two PRs

git pull

1. Increment the lib/.version file. This file must not end with a newline!

   # The release after $NEWVER (24.05 -> 24.11)
   echo -n "$NEXTVER" > lib/.version
   

2. Update the codeName attribute in lib/trivial.nix This will be the name for the next release.

3. Evaluate Nixpkgs to check for mistakes:

   nix-build ci -A eval.singleSystem --argstr evalSystem "x86_64-linux" --arg chunkSize 8000
   

4. Format your code changes:

   nix-shell --run treefmt
   

5. Commit the changes as $NEXTVER is <codeName>(25.11 example)

6. Tag the master branch, so that git describe shows the new version as the base for commits.

   git tag --annotate $NEXTVER-pre
   git push upstream master $NEXTVER-pre
   git describe HEAD # should yield $NEXTVER-pre
   

And afterwards

Now that everything on git is done, we are still missing the channels.

1. Create the necessary channels for https://channels.nixos.org in beta status, by updating channels.nix in infra and nag the infrastructure team to get these changes deployed.

   Example: 22.11

2. Update the ZHF issue, that now that the branch-off has been performed, fixes have to be backported. Examples: 22.05

Once the channel is available

The following steps should be done after the channels have become available on channels.nixos.org.

1. Update the flake input on the nixos-search repository by running the update-flake-lock and merging the new created PR afterwards.

2. Give the Marketing team a heads-up about the upcoming release

3. Get in contact with Arian van Putten

   1. They will need to update upload-legacy-ami.yml to point to the new jobset. This will automatically upload the AMIs from the jobset to AWS
   2. A PR is also welcome :)

4. Make sure the release editors have started finalizing the release notes. Only 7 days left until release!

5. Add release to LXC/Incus image server

   Ping Adam C. Stephens or open a Pull Request to lxc/lxc-ci

For Release Editors

Following a branch-off, Release Editors should keep in mind that the release notes between master and the release branches may fall out of sync. This is usually due to PRs adding release note entries being merged post branch-off. Entries for changes not actually present in the branched release may appear in master due to this, and backporting restructuring of the notes can be troublesome.