Re: announce-gen usage feedback

[Jim Meyering]

On Sat, Jul 9, 2022 at 6:29 AM Simon Josefsson via Gnulib discussion
list <bug-gnulib@gnu.org> wrote:
>
> Bruno Haible <bruno@clisp.org> writes:
>
> > Hi Simon,
> >
> > Two remarks regarding 'announce-gen':
> >
> > 1) I used the command
> >    $ $GNULIB_SRCDIR/build-aux/announce-gen --release-type stable \
> >        --package-name libunistring --previous-version 0.9.10 \
> >        --current-version 1.0 --gpg-key-id F5BE8B267C6A406D \
> >        --url-directory https://ftp.gnu.org/gnu/libunistring \
> >        --gnulib-version=v0.1-5095-gb79766eae
> >
> > and got the error message:
> >
> >    announce-gen: when specifying gnulib as a tool, you must also specify
> >    --gnulib-version=V, where V is the result of running git describe
> >    in the gnulib source directory.
> >    Try 'announce-gen --help' for more information.
> >
> > This was confusing, as I did gave --gnulib-version but no --bootstrap-tools
> > option. To fix this error, I had to add a --bootstrap-tools=... option.
> > The error message should better have been
> >
> >    announce-gen: when specifying --gnulib-version, you must also include
> >    gnulib in the --bootstrap-tools option.
> >    Try 'announce-gen --help' for more information.
>
> Thanks for feedback -- I think this question should go to Jim though,
> since I don't recognize that code path.  Changing the --help text and/or
> the error message seems straight-forward, and I agree the wording makes
> it difficult to understand how to fix the problem, but reading the code
> makes this obvious.
>
> Hmm.  However, why can't announce-gen use 'gnulib-tool --version' to
> figure out the gnulib version?  It goes to some effort to actually try
> to output something like git version string.  Probably it didn't do that
> when announce-gen was written.  One reason against may be that
> announce-gen is useful even if someone didn't use gnulib-tool.  So how
> about announce-gen uses the same code as gnulib-tool contains to figure
> out the gnulib version?  Then --gnulib-version can be optional, for
> those situations where the default code cannot figure out the gnulib
> version.

It would allow simplifying slightly (omitting --gnulib-version=V) with
--bootstrap-tools,
but would add a tiny bit more logic in a code path that is rarely
invoked by a human.
Either way works for me.

In any case, the attached makes announce-gen give a better diagnostic
in that case.

Thanks.

> > 2) The proposed text contained these paragraphs:
> >
> >    
> > ----------------------------------------------------------------------------
> >    Here are the SHA1 and SHA256 checksums:
> >
> >    cd38e3850b2d08a55cce0380d3510e7df83c6306  libunistring-1.0.tar.gz
> >    PAGEwOSS18IIzjHSXdHSxY8MPtbLvgMsWySM3a0xhUQ  libunistring-1.0.tar.gz
> >    ebae3103346745bef3534910a5c5afbf72099b2a  libunistring-1.0.tar.xz
> >    W6tVtJ91137SayV5l+kZtpPyn9ShvCLg5uAkwkbHJ0E  libunistring-1.0.tar.xz
> >
> >    The SHA256 checksum is base64 encoded, instead of the
> >    hexadecimal encoding that most checksum tools default to.
> >    
> > ----------------------------------------------------------------------------
> >
> >    But since the 'sha256sum' command from coreutils does not have an option
> >    to display the base64 encoded SHA256 sum, and no tool I know of provides
> >    a way to convert between hexadecimal and base64 checksums, displaying
> >    a base64 encoded SHA256 sum is next to useless.
> >
> >    I ended up rewriting these paragraphs as follows:
> >
> >    
> > ----------------------------------------------------------------------------
> >    Here are the SHA1 and SHA256 checksums:
> >
> >    File: libunistring-1.0.tar.gz
> >    SHA1 sum:   cd38e3850b2d08a55cce0380d3510e7df83c6306
> >    SHA256 sum: 
> > 3c0184c0e492d7c208ce31d25dd1d2c58f0c3ed6cbbe032c5b248cddad318544
> >
> >    File: libunistring-1.0.tar.xz
> >    SHA1 sum:   ebae3103346745bef3534910a5c5afbf72099b2a
> >    SHA256 sum: 
> > 5bab55b49f75d77ed26b257997e919b693f29fd4a1bc22e0e6e024c246c72741
> >    
> > ----------------------------------------------------------------------------
> >
> >    How about doing the same in the 'announce-gen' script?
>
> Yeah...  following through after this change fell between the cracks.
> The right thing to do is to implement this in coreutils.  Having hex
> encoded sha256 checksums looks ugly in email, and going back to them now
> seems like a move in the wrong direction.

I agree.

announce-gen.diff
Description: Binary data