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
• https://hydra.nixos.org/project/nixpkgs
  • nixpkgs-24.05-darwin
  • staging-next-24.05

Example configuration: nixos:release-23.11

Inputs:

Actual branch-off

Set NEWVER to the new release version:

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 attribute 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. Commit the changes from the previous steps

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

5. Create the staging branches

   git branch staging-$NEWVER
   git branch staging-next-$NEWVER
   

6. Tag the release and push everything

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

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

8. Switch back to the master branch

   git switch master
   

Back on the master branch

Now we prepare the master branch for the next release after this one.

1. Update the periodic-merge workflow to include the new release.

2. Increment the .version file in the repository root.

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

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

4. Create a new release notes file for the next release

5. Update the release versions in .github/PULL_REQUEST_TEMPLATE.md on master.

6. Update CONTRIBUTING.md on master.

7. Commit the changes (23.05 example + this commit + this commit)

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

   git tag --annotate 24.11-pre
   git push upstream master 24.11-pre
   git describe HEAD # should yield 24.11-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. Create the backport labels for all new branches:

   • backport staging-24.05
   • backport release-24.05

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

3. 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, and create a pull request:

   git clone git@github.com:nixos/nixos-search
   nix --extra-experimental-features "nix-command flakes" flake lock --update-input nixos-infra
   

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!

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.