Hi Simon,
> Maybe a doc/git-version-gen.texi is the answer here... and thinking
> through the concepts a bit more.
Let me start doing that.
First, what is the current status?
* The files:
- .tarball-version contains the version the maintainer wishes "make dist"
to produce — or, if absent, the maintainer is OK with a "smart" naming
scheme that depends on the git commit.
- .version is a timestamp file that is used for determining whether to
rebuild files that contain a version and that are expensive to rebuild
(such a the man pages and, in gettext, the manual).
* The workflow:
1) The maintainer creates or removes '.tarball-version'.
2) At configure time, '.git-version-gen .tarball-version' is called.
It determines an Autoconf macro named VERSION and stores its value
in config.status and various Makefiles.
3) The Makefile rules that use $(VERSION) are supposed to fall into two
categories:
- those that rebuild their target always,
- those that rebuild their target only if '.version' is newer.
The man pages are in the latter category, because they are generated
via help2man when not cross-compiling. The result is saved for the
cross-compiled situation; that's why "make distclean" does not erase it.
Next, what are the problems?
* There is a .version file in tarballs, that reveals the version of the
previous testing release the maintainer made in the same directory.
This is
- unintented (a privacy violation),
- not reproducible.
* Some of the files that depend on .version have not been remade:
- In coreutils 7.6:
.TH CP "1" "September 2009" "GNU coreutils 7.5.88-dd7f8" "User Commands"
.TH WHO "1" "September 2009" "GNU coreutils 7.5.88-dd7f8" "User Commands"
- In gettext 0.21:
.TH MSGEXEC "1" "July 2020" "GNU gettext-tools 20200704" "User Commands"
.TH GETTEXT 3 "May 2001" "GNU gettext 0.20.1.124-32cf"
So, this version of the previous testing release has now not only leaked into
the tarball, but also into documentation that the maintainer will publish
on www.gnu.org.
A fix to the first problem would be easy. I checked coreutils and gettext;
they never use the contents of '.version'. Therefore, changing the lines
$(top_srcdir)/.version:
echo $(VERSION) > $@-t && mv $@-t $@
to
$(top_srcdir)/.version:
echo timestamp > $@-t && mv $@-t $@
would fix this problem.
But the second problem still indicates that there's a loophole: it's
too easy for a maintainer to produce a tarball with an out-of-date version
in man pages.
> if it is possible to find a 'make release' workflow that
> create incorrect .version and/or .tarball-version files we should fix
> that. Or tighten up README-release.
Yes. Every package has its own "make release" workflow or README-release.
But the use of '.version' and the resulting out-of-date manpages mistake
are common among coreutils and gettext.
Bruno
