Re: [PATCH] announce-gen: Mention git commit in release announcement.

[Paul Eggert]

On 2024-05-12 12:50, Bruno Haible wrote:


Your real goal, which is — AFAIU — to allow distros to discard part
or all of the tarball and to redo the packaging work done by the release
manager in a different way, would be better served with a
   1) machine-readable file,
   2) somewhere in or in the vicinity of the tarball.


Although that's a good goal to have (see below), it's reasonably 
ambitious. For example, the tool lists we've been mentioning are 
incomplete, partly due to indirect dependencies (no glibc?) and partly 
not (no coreutils?) and it will be a pain to complete them (no firmware 
IDs? no motherboard or CPU IDs? you get the picture...). So I suspect 
that having an intermediate goal could be worthwhile.







In other words, if you really want to go this way — against the advice that
I gave you above —, better replace the two lines with:

   This release is based on the inetutils git, available at
 https://git.savannah.gnu.org/git/inetutils.git
   commit 524d4b6934db12b9f43be410d2f201fdb40cfc97, also labelled v1.42.


This is good advice. It's similar to wording I use in announcements of 
TZDB distributions (e.g., 
).


For what it's worth, those TZDB announcements have always intended to be 
human readable but various downstream projects parse the text and grab 
checksums and signatures and whatnot. The pull of automation is indeed 
strong, and your advice about going for automation is good.

Re: [PATCH] announce-gen: Mention git commit in release announcement.

[Bruno Haible]

Hi Simon,

> including the commit hash provide some additional information that may
> be useful further down the line

That is a bit weak as a rationale. There are many additional informations
that "may be useful" to include. Isn't this move part of a bigger plan of
yours, which is to decompose release tarballs [1][2][3]?

The problem I see with your patch is that it goes into a wrong direction.
In [1], I stated my objection: The release announcement is the wrong place
to add such information. You replied "It is better than nothing, though."
No, it's not better than nothing. It increases the future costs of moving
the ship into the right direction. The longer one has been sailing in the
wrong direction, the more costly it becomes to sail to the real goal.

More precisely, the release announcement is
  1) written for humans, not meant to be machine-readable,
  2) published on a different channel than tarballs.
Your real goal, which is — AFAIU — to allow distros to discard part
or all of the tarball and to redo the packaging work done by the release
manager in a different way, would be better served with a
  1) machine-readable file,
  2) somewhere in or in the vicinity of the tarball.

That is, it would be better if you design a new file format (*), containing

  vcs:
type: git
url: https://git.savannah.gnu.org/git/libidn.git
commit: d0eb2b5a596f8bca26b0b2ccf0c70311b9819e6f
label: v1.42
  build-tools:
- gnulib
type: git
url: https://git.savannah.gnu.org/git/gnulib.git
commit: aacceb6eff58eba91290d930ea9b8275699057cf
- autoconf
type: release
distributor: gnu.org
version: 2.71
- automake
type: release
distributor: gnu.org
version: 1.16.5
- bison
type: release
distributor: gnu.org
version: 3.8.2
- m4
type: release
distributor: gnu.org
version: 1.4.18
- makeinfo
type: release
distributor: gnu.org
version: 6.8
- help2man
type: release
distributor: gnu.org
version: 1.49.1
- make
type: release
distributor: gnu.org
version: 4.3
- gzip
type: release
distributor: gnu.org
version: 1.10
- tar
type: release
distributor: gnu.org
version: 1.34

Then call that file format the "metainfo" of the release, and either
  - include a .tarball-metainfo in the tarball itself. (Some packages
already have a .tarball-version.)
or
  - formulate a convention that this file be available on the same ftp
server, under the name PACKAGE.metainfo, next to PACKAGE.tar.gz.

(*) My example uses YAML syntax, but JSON or XML would be just as good.

> and turn that into this:
> 
> This release was built bootstrapped with the following tools
> using inetutils git commit 524d4b6934db12b9f43be410d2f201fdb40cfc97:
> 
>   Gnulib aacceb6eff
>   Autoconf 2.71
>   Automake 1.16.5
>   Bison 3.8.2
>   M4 1.4.18
>   Makeinfo 6.8
>   Help2man 1.49.1
>   Make 4.3
>   Gzip 1.10
>   Tar 1.34
> 
> Does this make sense?

As a naïve user, I would have two thoughts:

  * Why is he telling me a git commit this way? Has he not heard of
"git tag" and "git push --tags"?

  * Why do you make my brain jump from the tools to the commit id and then
back again to the tools?

In other words, if you really want to go this way — against the advice that
I gave you above —, better replace the two lines with:

  This release is based on the inetutils git, available at
https://git.savannah.gnu.org/git/inetutils.git
  commit 524d4b6934db12b9f43be410d2f201fdb40cfc97, also labelled v1.42.
  The release tarball was built using the following tools:

Bruno

[1] https://lists.gnu.org/archive/html/bug-gnulib/2024-04/msg00242.html
[2] https://lists.gnu.org/archive/html/bug-gnulib/2024-04/msg00431.html
[3] https://lists.gnu.org/archive/html/bug-gnulib/2024-05/msg00124.html

Re: [PATCH] announce-gen: Mention git commit in release announcement.

[Paul Eggert]

On 2024-05-12 09:27, Jim Meyering wrote:

I like it. Wording and placement are spot on.


Looks good to me too.

I at first thought to suggest adding announce-gen's own version number 
to the announcement (to help people who want to check the announcement 
itself), but there's no need as it's derivable from Gnulib's version number.

Re: [PATCH] announce-gen: Mention git commit in release announcement.

[Jim Meyering]

I like it. Wording and placement are spot on.

Thanks.

