The Art of Semantic Versioning

Today I want to write about semantic versioning or Semver. Not only because it's fun - which it totally is - but also because I actually ran into problems with it at work. Basically semantic versioning is a standard which defines how version strings of software should look like. This becomes especially important if you plan to upload your software to some kind of repository, but it can also be handy for things like automated deployment or the likes. Also using semantic versioning allows people to get some extra information about the program they are about to install just from looking at the version string.

Right, so that sounds nice and all but how does it actually work? I won't go into too much detail here because this post is meant as an introduction to semantic versioning. Basically the pattern is as follows: ::

<major>.<minor>.<patch>-<pre-rlease>+<build>

So you have a version string consisting of 3 places:

The major version, which has to be incremented on backwards compatibility breaking changes. The minor version, which is meant to be incremented on feature updates. The patch level, to be incremented on bugfix releases. Optionally you can have pre-release identifiers denoted by a hypen and build metadata denoted by a plus sign after the regular version string.

Have an ASCII art diagram:

                1.4.0-alpha+amd64
                | | |   |     |
major version --+ | |   |     |
minor version ----+ |   |     |
patch version ------+   |     |
pre-release version ----+     |
build metadata ---------------+

The above example would tell us that the corresponding program is backwards compatible with all 1.x.x versions, had 4 feature releases since version 1.0.0, is currently of alpha quality and has been built for the amd64 architecture.

Now in the early stages of development you might tend to make big changes more often which would leave you with high major version numbers quite quickly. In my opinion it's OK to only increase the minor version even for backwards incompatible changes as long as you are at major version 0 and you make it clear to your users that things are not stable yet.

That's pretty much it actually. If you want to learn more about this topic check out the well written specification at semver.org.

~ thomas