[PATCH v2] Integrate git-version-gen.

[Arsen Arsenović]

* etc/hacking.org (Building Release Tarballs): Add some notes
about how to get correct versioning information.
* configure.ac: Invoke git-version-gen to compute version value.
* bootstrap.conf (gnulib_modules): Add git-version-gen.
* Makefile.am (EXTRA_DIST): Add ``.version''.
(BUILT_SOURCES): Ditto.
($(top_srcdir)/.version): store current $(VERSION) value.
(dist-hook): Store version as .tarball-version.
* .gitignore: Ignore .version
* HACKING: Regenerate.
---
Evening,

This patchset includes the changes discussed on IRC and a little bit of
extended documentation.  If this looks OK, please apply when you feel it
appropriate to do so, as part of a release.

 .gitignore      |  1 +
 ChangeLog       | 14 ++++++++++++++
 HACKING         | 15 +++++++++++++++
 Makefile.am     | 11 ++++++++++-
 bootstrap.conf  |  1 +
 configure.ac    | 33 ++++++++++++++++++++++++++++++++-
 etc/hacking.org | 25 +++++++++++++++++++++++++
 7 files changed, 98 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index bdd339c4..cdbcec19 100644
--- a/.gitignore
+++ b/.gitignore
@@ -85,6 +85,7 @@ config.h.in
 /poke.pc.in
 /poke-uninstalled.pc
 /poke-uninstalled.sh
+/.version
 
 ## Tag files created by ctags
 tags
diff --git a/ChangeLog b/ChangeLog
index 0c677c14..821f0718 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -73,6 +73,20 @@
 
        * poked/poked.c (poked_version): Don't use year range.
 
+2023-01-24  Arsen Arsenović  <arsen@aarsen.me>
+
+       Integrate git-version-gen.
+       * etc/hacking.org (Building Release Tarballs): Add some notes
+       about how to get correct versioning information.
+       * configure.ac: Invoke git-version-gen to compute version value.
+       * bootstrap.conf (gnulib_modules): Add git-version-gen.
+       * Makefile.am (EXTRA_DIST): Add ``.version''.
+       (BUILT_SOURCES): Ditto.
+       ($(top_srcdir)/.version): store current $(VERSION) value.
+       (dist-hook): Store version as .tarball-version.
+       * .gitignore: Ignore .version
+       * HACKING: Regenerate.
+
 2023-01-23  Jose E. Marchesi  <jemarch@gnu.org>
 
        * libpoke/pvm.jitter (PVM_BINOP_SL): Do not trigger left-shit UB.
diff --git a/HACKING b/HACKING
index 123dbc57..5325092d 100644
--- a/HACKING
+++ b/HACKING
@@ -234,6 +234,21 @@ with GNU poke.  If not, see 
<https://www.gnu.org/licenses/>.
   The standard target `make distcheck' builds a distributable sources
   tarball, and tests that it can be built and tested properly.
 
+  Note that if you're working on a checkout that is not fresh (i.e. it
+  has had commits or tags since you last ran `./autogen.sh'), it is
+  desirable to re-run `./autogen.sh', or otherwise regenerate
+  `configure', to get updated version information.  This version will be
+  stored in the newly-generated dist tarball.
+
+  Keep in mind that, when regenerating, a dirty tree, including
+  differently dated submodules, will cause the version to be suffixed
+  with `-dirty'.  Should this happen, and you want to go through with
+  the release anyway, `git stash' your changes and `git submodule
+  update' submodules, so that they get checked out to in-tree revisions.
+  This also ensures that you're testing the version of the tree that
+  will make it into a release, rather than something with a potentially
+  uncommitted fix, or suchlike.
+
 
 2.6 Installing Obvious Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Makefile.am b/Makefile.am
index 83bce1ac..d402da0b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -19,7 +19,8 @@ ACLOCAL_AMFLAGS = -I m4 -I m4/libpoke
 SUBDIRS = jitter gl maps pickles gl-libpoke libpoke poke poked utils \
           doc man testsuite etc po
 
-EXTRA_DIST = INSTALL.generic DEPENDENCIES
+EXTRA_DIST = INSTALL.generic DEPENDENCIES $(top_srcdir)/.version
+BUILT_SOURCES = $(top_srcdir)/.version
 
 noinst_SCRIPTS = run
 
@@ -47,4 +48,12 @@ update-hacking:
        emacs ${srcdir}/etc/hacking.org --batch -f org-ascii-export-to-ascii 
--kill
        mv -f ${srcdir}/etc/hacking.txt ${srcdir}/HACKING
 