On Sun, May 12, 2024, 08:42 Simon Josefsson via Gnulib discussion list <
bug-gnulib@gnu.org> wrote:

> All,
>
> Our release announcements does not mention the git commit hash that was
> used to prepare the release.  While SHA1 is broken, I still think
> including the commit hash provide some additional information that may
> be useful further down the line, and hopefully including doesn't incur
> too much cognitive load on the reader (that isn't already present..).
>
> I haven't pushed the attached patch since I'm not a native speaker.
> Could someone suggest better wording, if needed?  Or better placement in
> the announcement?
>
> To read the result of the patch in context, take some earlier
> announcement:
>
> https://lists.gnu.org/archive/html/info-gnu/2024-03/msg6.html
>
> and then consider that the patch would turn the following snippet (for a
> hypothethical upcoming GNU inetutils release) text:
>
> This release was bootstrapped with the following tools:
>   Gnulib aacceb6eff
>   Autoconf 2.71
>   Automake 1.16.5
>   Bison 3.8.2
>   M4 1.4.18
>   Makeinfo 6.8
>   Help2man 1.49.1
>   Make 4.3
>   Gzip 1.10
>   Tar 1.34
>
> and turn that into this:
>
> This release was built bootstrapped with the following tools
> using inetutils git commit 524d4b6934db12b9f43be410d2f201fdb40cfc97:
>
>   Gnulib aacceb6eff
>   Autoconf 2.71
>   Automake 1.16.5
>   Bison 3.8.2
>   M4 1.4.18
>   Makeinfo 6.8
>   Help2man 1.49.1
>   Make 4.3
>   Gzip 1.10
>   Tar 1.34
>
> Does this make sense?  Is the location in the announcement e-mail a good
> one?  This hides it a bit further down which I think makes sense.  Few
> readers care about git commit and bootstrapping versions, and the
> information is related.  The new version adds an empty line which I
> think is more consistent with the other paragraphs.
>
> Thoughts?
>
> /Simon
>

[PATCH] announce-gen: Mention git commit in release announcement.

[Simon Josefsson via Gnulib discussion list]

All,

Our release announcements does not mention the git commit hash that was
used to prepare the release.  While SHA1 is broken, I still think
including the commit hash provide some additional information that may
be useful further down the line, and hopefully including doesn't incur
too much cognitive load on the reader (that isn't already present..).

I haven't pushed the attached patch since I'm not a native speaker.
Could someone suggest better wording, if needed?  Or better placement in
the announcement?

To read the result of the patch in context, take some earlier
announcement:

https://lists.gnu.org/archive/html/info-gnu/2024-03/msg6.html

and then consider that the patch would turn the following snippet (for a
hypothethical upcoming GNU inetutils release) text:

This release was bootstrapped with the following tools:
  Gnulib aacceb6eff
  Autoconf 2.71
  Automake 1.16.5
  Bison 3.8.2
  M4 1.4.18
  Makeinfo 6.8
  Help2man 1.49.1
  Make 4.3
  Gzip 1.10
  Tar 1.34

and turn that into this:

This release was built bootstrapped with the following tools
using inetutils git commit 524d4b6934db12b9f43be410d2f201fdb40cfc97:

  Gnulib aacceb6eff
  Autoconf 2.71
  Automake 1.16.5
  Bison 3.8.2
  M4 1.4.18
  Makeinfo 6.8
  Help2man 1.49.1
  Make 4.3
  Gzip 1.10
  Tar 1.34

Does this make sense?  Is the location in the announcement e-mail a good
one?  This hides it a bit further down which I think makes sense.  Few
readers care about git commit and bootstrapping versions, and the
information is related.  The new version adds an empty line which I
think is more consistent with the other paragraphs.

Thoughts?

/Simon
From 8be372e8ddfaa5b7202e2b58b22e55c00d9016c5 Mon Sep 17 00:00:00 2001
From: Simon Josefsson 
Date: Sun, 12 May 2024 17:31:51 +0200
Subject: [PATCH] announce-gen: Mention git commit in release announcement.

* build-aux/announce-gen (this_commit_hash): New variable.
(main): Print commit hash.
---
 ChangeLog  | 6 ++
 build-aux/announce-gen | 6 --
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b6aa21d7f7..20dbe3c2a3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-05-12  Simon Josefsson  
+
+	announce-gen: Mention git commit in release announcement.
+	* build-aux/announce-gen (this_commit_hash): New variable.
+	(main): Print commit hash.
+
 2024-05-12  Simon Josefsson  
 
 	maintainer-makefile: Silence announce-gen error with GNULIB_REVISION.
diff --git a/build-aux/announce-gen b/build-aux/announce-gen
index f9e20129dd..3d47ceb9a7 100755
--- a/build-aux/announce-gen
+++ b/build-aux/announce-gen
@@ -35,7 +35,7 @@
 eval 'exec perl -wSx "$0" "$@"'
  if 0;
 
-my $VERSION = '2023-12-29 18:26'; # UTC
+my $VERSION = '2024-05-12 15:30'; # 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
@@ -551,6 +551,8 @@ EOF
   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 $this_commit_hash = `git log --pretty=%H -1 "v$v1"`;
+  chop $this_commit_hash;
   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;
@@ -672,7 +674,7 @@ EOF
 
   my @tool_versions = get_tool_versions (\@tool_list, $gnulib_version);
   @tool_versions
-and print "\nThis release was bootstrapped with the following tools:",
+and print "\nThis release was built bootstrapped with the following tools\nusing $package_name git commit $this_commit_hash:\n",
   join ('', map {"\n  $_"} @tool_versions), "\n";
 
   print_news_deltas ($_, $prev_version, $curr_version)
-- 
2.41.0



signature.asc
Description: PGP signature