Final Release

Set the following environment variables to execute the commands below

# The version of the previous stable release
export OLDVER=22.11
# The version that is about to be released
export NEWVER=23.05

Before the final release

  • Two days before expected release date, change stableBranch to true in Hydra and wait for the channel to update

  • Re-check that the release editors have completed their work on the release notes

  • Merge the Pull Request that marks broken packages as broken

  • Update README.md on master with new stable NixOS version information. Then backport the change to the release branch.

  • Update Upgrading NixOS section of the manual to match new stable release version and backport this as well. This way the manual will already reflect the new version on release. Example: 22.05

  • Ensure the installer images are sufficiently tested on both aarch64 and x86_64 linux:

    • Graphical (GNOME/KDE)
    • Minimal

    All ISO images can be found on the nixos/release-$NEWVER hydra jobset.

    If you don't have any hardware to test the aarch64-linux on, QEMU emulation should allow to boot the images in a reasonable time to check the installer starts and is usable.

  • Gather some information about the release for the final announcement

    • Number of non-merge commits for the release:

      git log upstream/release-$OLDVER..upstream/release-$NEWVER --no-merges --format=%an | wc -l
      
    • Number of contributors for this release:

      git log upstream/release-$OLDVER..upstream/release-$NEWVER --no-merges --format=%an | sort | uniq | wc -l
      
    • New/updated/removed packages:

      git switch release-$OLDVER
      NIX_PATH= nix-env -f $PWD -qaP --json --out-path > old.json
      
      git switch release-$NEWVER
      NIX_PATH= nix-env -f $PWD -qaP --json --out-path > new.json
      
      #!/usr/bin/env python3
      
      import json
      
      with open('old.json') as f:
          old = json.load(f)
      with open('new.json') as f:
          new = json.load(f)
      
      n_removed = 0
      n_new = 0
      n_updated = 0
      for pkgname,pkg in new.items():
          if pkgname not in old:
              n_new += 1
              continue
          if pkg["version"] != old[pkgname]["version"]:
              n_updated += 1
      for pkgname in old.keys():
          if pkgname not in new:
              n_removed += 1
      
      print(f"New: {n_new}")
      print(f"Rem: {n_removed}")
      print(f"Upd: {n_updated}")
      

      Best to check how the previous announcement post was formulated to see what needs to be included.

    • Added/removed modules:

      git diff release-$OLDVER..release-$NEWVER nixos/modules/module-list.nix | grep ^+ | wc -l
      git diff release-$OLDVER..release-$NEWVER nixos/modules/module-list.nix | grep ^- | wc -l
      
    • Added/removed options:

      Download the result of the nixos.options job in Hydra from both your release and the previous release, then do:

      # removed options:
      comm -23 <(jq -r 'keys[]' old.json | sort) <(jq -r 'keys[]' new.json | sort) | wc -l
      # new options:
      comm -13 <(jq -r 'keys[]' old.json | sort) <(jq -r 'keys[]' new.json | sort) | wc -l
      

At final release time

On the master branch

  1. Create these PRs on master and backport to the release branch:

    1. Update rl-$NEWVER.section.md with the final release date.

    2. Commit and push all changes.

      git commit -m "Release NixOS $NEWVER" -S
      git push upstream master
      

On the release branch

  1. Switch to the release branch

    git switch release-$NEWVER
    
  2. Cherry-pick the release commit from master

  3. Push the commit to the release branch

    git push
    
  4. Find the commit id and tag the release on the release branch:

    git tag --annotate --message="Release $NEWVER" $NEWVER <COMMIT_ID>
    git push upstream $NEWVER
    
  5. Update nixos-homepage for the release.

    Examples: 22.11, 22.05

    This step requires the released ISOs, from the hydra evaluation with stableBranch enabled, to be available.

    1. Update the flake.nix input released-nixpkgs to $NEWVER and then run:

    2. Run ./scripts/update.sh (this updates flake.lock to updated channel).

    3. Add a compressed version of the NixOS logo (19.09 example). The logo should have a width of 100px.

    4. Write the announcement to blog/announcements.xml

    5. Create a pull request and poke the marking team. Make sure to push to a branch on the nixos-homepage repository, not your own fork, so the CI actions work properly.

    The website is hosted by a CDN so you may occasionally see the old site for a couple of minutes/hours (?) after your changes

  6. Update nixos-org-configurations to reflect the stable channel status for $NEWVER and the deprecated status for $OLDVER.

    Examples: 22.11, 22.05, 21.11

  7. Create a new topic on Discourse to announce the release.

    Examples: 22.11, 22.05

  8. Once the Pull Request in nixos-org-configurations is merged, update nixos-search to mark the channel as released. This is the same process as for the creation of the beta channel in the project.

After Release

  1. Add the new release to repology. Don't remove old releases, they want to keep them around.

    Examples: 22.11, 22.05

  2. Update osinfo-db entries.

    Examples: 22.11, 22.05, 21.11

    nix-shell -p "python3.withPackages (p: [ p.lxml p.requests ])" -p cdrkit
    ./scripts/updates/nixos.py --release YY.MM --codename <codename> --release-date YYYY-MM-DD --next-release YY.MM
    git add .
    git commit -s -m "nixos: Add YY.MM release"
    
    # run tests to validate your changes
    nix-shell -p "python3.withPackages (p: [ p.lxml p.requests p.pytest ])" -p cdrkit osinfo-db-tools gettext --run "make check"
    
  3. Check that the AMI image references have been updated in nixos/modules/virtualisation/amazon-ec2-amis.nix.

  4. Close the milestone

  5. Close the blockers project

  6. Close all issues you opened for the release and unpin them if necessary

  7. Ask someone with the appropriate permissions to update the description of the NixOS and NixOS Dev Matrix rooms to include the new release

  8. Create an announcement for the retrospective, some days after the old channel is discontinued.

Examples: 22.11, 22.05