+# Support for git-version-gen
+$(top_srcdir)/.version: $(top_srcdir)/configure
+       echo '$(VERSION)' > $@-t
+       mv $@-t $@
+
+dist-hook:
+       echo '$(VERSION)' > $(distdir)/.tarball-version
+
 .PHONY = update-hacking
diff --git a/bootstrap.conf b/bootstrap.conf
index abd82a1b..4990defa 100644
--- a/bootstrap.conf
+++ b/bootstrap.conf
@@ -33,6 +33,7 @@ gnulib_modules="
   getline
   getsockname
   getopt-gnu
+  git-version-gen
   glob
   host-cpu-c-abi
   isatty
diff --git a/configure.ac b/configure.ac
index 3c98032a..2ed024eb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -18,7 +18,38 @@ dnl
 dnl You should have received a copy of the GNU General Public License
 dnl along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-AC_INIT([GNU poke], [2.90.1], [poke-devel@gnu.org], [poke],
+dnl Branch-specific suffix to apply to the version, to disambiguate it from
+dnl other branches.  master and maint/poke-* are treated special in that they
+dnl get a short description, where all other branches get emitted in full.
+m4_define([poke_branch],
+         [m4_esyscmd_s([git tag --points-at HEAD 2>/dev/null | grep -q . \
+                            || { git branch --show-current                \
+                                     | sed 's|^maint/poke-.*|maint|;
+                                            s|^master$|dev|'; }])])
+
+
+dnl Version generated from a Git tag via git-version-gen.  To understand the
+dnl following mess, it is integral to know that ``:'' is special in Git and
+dnl will never be emitted.  We (ab)use this fact to escape the ``-g'', which is
+dnl another special construct in Git - used by git-describe output to delimit
+dnl the object reference from data for human consumption.
+dnl We also rely on this fact and choose ``:'' as a safe sed delimiter.
+dnl After we escape -g, and sufficiently mangle the describe output in order to
+dnl shove the branch name into the middle of it, we convert the escape ``:''
+dnl back into a ``g'', so that we end up with a git-showable reference (unless
+dnl the tree is -dirty).
+
+m4_define([poke_version], [m4_esyscmd_s([
+    build-aux/git-version-gen .tarball-version                            \
+        --prefix 'releases\/poke-'                                        \
+        
's:^\(releases/poke-\)\([^-]*\)-\([^-]*\)\(-g.*\):\1\2-]poke_branch()-[\3\4:;
+         s:g\([[:xdigit:]]\+\)$:\:\1:'                                    \
+      | sed 's/:/g/'
+])])
+
+AC_INIT([GNU poke],
+        [poke_version()],
+       [poke-devel@gnu.org], [poke],
         [http://www.jemarch.net/poke.html])
 
 AC_CONFIG_AUX_DIR([build-aux])
diff --git a/etc/hacking.org b/etc/hacking.org
index 98f5c9bf..12f41fb0 100644
--- a/etc/hacking.org
+++ b/etc/hacking.org
@@ -110,6 +110,31 @@ Arsen Arsenović            <arsen@aarsen.me>
    The standard target =make distcheck= builds a distributable sources
    tarball, and tests that it can be built and tested properly.
 
+   The version information the package gets built against is
+   automatically determined from git, based on =git describe= output
+   and the current branch.  The format for versions generated like this
+   is: =X.Y[.Z]-BRANCH-NN-gHASH= for an inter-version build, and
+   =X.Y[.Z]= for a release.  In either case, if the tree you're
+   building is not clean, you will get a =-dirty= suffix.
+
+   =X.Y[.Z]= gets computed from the latest annotated tag on your
+   current =HEAD= history.
+
+   Note that if you're working on a checkout that is not fresh (i.e. it
+   has had commits or tags since you last ran =./autogen.sh=), it is
+   desirable to re-run =./autogen.sh=, or otherwise regenerate
+   =configure=, to get updated version information.  This version will
+   be stored in the newly-generated dist tarball.
+
+   Keep in mind that, when regenerating, a dirty (i.e. modified) tree,
+   including differently dated submodules, will cause the version to be
+   suffixed with =-dirty=.  Should this happen, and you want to go
+   through with the release anyway, =git stash= your changes and =git
+   submodule update= submodules, so that they get checked out to
+   in-tree revisions.  This also ensures that you're testing the
+   version of the tree that will make it into a release, rather than
+   something with a potentially uncommitted fix, or suchlike.
+
 ** Installing Obvious Changes
 
    Anyone having write access to the git repository is allowed to push
-- 
2.39.1