Bumping Version Numbers for New Releases in Associated Files (Documentation)

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

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:

• What version numbering scheme do you recommend?
• How do you do version numbering in an agile project?
• What version number scheme for poorly planned, branched, and schizophrenic application
• And more https://stackoverflow.com/search?q=release+numbering

What version numbering scheme do you recommend?

There are two good answers for this (plus a lot of personal preferences; see gizmo's comment on religious wars).

For public applications, the standard Major.Minor.Revision.Build works best IMO - public users can easily tell what version of the program they have and, to some degree, how far out of date their version is.

For in house applications, where the users never asked for the application, the deployment is handled by IT, and users will be calling the help desk, I found the Year.Month.Day.Build to work better in a lot of situations. This version number can thus be decoded to provide more useful information to the help desk than the public versioning number scheme.

However at the end of the day I would make one recommendation above all else - use a system you can keep consistent. If there is a system that you can setup/script your compiler to automatically use everytime, use that.

The worst thing that can happen is you releasing binaries with the same version number as the previous ones - I've recently been dealing with automated network error reports (someone elses application), and came to the conclusion that the Year.Month.Day.Build version numbers shown in the core dumps where not even remotely up to date with the application itself (the application itself used a splash screen with the real numbers - which of course where not drawn from the binary as one might assume). The result is I have no way of knowing if crash dumps are coming from a 2 year old binary (what the version number indicates) or a 2 month old binary, and thus no way of getting the right source code (no source control either!)

What version number scheme for poorly planned, branched, and schizophrenic application

Sounds to me like you don't want to use version numbers specifically.
You can use codenames, (Windows did this with each of their releases before they were released).
You basically need something more than numbers to distinguish in house which branch you are talking about. As the versions are released you can slap a Major.Minor.Revision stamp on them, but until then you need to name them in a way that will be recognizable.

Split them into branches and sub-branches.
Make sure that anything dependant on a higher branch has a derivative name.
So, you could call a branch ProductionMac, and a branch ProductionWindows, and that way you would know instantly that they are not to be merged, and that they both derive from production.

The most important thing to maintain is the structural hierarchy. Version numbers do this fairly well, but you have to keep adding "." for each new layer, which is annoying and completely undescriptive (much like naming your variables variableOne,variableTwo,variableThree) So, make sure that however you choose to label each branch, it is still obvious which branches are related to which other branches.

How to do version numbers?

[major].[minor].[release].[build]

major: Really a marketing decision. Are you ready to call the version 1.0? Does the company consider this a major version for which customers might have to pay more, or is it an update of the current major version which may be free? Less of an R&D decision and more a product decision.

minor: Starts from 0 whenever major is incremented. +1 for every version that goes public.

release: Every time you hit a development milestone and release the product, even internally (e.g. to QA), increment this. This is especially important for communication between teams in the organization. Needless to say, never release the same 'release' twice (even internally). Reset to 0 upon minor++ or major++.

build: Can be a SVN revision, I find that works best.

Examples

My current chrome: 83.0.4103.61

VB.NET Checking for existing files and assigning new Version Numbers to the name?

You are doing it right, I have a sneaking suspicion here with this line

For i = 0 To strPossibleFilename.Length 

change it to

For i = 0 To strPossibleFilename.Length -1

and then unless you kissed BillGates daughter and he's pissed off, it should work!

What does Bump Version stand for?

It means to increment the version number to a new, unique value.

How can I elegantly update the version string from autoconf in things like the man page and other non-source documents?

You can write make recipes (basically shell scripts) which build the desired files from the available information by invoking more or less common tools.

Let's start with something easy like the version number in the man page.

dnl configure.ac snippet
AC_PROG_SED

You rename the man page file doc/xnec2c.1 to doc/xnec2c.1in, so that running make can build a doc/xnec2c.1 man page with the correct version number substituted in:

.\" doc/xnec2c.1in man page snippet
This is the man page for xnec2c version @PACKAGE_VERSION@.

dnl Makefile.am or Makefile-files snippet

EXTRA_DIST += doc/xnec2c.1in
CLEANFILES += doc/xnec2c.1
man1_DATA  += doc/xnec2c.1

SED_REPLACEMENTS += -e 's|[@]PACKAGE_VERSION@|$(PACKAGE_VERSION)|g'

.1in.1:
        @$(MKDIR_P) $(@D) ||:
        $(SED) $(SED_REPLACEMENTS) < $< > $@

This is a basic recipe to get you started. Some issues it still has:

• You need to define the variables somewhere above the snippet before you can += add to them (CLEANFILES =, etc). I like the += way of defining variables very much because makes diffs which add or remove something like generating doc/xnec2c.1 from doc/xnec2c.1in much easier to read.

• When you put an invalid sed command into SED_REPLACEMENTS, running sed will fail leave behind an empty doc/xnec2c.1 file. The next make run then sees that the empty newer than doc/xnec2c.1in, skips rebuilding doc/xnec2c.1, resulting in an apparently successful build shipping an empty file as man page.

• The generated file might contain @FOOBAR@ patterns which you forgot to add to the SED_REPLACMENTS variable, and you could detect that with grep and an appropriate regexp.

• You might want to use a more generic suffix pattern for substitutions to allow e.g. substituting *.1.in to *.1, and *.spec.in to *.spec, etc. Using a pattern like %: %.in for GNU make will work here, but is not portable make. (I cannot remember off the top of my head whether .in: is the portable way to write %: %.in for all possible cases.)

Then there is the question of whether you want to put the generated file under version control or not. For simple substitutions which can be done be very standard tools like sed, you can expect the user to have that tool available and have the build work. You might not want to require your users to require a seldomly used tool, and therefore choose to put the built result under version control. I usually err on the side of requiring tools on user systems and therefore tell my version control system to ignore the generated file, because I do not want to have to deal with source controlled files changing due to me editing another source controlled file.

# .gitignore snippet
/doc/xnec2c.1

So, now we get to substituting changelogs into a HTML file. This now becomes arbitrarily complex depending on what format your changelog is in and where it is stored, and how you want to convert it to HTML.

I personally like to write text documentation such as README as README.md markdown files due to github.com rendering that nicely as HTML, so I keep my changelogs in a NEWS.md file. (Part of) that NEWS.md file could be substituted into a doc/xnec2c.md file generated from, say doc/xnec2c.md.in, and then converted from .md to .html using the markdown tool.

Then you need to have configure.ac check for the presence of and either require the user to have markdown installed, or add the generated doc/xnec2c.md file to the git index, and then deal with git suddenly noticing changed files just because you have changed the version number inside AC_INIT.

You can also rely on the version information from git tags and use a shell script to generate the AC_INIT version number from git tags by using the m4_esyscmd m4 macro. That brings its own set of benefits and drawbacks however, and is probably a bit outside the scope of this question. In the end, though, some files should directly contain the version number after all, like e.g. a NEWS or NEWS.md file detailing the user visible changes from the last version, as you will want that file to show the proper information both on github.com and in a dist tarball. So there will always be some work to update the version number inside some files.

Automatic consistency checks can be helpful here, either hooked into the all-local or check-local target, or written as a separate shell script you add to TESTS.

In a few projects I have on github.com, I use the first section of the markdown formatted user changelog NEWS.md as the github release notes, often unchanged.

There might be more elegant ways, but these are a few things which work for me in similar situations. Something is always helpful, however: Document every step in the release process so that you can just read off the list of steps the next time you need them, without needing to remember all the details inside your head.

I hope this helps, even if it probably is not very general best practise in all aspects.

How to update the version of a file?

You can use the command sed to replace strings in a file.

For example, if you have a file myfile with the following content:

// Some comments
// Version: #VERSION
// ...    

You can use the following command to replace the version number:

sed -i 's/#VERSION/123/g' myfile

The -i means inline, i.e. modify the file content.

Do not redirect the output of sed back to the same file, as in sed ... myfile > myfile as you will lose the file contents. See Redirect output from sed 's/c/d/' myFile to myFile

Result:

// Some comments
// Version: 123
// ...  

If you use Ant, this could be useful:

Use ANT to update build number and inject into source code

See also the following question related to version numbering (schemes):

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

---

Related Topics