branch master updated: doc: Add detailed usage instructions for the announce-gen script.

[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 96d7a21  doc: Add detailed usage instructions for the announce-gen 
script.
96d7a21 is described below

commit 96d7a212207166149797319504742e6431db0899
Author: Maxim Cournoyer <maxim.cournoyer@gmail.com>
AuthorDate: Wed May 12 13:18:04 2021 -0400

    doc: Add detailed usage instructions for the announce-gen script.
    
    And update the about.txt boilerplate text.
    
    * doc/release.org (Update the on-line copy of the manual): Add a note
    about restarting mcron after reconfiguring.
    (Prepare the email announcement): Add usage instructions for
    announce-gen.  Reword to explicit that appending NEWS should have been
    handled by the announce-gen script.
---
 doc/announcements/savannah/about.txt | 18 ++++++++++++++----
 doc/release.org                      | 35 +++++++++++++++++++++++++++--------
 2 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/doc/announcements/savannah/about.txt 
b/doc/announcements/savannah/about.txt
index 008de6c..59fda81 100644
--- a/doc/announcements/savannah/about.txt
+++ b/doc/announcements/savannah/about.txt
@@ -1,7 +1,17 @@
-== About GNU Guix ==
+• About
 
-[http://www.gnu.org/software/guix GNU Guix] is a transactional package manager 
for the GNU system.  The Guix System Distribution or GuixSD is an advanced 
distribution of the GNU system that relies on GNU Guix and 
[http://www.gnu.org/distros/free-system-distribution-guidelines.html respects 
the user's freedom].
+GNU Guix is a transactional package manager and an advanced
+distribution of the GNU system that respects user freedom.  Guix can
+be used on top of any system running the Hurd or the Linux kernel, or
+it can be used as a standalone operating system distribution for i686,
+x86_64, ARMv7, AArch64 and POWER9 machines.
 
-In addition to standard package management features, Guix supports 
transactional upgrades and roll-backs, unprivileged package management, 
per-user profiles, and garbage collection.  Guix uses low-level mechanisms from 
the Nix package manager, except that packages are defined as native 
[http://www.gnu.org/software/guile Guile] modules, using extensions to the 
[http://schemers.org Scheme] language.  GuixSD offers a declarative approach to 
operating system configuration management, and is  [...]
+In addition to standard package management features, Guix supports
+transactional upgrades and roll-backs, unprivileged package
+management, per-user profiles, and garbage collection.  When used as a
+standalone GNU/Linux distribution, Guix offers a declarative,
+stateless approach to operating system configuration management.  Guix
+is highly customizable and hackable through Guile programming
+interfaces and extensions to the Scheme language.
 
-GuixSD can be used on an i686 or x86_64 machine.  It is also possible to use 
Guix on top of an already installed GNU/Linux system, including on mips64el and 
armv7.
+https://guix.gnu.org
diff --git a/doc/release.org b/doc/release.org
index bdf2a84..7191d03 100644
--- a/doc/release.org
+++ b/doc/release.org
@@ -1,5 +1,5 @@
 #+TITLE: Release Process for GNU Guix
-#+AUTHOR: Ludovic Courtès
+#+AUTHOR: Ludovic Courtès, Maxim Cournoyer
 #+STARTUP: content hidestars
 #+EMAIL: ludo@gnu.org
 
@@ -197,14 +197,33 @@ The web site will be automatically rebuilt by an mcron 
job on berlin
 ** Update the on-line copy of the manual
 
 Change the ‘static-web-site’ service in hydra/berlin.scm
-(guix-maintenance.git) so that it builds the ‘version-X.Y.Z’ branch.
+(guix-maintenance.git) and reconfigure berlin, so that it builds the
+‘version-X.Y.Z’ branch.
+
+Note: Simply reconfiguring is *not* enough to ensure the new manual
+will be built.  You must also restart the mcron service for the update
+job to take effect.
 
 ** Prepare the email announcement
 
-  $ build-aux/announce-gen --release-type=alpha --package-name=guix \
-      --previous-version=X1.Y1.Z1 --current-version=X2.Y2.Z2 \
+The following command uses the =build-aux/announce-gen= script found
+in the ~gnulib~ sources.  By default, it will match only release
+artifacts named '${package-name}-${version}',
+e.g. 'guix-1.3.0.tar.gz'.  Since Guix includes various other artifacts
+such as ISO and QCOW2 images, it is useful to modify the script with
+the following command:
+
+  $ sed -E 's/(my @tarballs = ).*/\1glob("*.[xlg]z *.qcow2 *.iso");/' \
+      -i ~/.local/bin/announce-gen
+
+The script must run from the release sub-directory containing the
+release artifacts, like so:
+
+  $ cd release-X.Y.Z
+  $ announce-gen --release-type=stable --package-name=guix \
+      --previous-version=X1.Y1.Z1 --current-version=X.Y.Z \
       --gpg-key-id=MY-KEY --url-directory=https://ftp.gnu.org/gnu/guix \
-      --bootstrap-tools=autoconf,automake,makeinfo,help2man
+      --news=../NEWS
 
 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
@@ -212,9 +231,9 @@ projects.)  It must include a description of what Guix is 
(not everyone
 reading info-gnu may know about it.)  Use the text of previous
 announcements as a template.
 
-Below the initial boilerplate that describes Guile should come the
-output of `announce-gen', and then the `NEWS' file excerpt in its
-entirety (don't call it a change log since that's not what it is.)
+Below the initial [[file:announcements/savannah/about.txt]["About" section 
boilerplate]] that describes Guix
+should come the output of ~announce-gen~, which should include the
+NEWS content for the release.
 
 ** Send the email announcement