Re: [PATCH v2] Integrate git-version-gen.

[Jose E. Marchesi]

Hi Arsen.

Thank you for installing this.

Now, we will need a pk_version_compare function implementing <, > and ==
particularly for the new poke version strings.

An example of use is the implementation of the PK_PROG_POKE autoconf
macro.  At the moment we have this in autoconf/poke.m4:

  exit (pk_version >= "$2" ? 0 : 1);

But clearly that may easily break.



> * 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