When not to version

Semantic Versioning is a simple and effective way to document not just the version of your software, but how any given release relates to those around it. The principle is simple, three dot separated integers that are gradually incremented with the following meaning: MAJOR.MINOR.PATCH

This is a system used successfully by most package managers of modern times, as long as everyone follows the rules, and it leads to a certain amount of automation and upgrade confidence.

I’ve used SemVer for years across various languages and tools, having some specific and enforceable rules around versioning appeals to the more anal aspects of my personality. What I have found is that this level of meaningful versioning is sometimes excessive, and adds an unnecessary cost to development.

The cost of versioning

Meaningful versioning your software is hard to completely automate. Only the developer is fully capable of deciding if their change adds a feature or not, or whether a change breaks backwards compatibility. A certain level of automation can be achieved with commit hooks, or with commit message flags that a build system can use to modify version numbers, but the operation still needs to occupy the developer’s consciousness at some point.

For a while my team decided that making a change in the build number was necessary for a pull request to be merged, and enforced this rule in our CI system. This meant that over 60% of new pull requests failed to build just because the version number had not been updated, and resulted in a lot of crappy commits.

Even in highly automated solutions, the cost has been paid in the time it takes to create and maintain an automatic versioning system.

When should I use SemVer?

SemVer should be used mainly with code that has dependants. It is appropriate for library code that will be used by other applications or libraries, where changes may have an impact on functionality further down the chain. In these cases ensuring a stable and consistant experience for you consumers is worth the cost you pay for ensuring that versioning is being done correctly.

On the other hand, a logical versioning system like SemVer is excessive for some applications that do not have direct dependents. A web service that presents a JSON API probably doesn’t need to be so strict about maintaining meaningful version numbers. A more simple V1, V2 etc will protect users from breaking changes, but there is likely no need to expose granular information about bugfixes.

Ultimately it’s all about what works best for your team. I’m now advocating SemVer for library code and consecutive build numbers for the services that consume those libraries…but who knows how I’ll be doing it tomorrow.