FYI: announce-gen: add more info to the auto-generated announce template

FYI: announce-gen: add more info to the auto-generated announce template

[Jim Meyering]

[-- Attachment #1: Type: text/plain, Size: 3920 bytes --]

Whenever one makes a release of a package using maint.mk, part of that
process creates a file named e.g., announce-grep-3.8 in your home
directory. Upon a recent request by Simon, I've adjusted the
generating code to include more information in that template. I've
been using some variant of this for years.

    announce-gen: add more info to the auto-generated announce template

    * build-aux/announce-gen (readable_interval, readable_interval0):
    New functions.
    (digest_file_base64_wrap): New function to add padding to the
    base64-encoded SHA256 checksums.
    (print_checksums): Use that wrapper. Indent each line by two spaces.
    (main): Emit new sections, e.g., these lines from grep-3.8's release:
    - There have been 104 commits by 6 people in the 55 weeks since 3.7.
    - The following people contributed changes to this release: (and list)
    I tested with this, running from a sibling cloned grep directory:
      ../gnulib/build-aux/announce-gen --release-type=stable \
        --package-name=grep --previous-version=3.7 --current-version=3.8 \
        --gpg-key-id=0x7FD9FCCB000BEEEE --url-directory=https://testing
    Also, reference the cksum programs from coreutils-9.2 and from OpenBSD.

Here's the full output from the sample command above:

Subject: grep-3.8 released [stable]

<#secure method=pgpmime mode=sign>
This is to announce grep-3.8, a stable release.

FIXME: put comments here

There have been 104 commits by 6 people in the 55 weeks since 3.7.

See the NEWS below for a brief summary.

Thanks to everyone who has contributed!
The following people contributed changes to this release:

  Carlo Marcelo Arenas Belón (2)
  Helge Kreutzmann (1)
  Jim Meyering (27)
  Ondřej Fiala (1)
  Paul Eggert (71)
  Ulrich Eckhardt (2)

Jim
 [on behalf of the grep maintainers]
==================================================================

Here is the GNU grep home page:
    http://gnu.org/s/grep/

For a summary of changes and contributors, see:
  http://git.sv.gnu.org/gitweb/?p=grep.git;a=shortlog;h=v3.8
or run this command from a git-cloned grep directory:
  git shortlog v3.7..v3.8

Here are the compressed sources:
  https://test/grep-3.8.tar.gz   (2.8MB)
  https://test/grep-3.8.tar.xz   (1.7MB)

Here are the GPG detached signatures:
  https://test/grep-3.8.tar.gz.sig
  https://test/grep-3.8.tar.xz.sig

Here are the SHA1 and SHA256 checksums:

  eb3bf741fefb2d64e67d9ea6d74c723ea0efddb6  grep-3.8.tar.gz
  jeYKUWnAwf3YFwvZO72ldbh7/Pp95jGbi9YNwgvi+5c=  grep-3.8.tar.gz
  6d0d32cabaf44efac9e1d2c449eb041525c54b2e  grep-3.8.tar.xz
  SY18wbT7CBkE2HND/rtzR1z3ceQk+35hQa/2YBOrw4I=  grep-3.8.tar.xz

Verify the base64 SHA256 checksum with cksum -a sha256 --check
from coreutils-9.2 or openBSD's cksum since 2007.

Use a .sig file to verify that the corresponding file (without the
.sig suffix) is intact.  First, be sure to download both the .sig file
and the corresponding tarball.  Then, run a command like this:

  gpg --verify grep-3.8.tar.gz.sig

The signature should match the fingerprint of the following key:

  pub   rsa4096/0x7FD9FCCB000BEEEE 2010-06-14 [SCEA]
        Key fingerprint = 155D 3FC5 00C8 3448 6D1E  EA67 7FD9 FCCB 000B EEEE
  uid                   [ unknown] Jim Meyering <jim@meyering.net>
  uid                   [ unknown] Jim Meyering <meyering@fb.com>
  uid                   [ unknown] Jim Meyering <meyering@gnu.org>

If that command fails because you don't have the required public key,
or that public key has expired, try the following commands to retrieve
or refresh it, and then rerun the 'gpg --verify' command.

  gpg --recv-keys 0x7FD9FCCB000BEEEE

As a last resort to find the key, you can try the official GNU
keyring:

  wget -q https://ftp.gnu.org/gnu/gnu-keyring.gpg
  gpg --keyring gnu-keyring.gpg --verify grep-3.8.tar.gz.sig

[-- Attachment #2: announce-gen.diff --]
[-- Type: application/octet-stream, Size: 6917 bytes --]

From f4108bb802770feed541f4b168aebbea45146ede Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@fb.com>
Date: Sat, 25 Feb 2023 13:20:43 -0800
Subject: [PATCH] announce-gen: add more info the auto-generated announce
 template

* build-aux/announce-gen (readable_interval, readable_interval0):
New functions.
(digest_file_base64_wrap): New function to add padding to the
base64-encoded SHA256 checksums.
(print_checksums): Use that wrapper. Indent each line by two spaces.
(main): Emit new sections, e.g., these lines from grep-3.8's release:
- There have been 104 commits by 6 people in the 55 weeks since 3.7.
- The following people contributed changes to this release: (and list)
I tested with this, running from a sibling cloned grep directory:
  ../gnulib/build-aux/announce-gen --release-type=stable \
    --package-name=grep --previous-version=3.7 --current-version=3.8 \
    --gpg-key-id=0x7FD9FCCB000BEEEE --url-directory=https://testing
Also, reference the cksum programs from coreutils-9.2 and from OpenBSD.
---
 ChangeLog              | 17 ++++++++
 build-aux/announce-gen | 92 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 103 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e8a49c247a..3d8446ce5c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2023-02-25  Jim Meyering  <meyering@fb.com>
+
+	announce-gen: add more info the auto-generated announce template
+	* build-aux/announce-gen (readable_interval, readable_interval0):
+	New functions.
+	(digest_file_base64_wrap): New function to add padding to the
+	base64-encoded SHA256 checksums.
+	(print_checksums): Use that wrapper. Indent each line by two spaces.
+	(main): Emit new sections, e.g., these lines from grep-3.8's release:
+	- There have been 104 commits by 6 people in the 55 weeks since 3.7.
+	- The following people contributed changes to this release: (and list)
+	I tested with this, running from a sibling cloned grep directory:
+	  ../gnulib/build-aux/announce-gen --release-type=stable \
+	    --package-name=grep --previous-version=3.7 --current-version=3.8 \
+	    --gpg-key-id=0x7FD9FCCB000BEEEE --url-directory=https://testing
+	Also, reference the cksum programs from coreutils-9.2 and from OpenBSD.
+
 2023-02-25  ChuanGang Jiang  <jiangchuanganghw@outlook.com>  (tiny change)

 	terminfo, termcap: Fix typos in comments.
diff --git a/build-aux/announce-gen b/build-aux/announce-gen
index 6bf48e1b02..e51a8a78c1 100755
--- a/build-aux/announce-gen
+++ b/build-aux/announce-gen
@@ -35,7 +35,7 @@
 eval 'exec perl -wSx "$0" "$@"'
      if 0;

-my $VERSION = '2022-07-10 01:47'; # UTC
+my $VERSION = '2023-02-25 21:13'; # UTC
 # The definition above must lie within the first 8 lines in order
 # for the Emacs time-stamp write hook (at end) to update it.
 # If you change this file with Emacs, please let the write hook
@@ -165,6 +165,17 @@ Print the SHA1 and SHA256 signature section for each C<@file>.

 =cut

+# This digest function omits the "=" padding that is required by cksum,
+# so add the 0..2 bytes of padding required for each of Digest's algorithms.
+sub digest_file_base64_wrap ($$)
+{
+  my ($file, $alg) = @_;
+  my $h = digest_file_base64($file, $alg);
+  $alg =~ tr{-}{}d;
+  my %pad = (MD5 => 2, SHA1 => 1, SHA256 => 1, SHA384 => 0, SHA512 => 2);
+  return $h . '=' x $pad{$alg};
+}
+
 sub print_checksums (@)
 {
   my (@file) = @_;
@@ -176,11 +187,11 @@ sub print_checksums (@)

   foreach my $f (@file)
     {
-      print digest_file_hex($f, "SHA-1"), "  $f\n";
-      print digest_file_base64($f, "SHA-256"), "  $f\n";
+      print '  ', digest_file_hex ($f, "SHA-1"), "  $f\n";
+      print '  ', digest_file_base64_wrap ($f, "SHA-256"), "  $f\n";
     }
-  print "\nThe SHA256 checksum is base64 encoded, instead of the\n";
-  print "hexadecimal encoding that most checksum tools default to.\n\n";
+  print "\nVerify the base64 SHA256 checksum with cksum -a sha256 --check\n";
+  print "from coreutils-9.2 or openBSD's cksum since 2007.\n\n";
 }

 =item C<print_news_deltas ($news_file, $prev_version, $curr_version)
@@ -365,6 +376,38 @@ sub get_tool_versions ($$)
   return @tool_version_pair;
 }

+# Print a more human-friendly representation of $SEC seconds.
+sub readable_interval0($)
+{
+  my $sec = shift;
+  $sec < 60 and return "$sec seconds";
+
+  my $min = int($sec / 60); $sec %= 60;
+  30 < $sec and $min++;
+  $min < 60 and return "$min minutes";
+
+  my $hr = int($min / 60); $min %= 60;
+  30 < $min and $hr++;
+  $hr < 24 and return "$hr hours";
+
+  my $day = int($hr / 24); $hr %= 24;
+  12 < $hr and $day++;
+  $day < 50 and return "$day days";
+
+  my $wk = int($day / 7); $day %= 7;
+  4 < $day and $wk++;
+  return "$wk weeks";
+}
+
+# Convert e.g., "1 weeks", to "1 week".
+sub readable_interval($)
+{
+  my $interval_str = shift;
+  my $i = readable_interval0 $interval_str;
+  $i =~ m{^1 \w+s$} and chop $i;
+  return $i;
+}
+
 {
   # Use the C locale so that, for instance, "du" does not
   # print "1,2" instead of "1.2", which would confuse our regexps.
@@ -493,9 +536,47 @@ sub get_tool_versions ($$)
 ${headers}Subject: $my_distdir released [$release_type]

 <\#secure method=pgpmime mode=sign>
+This is to announce $package_name-$curr_version, a $release_type release.

 FIXME: put comments here

+EOF
+
+  my $v0 = $prev_version;
+  my $v1 = $curr_version;
+
+  (my $first_name = `git config --global user.name|cut -d' ' -f1`)
+    =~ m{\S} or die "no name? set user.name in ~/.gitconfig\n";
+
+  chomp (my $n_ci = `git rev-list "v$v0..v$v1" | wc -l`);
+  chomp (my $n_p = `git shortlog "v$v0..v$v1" | grep -c '^[^ ]'`);
+
+  my $prev_release_date = `git log --pretty=%ct -1 "v$v0"`;
+  my $this_release_date = `git log --pretty=%ct -1 "v$v1"`;
+  my $n_seconds = $this_release_date - $prev_release_date;
+  my $time_since_prev = readable_interval $n_seconds;
+  my $names = `git shortlog "v$v0..v$v1"|perl -lne '/^(\\w.*):/ and print "  ".\$1'`;
+
+  print <<EOF;
+There have been $n_ci commits by $n_p people in the $time_since_prev since $v0.
+
+See the NEWS below for a brief summary.
+
+Thanks to everyone who has contributed!
+The following people contributed changes to this release:
+
+$names
+$first_name [on behalf of the $package_name maintainers]
+==================================================================
+
+Here is the GNU $package_name home page:
+    http://gnu.org/s/$package_name/
+
+For a summary of changes and contributors, see:
+  http://git.sv.gnu.org/gitweb/?p=$package_name.git;a=shortlog;h=v$v1
+or run this command from a git-cloned $package_name directory:
+  git shortlog v$v0..v$v1
+
 EOF

   if (@url_dir_list == 1 && @tarballs == 1)
@@ -587,7 +668,6 @@ keyring:

   wget -q https://ftp.gnu.org/gnu/gnu-keyring.gpg
   gpg --keyring gnu-keyring.gpg --verify $tarballs[0].sig
-
 EOF

   my @tool_versions = get_tool_versions (\@tool_list, $gnulib_version);
-- 
2.39.2.501.gd9d677b2d8

Re: FYI: announce-gen: add more info to the auto-generated announce template

[Bruno Haible]

Jim Meyering wrote:
> from coreutils-9.2 or openBSD's cksum since 2007.

It's the first time I see OpenBSD spelled this way. Why not use an
uppercase 'O', like they do themselves [1] ?

Bruno

[1] http://www.openbsd.org/

Re: FYI: announce-gen: add more info to the auto-generated announce template

[Jim Meyering]

On Sat, Feb 25, 2023 at 11:56 PM Bruno Haible <bruno@clisp.org> wrote:
> Jim Meyering wrote:
> > from coreutils-9.2 or openBSD's cksum since 2007.
>
> It's the first time I see OpenBSD spelled this way. Why not use an
> uppercase 'O', like they do themselves [1] ?

Thanks. Corrected.