Bumping version numbers for new releases in associated files (documentation)

Question

I would be interested to in knowing how you out there handle the bumping the version number for new releases issue.

How do you handle the version number in associated files like man pages, etc.

The software is build with the gnu tool chain so autoconf, automake, etc are available and used for the version number of the application. So that information can be reused.

git is used as a vcs.

One possibility would be introduce an extra, new target in Makefile.am that does a sed/awk to replace version number and dates in all associated files. That target could be called once at the beginning (right after branching) of the development of a new release.

Then the project could build with the correct information when people would do a git clone of the project or when a release tarball is done. Of course one has to remember to run this make target when starting development of a new release.

Another option would be to do the sed/awk replacement with a hook for the dist target.But this would put the git repository of the project in a state were no correct version number is associated with the associated files.

I prefer doing the first solution as it also records the correct version number inside the git history.

When doing a sed/awk replacement do you prefer doing it "in-file" or with a template in-file liek the autoconf/automake tools do. I see both advantages and disadvantages in both methods.

How do you handle versioning of associated files. Do you change them at the beginning of the development phase, do you change them when just before shipping, do you do infile replacement or do you prefer using a template?

THX.

Answer 1

I think that the standard way to do this is to use Git's hook system and m4 or sed/awk to do the search/replace as you suggest. You just need a special token with in a comment in each file (probably in the header).

Here's the reference on githooks and here's a few pages written by people solving the same problem:

• http://groups.google.com/group/memcached/browse_thread/thread/b02e992ede0f0e89
• http://blog.rfwatson.net/2009/06/03/automatic-version-numbering-using-git/

Both of these rely on storing the version number in a file somewhere in your source tree.

I also came across a took called 0release that claims to automate release creation (and setting version numbers).

Finally, regarding release numbers, this is addressed in several other questions:

• http://stackoverflow.com/questions/121795/what-version-numbering-scheme-do-you-recommend
• http://stackoverflow.com/questions/483122/how-do-you-do-version-numbering-in-an-agile-project
• http://stackoverflow.com/questions/850064/what-version-number-scheme-for-poorly-planned-branched-and-schizophrenic-applic
• And more http://stackoverflow.com/search?q=release+numbering

Answer 2

We use the classic major.minor.patch system, which gets applied to release candidates as a 'tag', we have a script which tags a commit as the version number, rather than use a git 'tag object'. All the version numbering is done 'by hand'. It works reasonably well, because the version number is created by the 'release onto staging' scripts, which is much later on in the development process. We don't bother using any of the git hooks, because we don't really need to, if a commit isn't leaving the development environment then it doesn't need id other than it's internal SHA code.

We try to enforce that every 'patch' release must be binary compatible with other versions with the same major,minor tag.

That way, anything with a tag should at least build, but it's possible or quite likely that it won't work to spec.

A refinement would be to get the QA department to create a signed tag object on anything that is 'QA approved' but for now we rely on other paperwork for that.

Answer 3

A common solution nowadays is to invoke AC_INIT with an m4_esyscmd argument to generate the VERSION from git. For example, autoconf's configure.ac contains the lines:

AC_INIT([GNU Autoconf],
        m4_esyscmd([build-aux/git-version-gen .tarball-version]),
        [[email protected]])

where build-aux/git-version-gen is a simple script that calls 'git describe' to generate the version number. (see gnulib)

There are drawbacks to this approach, but it can be effective.