Re: Release management: how do you update the libtool version information?

[Bruno Haible]

Vivien Kraus wrote:
> How do you manage the libtool version information for a library using
> gnulib?

Every maintainer probably does their release management somewhat
differently. I'll say how it _can_ be done. I have no intention to
urge or even recommend any release steps.

I have two recipes, consisting of manual steps:
  - one for creating a snapshot release,
  - one for making an official release.

In the recipe for making an official release, there are several items:

** Update files:

  - version.sh (or for some packages: configure.ac)

    Update VERSION_NUMBER and RELEASE_DATE.

  - lib/Makefile.am

    Update -version-info arguments, according to libtool versioning
    (info "(libtool) Updating version info").
    Preferrably using the gnulib/build-aux/libtool-next-version program.
    Or manually, using these rules:

      * increment LTV_REVISION,
      * if any interfaces (functions/variables/classes) have been removed
        or changed [i.e. backwards compatibility has been broken],
        increment LTV_CURRENT, set LTV_REVISION to 0, set LTV_AGE to 0.
      * otherwise:
        * if any interfaces (functions/variables/classes) have been added,
          increment LTV_CURRENT, set LTV_REVISION to 0, increment LTV_AGE.

  - Update copyright years of the --version output of all programs.

  - NEWS

    Add news entries if any.

** Update translations ...

** Create a release:

  ...

  Add a git tag (an annotated tag, not a lightweight tag):

    git commit --allow-empty -m "Release $CURRENT_VERSION"
    git tag -a -m "Release $CURRENT_VERSION" v$CURRENT_VERSION

> For now, I have it written down explicitly in configure.ac.

I prefer to define these variables in lib/Makefile.am, because why would
I force a "make distclean" and re-configure run if I need the new values
in a single file only.

> Unfortunately, this requires a new commit to bump the numbers before
> each release.

Sure. Updating the package version number also requires a commit. Updating
the copyright year output of the programs also requires a commit. Updating
the NEWS file also requires a commit. Yes, preparing a release is more than
preparing a snapshot.

> Gnulib provides a script to help update the libtool version
> information. Is there a way to involve that script in the "make
> release-commit" invocation?

I wouldn't do that, for two reasons:
  - The gnulib/build-aux/libtool-next-version program asks for the locations
    of the current shared libraries (that you can prepare with a snapshot
    release, installed in, say, --prefix=/tmp/current) and of the previous
    version's shared libraries (for which there is no canonical location).
  - If you tie two different parts of the release process together, you make
    it less flexible, and you'll regret that sooner or later.

> It is a little awkward to create a commit
> just to bump the libtool version information, or to squash it with the
> commit created by "make release-commit".

Why do you feel an urge to squash commits together? Making a release has
several steps. Take the poke 3.0 release for example:
https://git.savannah.gnu.org/gitweb/?p=poke.git;a=shortlog
The preparations included
  - update gendocs_template
  - update version number
  - update gnulib submodule reference
  - NEWS formatting fixes
  - NEWS update
  - HACKING update

Bruno