From e36ab64536f25131ee05eeb21b6246bb09de4133 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sun, 22 Sep 2024 16:34:04 +0200
Subject: [PATCH] nix: add upgrade guide for bumping nix versions

---
 pkgs/tools/package-management/nix/README.md   | 35 +++++++++++++++++++
 pkgs/tools/package-management/nix/default.nix |  1 +
 2 files changed, 36 insertions(+)
 create mode 100644 pkgs/tools/package-management/nix/README.md

diff --git a/pkgs/tools/package-management/nix/README.md b/pkgs/tools/package-management/nix/README.md
new file mode 100644
index 000000000000..0105b504e9b0
--- /dev/null
+++ b/pkgs/tools/package-management/nix/README.md
@@ -0,0 +1,35 @@
+# Steps for Testing New Releases
+
+## Patch Releases or Updating `nixVersions.{latest,git}`
+
+Branch to merge into: **master** or **release-$nixos-version**
+
+Build the affected Nix packages and run their tests on the following platforms: **x86_64-linux**, **aarch64-linux**, **x86_64-darwin**, and **aarch64-darwin**.
+If you lack the necessary hardware for these platforms, you may need to ask others for assistance with the builds.
+Alternatively, you can request access to the Nix community builder for all platforms [here](https://github.com/NixOS/aarch64-build-box) and [here](https://nix-community.org/community-builder/).
+
+To build all dependent packages, use:
+
+```
+nix-review pr <your-pull-request>
+```
+
+And to build all important NixOS tests, run:
+
+```
+# Replace $version with the actual Nix version
+nix-build nixVersions.nix_$version.tests
+```
+
+Be sure to also update the `nix-fallback-paths` whenever you do a patch release for `nixVersions.stable`
+
+```
+# Replace $version with the actual Nix version
+curl https://releases.nixos.org/nix/nix-$version/fallback-paths.nix > nixos/modules/installer/tools/nix-fallback-paths.nix
+```
+
+## Major Version Bumps
+
+If you're updating `nixVersions.stable`, follow all the steps mentioned above, but use the **staging** branch for your pull request (or **staging-next** after coordinating with the people in matrix `#staging:nixos.org`)
+This is necessary because, at the end of the staging-next cycle, the NixOS tests are built through the [staging-next-small](https://hydra.nixos.org/jobset/nixos/staging-next-small) jobset.
+Especially nixos installer test are important to look at here.
diff --git a/pkgs/tools/package-management/nix/default.nix b/pkgs/tools/package-management/nix/default.nix
index 38cd370d064a..ab059abf912f 100644
--- a/pkgs/tools/package-management/nix/default.nix
+++ b/pkgs/tools/package-management/nix/default.nix
@@ -265,6 +265,7 @@ in lib.makeExtensible (self: ({
     else
       nix;
 
+  # Read ./README.md before bumping a major release
   stable = addFallbackPathsCheck self.nix_2_18;
 } // lib.optionalAttrs config.allowAliases (
   lib.listToAttrs (map (