Bruno Peeters Technical Blog

Due to the fluid property of software, it is relative easily to make changed and create a new release of the software. Therefore the code base grows over time; new features are added and bugs are being solved. To identify the evolution of software or a software library, we give software a certain version. A version identifies software at a particular stage. If the version differs from another version of the same software, this other version contains possibly other features or solves (or even introduces) bugs.

It is important to have a solid versioning strategy in place, so that you can easily identify the state of a piece of software you are looking at. A good software versioning software also gives a hint to the user, what to expect: will it have major improvements, will it break any interfaces? It also helps the development team to pinpoint an issue to a set of changes within the code that all together formed this version. A common used strategy is semantic versioning, meaning that the versioning has a specific meaning.

The parts within Semantic Versioning

Version numbers within the semantic versioning, are build up upon three parts: major, minor and patch. When a new version is being created, at least one of the components get incremented. This means that there will be never two copies of a piece of software, with the same version but different functionality.

Let’s have a look at what each of these three parts are used for within semantic versioning. First off all the major version will be increased when making API (Application Programming Interface) changes that break previously used interfaces. The API defines the interface with its outside world. In terms of a software product, this can for example mean that the datamodel is different or other external interfaces have been changed (like the UI).

The minor version will be increased when you add functionality in such a way it doesn’t break functionality provided in older versions of the current major version.

Increase the patch version when backward compatible bug fixes are added to the software.

Prototyping and Semantic Versioning

Let’s say you are prototyping a new solution for your customer, but the software is not yet officially released. Semantic version dictates you start versioning this software with 0.x.y, so version 0. It indicates that anything can still be changed.

In case of a library this means your users shouldn’t rely to much on the API, since it is still under construction.

Where to store the version

Having a software version is one thing, but it is also important that people are able to identify the version of your software they are using. Within .Net development, this can be easily achieved via the assembly information of your application. Instead of the 3 elements within Semantic versioning, .Net has 4 elements: <major version>.<minor version>.<build number>.<revision>. You can easily map these unto semantic versioning by replacing the ‘build number’ with ‘patch’. Leave ‘revision’ to ‘0’.

Make it your user easy to find this number, either via the properties of your application (which can be shown via the file explorer) or show the version number in the help section of your application.

Alternatives to semantic versioning

There are more types of versioning beside semantic versioning. Some examples:

• Date of release
  The date that the software was released. This has however some drawbacks when working with internal builds to test. It will be more difficult to distinguish two different pieces of software based on solely the date.
• Commit hash
  The commit hash added to the version, denotes on which git commit the software was build.
• Build number
  Each time a new build is trigger, the build number will be increased.

Semantic Versioning is however now commonly used, especially in open source project. If you don’t have yet a version control mechanism in place for your software release, you might want to give semantic versioning a try.