From aaef82e192fbee108f9c2f64f4dd1fa2cd21d72b Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Tue, 6 Dec 2022 14:12:05 +0100
Subject: [PATCH] Document the release process

---
 maintainers/release-process.md | 166 +++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 maintainers/release-process.md

diff --git a/maintainers/release-process.md b/maintainers/release-process.md
new file mode 100644
index 000000000..68063f50c
--- /dev/null
+++ b/maintainers/release-process.md
@@ -0,0 +1,166 @@
+# Nix release process
+
+## Release artifacts
+
+The release process is intended to create the following for each
+release:
+
+* A Git tag
+
+* Binary tarballs in https://releases.nixos.org/?prefix=nix/
+
+* Docker images
+
+* Closures in https://cache.nixos.org
+
+* (Optionally) Updated `fallback-paths.nix` in Nixpkgs
+
+* Update the manual on https://nixos.org/manual/nix/stable/
+
+## Creating a new release from master
+
+* Make sure that https://hydra.nixos.org/jobset/nix/master is green.
+
+* In a checkout of the Nix repo, make sure you're on `master` and do a
+  `git pull`.
+
+* Move the contents of `doc/manual/src/release-notes/rl-next.md`
+  (except the first line) to
+  `doc/manual/src/release-notes/rl-$VERSION.md` (where `$VERSION` is
+  the contents of `.version` *without* the patch level, e.g. `2.12`
+  rather than `2.12.0`).
+
+* Add a header to `doc/manual/src/release-notes/rl-$VERSION.md` like
+
+  ```
+  # Release 2.12 (2022-12-06)
+  ```
+
+* Proof-read / edit / rearrange the release notes. Breaking changes
+  and highlights should go to the top.
+
+* Add a link to the release notes to `doc/manual/src/SUMMARY.md.in`
+  (*not* `SUMMARY.md`), e.g.
+
+  ```
+  - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
+  ```
+
+* Run
+
+  ```console
+  $ git checkout -b release-notes
+  $ git add doc/manual/src/release-notes/rl-$VERSION.md
+  $ git commit -a -m 'Release notes'
+  $ git push --set-upstream edolstra release-notes
+  ```
+
+* Create a PR for `release-notes` and auto-merge it.
+
+* Wait for the PR to be merged.
+
+* Branch the release:
+
+  ```console
+  $ git checkout master
+  $ git pull
+  $ git checkout -b $VERSION-maintenance
+  ```
+
+* Mark the release as stable:
+
+  ```console
+  $ git cherry-pick f673551e71942a52b6d7ae66af8b67140904a76a
+  ```
+
+  This removes the link to `rl-next.md` from the manual and sets
+  `officialRelease = true` in `flake.nix`.
+
+* Push the release branch:
+
+  ```console
+  $ git push
+  ```
+
+* Create a jobset for the release branch on Hydra as follows:
+
+  * Go to the jobset of the previous release
+  (e.g. https://hydra.nixos.org/jobset/nix/maintenance-2.11).
+
+  * Select `Actions -> Clone this jobset`.
+
+  * Set identifier to `maintenance-$VERSION`.
+
+  * Set description to `$VERSION release branch`.
+
+  * Set flake URL to `github:NixOS/nix/$VERSION-maintenance`.
+
+  * Hit `Create jobset`.
+
+* Wait for the new jobset to evaluate and build. If impatient, go to
+  the evaluation and select `Actions -> Bump builds to front of
+  queue`.
+
+* When the jobset evaluation has succeeded building, take note of the
+  evaluation ID (e.g. `1780832` in
+  https://hydra.nixos.org/eval/1780832).
+
+* Tag the release and upload the release artifacts to
+  `releases.nixos.org` and dockerhub:
+
+  ```console
+  $ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
+  ```
+
+  Note: `IS_LATEST=1` causes the `latest-release` branch to be
+  force-updated. This is used by the `nixos.org` website to get the
+  latest Nix manual.
+
+  TODO: This script requires the right AWS credentials. Document.
+
+  TODO: This script currently requires a
+  `/home/eelco/Dev/nix-pristine` and
+  `/home/eelco/Dev/nixpkgs-pristine`.
+
+* Prepare for the next point release by editing `.version` to
+  e.g.
+
+  ```console
+  $ echo -n 2.12.1 > .version
+  $ git commit -a -m 'Bump version'
+  $ git push
+  ```
+
+  Note the `-n`: `.version` must not end in a newline.
+
+  Commit and push this to the maintenance branch.
+
+* Bump the version of `master`:
+
+  ```console
+  $ git checkout master
+  $ echo -n 2.13.0 > .version
+  $ git checkout -b bump-2.13
+  $ git commit -a -m 'Bump version'
+  $ git push
+  ```
+
+  Make a PR and auto-merge it.
+
+## Creating a point release
+
+* Wait for the desired evaluation of the maintenance jobset to finish
+  building.
+
+* Run
+
+  ```console
+  $ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
+  ```
+
+  Omit `IS_LATEST=1` when creating a point release that is not on the
+  most recent stable branch. This prevents `nixos.org` to going back
+  to an older release.
+
+* Bump the version number of the release branch as above (e.g. to
+  `2.12.2`).