01/03: doc: Update release document.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository maintenance.

commit 3797abea087f49b67127019fb75aaaf0e7df531a
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Mon Dec 19 15:05:40 2022 +0100

    doc: Update release document.
    
    * doc/release.org: Update.
---
 doc/release.org | 71 ++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 53 insertions(+), 18 deletions(-)

diff --git a/doc/release.org b/doc/release.org
index 3f05960..23528f4 100644
--- a/doc/release.org
+++ b/doc/release.org
@@ -5,9 +5,54 @@
 
 This document describes the typical release process for Guix.
 
-* Update NEWS
+* Process overview
 
-** Update the list fixed bugs, with bugs.gnu.org URL
+The release process can span several weeks and goes along these lines.
+
+** Nominating a release management team
+
+First, a team of 2–3 people should be designated as responsible for the
+release.  The team has to be committed to be available for the duration
+of the whole process, which may typically span several weeks.
+
+** Identifying and addressing bugs considered release blockers
+
+As the team starts its work, it should identify what it considers are
+release blockers and call for discussion of these on =guix-devel=.
+
+** Stabilizing things
+
+From there on, stabilize things, in particular core package builds on
+all supported architectures (=make assert-binaries-available=).
+
+** Creating a =version-X.Y.Z= branch
+
+Its policy is to only receive critical bug fixes.  It should converge
+towards a state without any known critical bug.
+
+** Adding a Cuirass jobset for branch =version-X.Y.Z=
+
+This jobset will have to be kept until the next release, so that
+substitutes remain available.  The easiest way to add a new jobset is
+directly via the web interface of Cuirass.  To be allowed to do so,
+you must authenticate with the Cuirass instance via a private TLS
+certificate imported into your browser.
+
+** Publish release candidates
+
+RCs should be made from that branch, using the normal release
+mechanisms.  Call for testing and incorporate feedback to prepare either
+a new RC or the final release.
+
+** Communication throughout the process
+
+To improve legibility, and to give contributors a chance to help, the
+whole process must be transparent.  Send a *weekly update* about things
+that have been fixed and critical issues that remain to be addressed.
+
+* Updating NEWS
+
+** Update the list fixed bugs, with issues.guix.gnu.org URLs
 
 Run "git log" and search for "^Fixes".
 
@@ -30,11 +75,10 @@ your maintenance.git checkout.  Make sure to commit it:
   git add data/packages-X.Y.Z.txt
   git commit -m "Data for X.Y.Z."
 
-* Prepare & upload tarball
+* Preparing & uploading tarballs and ISOs
 
-** Create branch 'version-X.Y.Z'
+** Check out the =version-X.Y.Z= branch
 
-  $ git branch version-X.Y.Z
   $ git checkout version-X.Y.Z
 
 ** Enter a guix environment containing everything needed
@@ -129,11 +173,10 @@ If “make release” succeeded, push the branch and tag:
 
   $ git push
 
-** Merge the version-X-Y-Z branch into master
+** Merge the =version-X.Y.Z= branch into master
 
-It's recommended to not alter the history at this time, so that the
-release tag will be reachable directly from the master branch (and
-visible in ~git describe~).
+  $ git checkout master
+  $ git merge version-X.Y.Z
 
 ** Upload all the files
 
@@ -156,17 +199,9 @@ Your GPG public key must be registered for this to work 
(info
 "(maintain) Automated Upload Registration").
 
 Make sure to publish your public key on public OpenPGP servers
-(keys.gnupg.net, pgp.mit.edu, etc.), so that people can actually use it
+(keys.openpgp.org, pgp.mit.edu, etc.), so that people can actually use it
 to check the authenticity and integrity of the tarball.
 
-** Add a Cuirass jobset for branch 'version-X.Y.Z'
-
-This jobset will have to be kept until the next release, so that
-substitutes remain available.  The easiest way to add a new jobset is
-directly via the web interface of Cuirass.  To be allowed to do so,
-you must authenticate with the Cuirass instance via a private TLS
-certificate imported into your browser.
-
 *** Generate a TLS user certificate for Cuirass
 
 On the Berlin machine, do the following: