When the maintainer has decided about the version number for the next build (and likely also the next tarball), they implement that decision by storing this version number in a file named .tarball-version at the top level of the package. This is a simple one-line text file.
The maintainer can, alternatively, decide to let the git version be the version number. To implement this choice, they remove the file .tarball-version at the top level of the package.
The actual version number comes from an invocation of
the program git-version-gen
,
part of the Gnulib module git-version-gen
.
It looks at the file .tarball-version, if that exists,
and at the current checkout, otherwise.
The file .tarball-version should not be put under version control.
Therefore you may want to list it
in the package’s top-level .gitignore
file.
But you need a Makefile.am
rule that will
make sure that .tarball-version will exist in distribution tarballs:
dist-hook: dist-tarball-version .PHONY: dist-tarball-version dist-tarball-version: echo '$(VERSION)' > $(distdir)/.tarball-version
Typically, the maintainer will set the version number in a clean directory
(i.e. after “make distclean”).
In order to adapt to alternative workflows,
the file GNUmakefile, part of the Gnulib module gnumakefile
,
contains a rule that will print a warning or possibly call autoreconf
if it finds that the version has changed but has not yet been propagated.
Reminder: Not every package supports autoreconf
.