After you release your software, the version number should be incremented immediately.

Why?

Let’s assume you’re following a scheme like Semantic Versioning, and you have a build number in the version. So you might have [Major].[Minor].[Patch].[Build]. I am going to call the [Major].[Minor].[Patch] part the version.

You will be creating multiple builds during development. Each build is a development snapshot of your next release. It makes sense to use the same version for your development and release builds. The version indicates what release you’re working toward.

If you’re preparing for release and the software passes all of its tests, you won’t want to rebuild and retest the software just because you had to update the version. When you eventually make a release, you are stating that “build 1.1.0.23” shall henceforth be referred to as “version 1.1.0”.

The increment-after-release model makes sense for branching too. Suppose you have a mainline development branch, and you create maintenance branches for releases. The moment you create your release branch, your development branch is no longer linked to that release’s version number. The development branch contains code that is part of the next release, so the version should reflect that.

I generally try to use SemVer for internal version numbers. It’s nice to be able to know something about a release based on the semantics of its version number.

During development, I try to change version numbers straight away (if possible). Sometimes it is hard to know whether the change will be a breaking change or not (which will influence my version number), so nothing is “set in stone”.

To address your specific example:

• During development, pre-release versions would be 1.0.1-alpha.1, 1.0.1-alpha.2, etc.
• The final release of the bug-fix would be version 1.0.1.

Having said that, the ‘public-facing’ product version numbers are often set by marketing, and are completely different. This is out of my control, so no point worrying about it.

Let’s assume A.B.C.D in the answers. When do you increase each of the components?

It is basically determined by your company policy. Our company policy is:

• A – Significant (> 25%) changes or
  additions in functionality or
  interface.
• B – small changes or
  additions in functionality or
  interface.
• C – minor changes that
  break the interface.
• D – fixes to a
  build that do not change the
  interface.

In larger projects/organizations, the major and minor version numbers are controlled by marketing departments and are usually incremented for marketing reasons. At my organization, groups aim to release one major and one minor release each year. The expectation is that major releases contain significant new functionality and there is binary compatibility between APIs for all releases with the same major version number. However, marketing may choose to downgrade a major version change to minor because promised features are not delivered or vice versa to been seen to leap frog competition, for example.

The major and minor build numbers (c and d in a.b.c.d) are usually controlled by development. c is the build number and d is used for patches on a particular release or version of c.

In your case, when you change the major and minor version numbers is less relevant than ensuring the major and minor build numbers are accurate. At my organization, we change the major and minor build numbers as part of the branching process in source control. The main branch usually contains the latest version but marketing may not have decided what version number the release will have yet.

We try and follow the Eclipse example. It does a better job of explaining than I can, but effectively for us it works like this:

When you release 1.0.0.0 the version number you change to is dependent on the type of change that you are making.

• A release that does not effect the API, consider a behind the scenes bug fix that makes the current API work in the expected way, is released at 1.0.1
• A release that adds to the API but does not change the existing API, you may have added a new feature that does not make current clients incomparable with the new version. This can include any number of the above fixes as well.
• A release breaks the current API, removing something, changing something in the way that breaks the comparability with current clients. This can have any umber of the above fixes as well.

As for how to use the 4th section in the version number we use this to differentiate different builds in Nuget (the package managment solution we use for .net). This allows us to avoid having to clear the caches each time we need to update our unreleased software.

There is no next build. On that branch.

Idealized version of our scheme.

Version identification on any branch is PRETTY_BRANCH_NAME-build and PRETTY_BRANCH_NAME is fixed at branch creation.

Our branching scheme(*) is the following:

Top level branches, the PRETTY_BRANCH_NAME of each is a code name, speaking of version number at that level is meaningless, there may be a planned scheme but it will change before the release.

• a TNG (the next generation) branch where long term development is made. Often we don’t even have it and it has never (release) subbranches.

• a TCG (the current generation) branch where current development is made. PRETTY_BRANCH_NAME is a code name.

• a TPG (the previous generation) branch. Often no more development is made here, but there may be activity in the subbranches.

A subbranch is made of a top level branch (of TCG, in presence of slow migration of TPG) when beta for a major release start. The PRETTY_BRANCH_NAME is something like “1.3.X” (X is the letter, not the digit, it means we intend to deliver 1.3 releases from here), feedback from beta is token into account here while work for the next major release is done on the TCG branch.

Ideally, release should be snapshot on that branch, but we know we aren’t perfect and often need to do last minute changes while allowing others to continue to work for the next minor release. Thus subsubbranches are made for the final stabilization with pretty names being the official version number (at that time even marketing won’t want to change it) like “1.3”, “1.3.1” out of the “1.3.X” branch, the last build on each is the release.

If we had a fourth level, the subsubbranches names would have been “1.3.0.X” out of which we’d have had sub^3branches “1.3.0.0” “1.3.0.1”.

(*) At the release level. There may be project subbranches on each of these.

If you are selling software then you will have a new major release each time sales/marketing needs to earn a bigger bonus :-).

If you have some control then:

1. Major releases when:

   • There is some incompatibility with the previous release that requires conversion etc. like from Python 2 to Python 3.

   • There is a whole chunk of new functionality.

2. Minor releases for any small changes in functionality.

3. Patch release for bug fixes.