Branch-off

For these steps "23.05" represents the current release tag and "23.11" represents the next (6 months in the future) release tag. "22.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.

Example configuration: nixos:release-22.11

FieldValue
StateEnabled
DescriptionNixOS 22.11 release branch
Nix expressionnixos/release-combined.nix in input nixpkgs
Check interval86400
Scheduling shares5000000 (8.32% out of 60071636 shares)
Enable Dynamic RunCommand Hooks:No (not enabled by server)
Number of evaluations to keep1

Inputs:

Input nameTypeValues
nixpkgsGit checkouthttps://github.com/NixOS/nixpkgs.git release-22.11
stableBranchBooleanfalse
supportedSystemsNix expression[ "x86_64-linux" "aarch64-linux" ]

Actual branch-off

Set NEWVER to the new release version:

export NEWVER=23.05

On the master branch

Pull in the final changes before performing the actal 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 (23.05 -> 23.11)
    echo -n "23.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 PULL_REQUEST_TEMPLATE.md on master.

    Examples: 22.11

  6. Update CONTRIBUTING.md on master

    Examples: 22.11

  7. Commit the changes (22.05 example + this additional commit)

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

    git tag --annotate $NEWVER-pre
    git push upstream master $NEWVER-pre
    git describe HEAD # should yield 23.05-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 nixos-org-configurations and nag the infrastructure team to get these changes deployed.

    Example: 22.11

  2. Create the backport labels for all new branches:

    • backport staging-21.05
    • backport release-21.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-org-configurations
    
  2. Give the Marketing team a heads-up about the upcoming release

  3. Get in contact with Amine Chikhaoui on the infrastructure room on Matrix, so they can get the AMIs updated in time for the release.

    1. They will need to run create-amis.sh, which requires write permissions to the S3 bucket.

    2. Create PR adding it to NixOS configuration. Examples:

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