Re: .version and .tarball-version

[Bruno Haible]

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