branch master updated: doc: Update release instructions.

[Maxim Cournoyer]

This is an automated email from the git hooks/post-receive script.

apteryx pushed a commit to branch master
in repository maintenance.

The following commit(s) were added to refs/heads/master by this push:
     new 4e33411  doc: Update release instructions.
4e33411 is described below

commit 4e334119a349cce926522e148bdec59126f0b9ad
Author: Maxim Cournoyer <maxim.cournoyer@gmail.com>
AuthorDate: Tue May 11 23:13:35 2021 -0400

    doc: Update release instructions.
    
    * doc/release.org (Bootstrap and build): Renamed from 'Bootstrapping'.
    Use nproc * 2 as the parallel job count passed to make.
    (Update the translation files): Renamed from 'Updating the translation
    files'.  Suggest running 'autoreconf -f' after updating the
    translations to catch mistakes and cross-reference the guix manual.
    Drop last paragraph, which isn't that important anymore now that the
    translations are fetched from git and not rate limited.
    (Run “make release” for one or several release candidates): Simplify
    wording.
    (Merge the version-X-Y-Z branch into master): New section.
    (Update web pages): Note mcron frequency.
    (Prepare the email announcement): Use X.Y.Z version templates.
    (Send the email announcement): Drop the newsgroups.  Publicly
    available NNTP servers seem a rarity these days.
    (Post a news item on the web site (automated)): Drop recommendations
    about the form, as this is now all automated.
---
 doc/release.org | 55 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 28 insertions(+), 27 deletions(-)

diff --git a/doc/release.org b/doc/release.org
index e3d2ae2..bdf2a84 100644
--- a/doc/release.org
+++ b/doc/release.org
@@ -43,16 +43,16 @@ The documentation has a few extra requirements:
 
   $ guix environment guix --ad-hoc imagemagick perl
 
-** Bootstrapping
+** Bootstrap and build
 
 If you haven done so already, the build system should be initialized
 using:
 
   $ ./bootstrap && ./configure --localstatedir=/var --sysconfdir=/etc
 
-And the project should be built with something like:
+and the project should be built with something like:
 
-  $ make -j$(nproc)
+  $ make -j$((2 * $(nproc)))
 
 ** Add a Git tag
 
@@ -67,24 +67,23 @@ The tag must be =vX.Y.Z=.  For the sake of consistency, 
always use
 =GNU Guix X.Y.Z= as the tag comment.  The ~autoreconf -f~ invocation
 is important, and should be re-run anytime you create a new tag.
 
-** Updating the translation files
+** Update the translation files
 
-To fetch, update and commit the translation files, you can run:
+In a nutshell, to update the translation files, you can run:
 
   $ make download-po
-  $ make doc-po-update
-  $ git add po
+  # Test that the translated manuals build fine.
+  $ make
+  # To detect additional problems with translation files.
+  $ autoreconf -f
 
-Then commit any newly added file in a first commit, after having
-registered them in the doc/local.mk and po/doc/local.mk files.  For
-the rest of the change, it's OK to simply do:
+If there are any new translation files, commit them following the
+guidelines in [[info:guix#Translating Guix][(guix)Translating Guix]].  For the 
remaining changes, it's
+OK to simply do:
 
+  $ git add po
   $ git commit -m 'nls: Update translations.'
 
-The downloading and committing of the .po files is not automated as it
-takes time (about 2 minutes), and all files are re-downloaded every
-time it runs.
-
 ** Run “make release” for one or several release candidates
 
 This will automatically build:
@@ -108,9 +107,8 @@ that only if your machine is in a safe place!):
 Caveat: If the release target fails, you'll be left in the middle of
 something which cannot be resumed from where it stopped.  You can try
 to debug the underlying commands that failed, but after fixing the
-problem, you should restart the release process from the beginning,
-cleaning the tree and removing any automatic commits that were done to
-update the ~guix~ package.
+problem, you should remove any automatic commits that were done to
+update the ~guix~ package and try again.
 
 #+begin_example
   default-cache-ttl 36000
@@ -131,6 +129,12 @@ If “make release” succeeded, push the branch and tag:
 
   $ git push
 
+** 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~).
+
 ** Upload all the files
 
 The ~gnupload~ script from [[https://www.gnu.org/software/gnulib/][Gnulib]] is 
used to upload the release
@@ -187,7 +191,8 @@ First, re-read the GNU Maintainers Guide 
[[info:maintain.info#Announcements][on
 Update the ‘latest-guix-version’ value in (apps base utils), in the
 guix-artwork.git repository.  Add a blog post under posts/.
 
-The web site will be automatically rebuilt by an mcron job on berlin.
+The web site will be automatically rebuilt by an mcron job on berlin
+(every hour).
 
 ** Update the on-line copy of the manual
 
@@ -197,11 +202,11 @@ Change the ‘static-web-site’ service in hydra/berlin.scm
 ** Prepare the email announcement
 
   $ build-aux/announce-gen --release-type=alpha --package-name=guix \
-      --previous-version=A.B --current-version=X.Y \
+      --previous-version=X1.Y1.Z1 --current-version=X2.Y2.Z2 \
       --gpg-key-id=MY-KEY --url-directory=https://ftp.gnu.org/gnu/guix \
       --bootstrap-tools=autoconf,automake,makeinfo,help2man
 
-The subject must be "GNU Guix X.Y released".  The text should remain
+The subject must be "GNU Guix X.Y.Z released".  The text should remain
 formal and impersonal (it is sent on behalf of the Guix and GNU
 projects.)  It must include a description of what Guix is (not everyone
 reading info-gnu may know about it.)  Use the text of previous
@@ -218,15 +223,11 @@ Send to these places, preferably in the morning on a 
working day (UTC):
   - guix-devel@gnu.org, help-guix@gnu.org
   - gnu-system-discuss@gnu.org, info-gnu@gnu.org
   - guile-user@gnu.org, nix-dev@lists.science.uu.nl
-  - comp.lang.scheme
-  - comp.lang.functional
-
-** Post a news item on the web site
 
-The news will end up on planet.gnu.org and [[http://scheme.dk/planet/][Planet 
Scheme]].  The text can
-be shorter and more informal, with a link to the email announcement for
-details.  Add the [[./announcements/savannah/about.txt]["About" footer]] at 
the bottom of the announcement.
+** Post a news item on the web site (automated)
 
+The blog post will automatically end up on planet.gnu.org and 
[[http://scheme.dk/planet/][Planet
+Scheme]].
 
 
 Copyright © 2014, 2018, 2019 Ludovic Courtès <ludo@gnu.org>