From aaef82e192fbee108f9c2f64f4dd1fa2cd21d72b Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 14:12:05 +0100 Subject: [PATCH 1/9] 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 + ``` + + 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 + ``` + + 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`). From 98364a0df234f0febfddbcdde4a627405d6b19f1 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 14:33:12 +0100 Subject: [PATCH 2/9] Mention milestone --- maintainers/release-process.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 68063f50c..5eeb0c206 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -147,6 +147,10 @@ release: Make a PR and auto-merge it. +* Create a milestone for the next release, move all unresolved issues + from the previous milestone, and close the previous milestone. Set + the date for the next milestone 6 weeks from now. + ## Creating a point release * Wait for the desired evaluation of the maintenance jobset to finish From f2b9e1f8cb682d37533feed7d5b1d1a4ee13ad81 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 15:26:26 +0100 Subject: [PATCH 3/9] Update maintainers/release-process.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com> --- maintainers/release-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 5eeb0c206..b266b35e0 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -15,7 +15,7 @@ release: * (Optionally) Updated `fallback-paths.nix` in Nixpkgs -* Update the manual on https://nixos.org/manual/nix/stable/ +* An updated manual on https://nixos.org/manual/nix/stable/ ## Creating a new release from master From 758c2fdbfe93ab5d3582cc83dfef80f20387630b Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 15:27:45 +0100 Subject: [PATCH 4/9] Update maintainers/release-process.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com> --- maintainers/release-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index b266b35e0..e1f8e7d75 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -59,7 +59,7 @@ release: * Wait for the PR to be merged. -* Branch the release: +* Create a branch for the release: ```console $ git checkout master From 31e3c7d6fd5ce6c009ef2b7025aa1de43050ca2e Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 17:07:51 +0100 Subject: [PATCH 5/9] Mention Discourse --- maintainers/release-process.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index e1f8e7d75..759e80d3c 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -79,7 +79,7 @@ release: * Push the release branch: ```console - $ git push + $ git push --set-upstream origin $VERSION-maintenance ``` * Create a jobset for the release branch on Hydra as follows: @@ -151,6 +151,9 @@ release: from the previous milestone, and close the previous milestone. Set the date for the next milestone 6 weeks from now. +* Post an announcement on Discourse, including the contents of + `rl-$VERSION.md`. + ## Creating a point release * Wait for the desired evaluation of the maintenance jobset to finish From 27392a3b48bad24385ddf1c359f7c04164b6aabc Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 17:46:42 +0100 Subject: [PATCH 6/9] More tweaks --- maintainers/release-process.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 759e80d3c..27452b37e 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -139,10 +139,12 @@ release: ```console $ git checkout master - $ echo -n 2.13.0 > .version - $ git checkout -b bump-2.13 + $ git pull + $ NEW_VERSION=2.13.0 + $ echo -n $NEW_VERSION > .version + $ git checkout -b bump-$NEW_VERSION $ git commit -a -m 'Bump version' - $ git push + $ git push --set-upstream origin bump-$NEW_VERSION ``` Make a PR and auto-merge it. From acb69a7beb434e5a5a25462f6d4e38d771eca7a1 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 7 Dec 2022 13:29:50 +0100 Subject: [PATCH 7/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com> Co-authored-by: Robert Hensing --- maintainers/release-process.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 27452b37e..565539bf6 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -52,10 +52,10 @@ release: $ 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 + $ git push --set-upstream $REMOTE release-notes ``` -* Create a PR for `release-notes` and auto-merge it. +* Create a PR for `release-notes`. * Wait for the PR to be merged. @@ -122,17 +122,16 @@ release: `/home/eelco/Dev/nix-pristine` and `/home/eelco/Dev/nixpkgs-pristine`. + TODO: trigger nixos.org netlify: https://docs.netlify.com/configure-builds/build-hooks/ * Prepare for the next point release by editing `.version` to e.g. ```console - $ echo -n 2.12.1 > .version + $ echo 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`: @@ -173,3 +172,8 @@ release: * Bump the version number of the release branch as above (e.g. to `2.12.2`). + +## Recovering from mistakes + +`upload-release.pl` should be idempotent. For instance a wrong `IS_LATEST` value can be fixed that way, by running the script on the actual latest release. + From 6eed1325ffbe50214620e974685e36731e8730b6 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 12 Dec 2022 17:04:06 +0100 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Valentin Gagarin --- maintainers/release-process.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 565539bf6..75c1470b8 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -17,11 +17,11 @@ release: * An updated manual on https://nixos.org/manual/nix/stable/ -## Creating a new release from master +## Creating a new release from the `master` branch -* Make sure that https://hydra.nixos.org/jobset/nix/master is green. +* Make sure that the [Hydra `master` jobset](https://hydra.nixos.org/jobset/nix/master) succeeds. -* In a checkout of the Nix repo, make sure you're on `master` and do a +* In a checkout of the Nix repo, make sure you're on `master` and run `git pull`. * Move the contents of `doc/manual/src/release-notes/rl-next.md` @@ -103,10 +103,10 @@ release: * When the jobset evaluation has succeeded building, take note of the evaluation ID (e.g. `1780832` in - https://hydra.nixos.org/eval/1780832). + `https://hydra.nixos.org/eval/1780832`). * Tag the release and upload the release artifacts to - `releases.nixos.org` and dockerhub: + [`releases.nixos.org`](https://releases.nixos.org/) and [Docker Hub](https://hub.docker.com/): ```console $ IS_LATEST=1 ./maintainers/upload-release.pl @@ -114,7 +114,7 @@ release: 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. + [latest Nix manual](https://nixos.org/manual/nixpkgs/unstable/). TODO: This script requires the right AWS credentials. Document. @@ -146,13 +146,13 @@ release: $ git push --set-upstream origin bump-$NEW_VERSION ``` - Make a PR and auto-merge it. + Make a pull request and auto-merge it. * Create a milestone for the next release, move all unresolved issues from the previous milestone, and close the previous milestone. Set the date for the next milestone 6 weeks from now. -* Post an announcement on Discourse, including the contents of +* Post an [announcement on Discourse](https://discourse.nixos.org/c/announcements/8), including the contents of `rl-$VERSION.md`. ## Creating a point release From 5c0d3b476f617723b90d6e9daf0d8b53ac25bbac Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 12 Jan 2023 00:19:18 +0100 Subject: [PATCH 9/9] release-process: Add "create a backport label" --- maintainers/release-process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/maintainers/release-process.md b/maintainers/release-process.md index 75c1470b8..b52d218f5 100644 --- a/maintainers/release-process.md +++ b/maintainers/release-process.md @@ -152,6 +152,8 @@ release: from the previous milestone, and close the previous milestone. Set the date for the next milestone 6 weeks from now. +* Create a backport label + * Post an [announcement on Discourse](https://discourse.nixos.org/c/announcements/8), including the contents of `rl-$VERSION.md`.