21 July 2015 SemVer Robert Muehsig

I made a short tweet today and it seems I hit a nerve:

Because I like blogging I decided to write a small blogpost about SemVer.

Why Semantic Versioning (SemVer)

In our industry we use version numbers a lot. The typical naming is MAJOR.MINOR.PATCH, sometimes also MAJOR.MINOR.PATCH.BUILD or instead of PATCH you could say REVISION - it is more or less the same.

But the problem is: This is not very self describing. What is MAJOR or a REVISION? When should I change the MAJOR version and when should I increase the MINOR version etc. You see: It sounds simple, but it is really complicated.


SemVer is a pretty simple concept to give each part a better description.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.
  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

If you change your API with breaking changes: Increase the MAJOR version. A new feature? Increase the MINOR version. Bugfix? Simple…

So in short: Breaking.Feature.Bugfix

It’s a technical solution - don’t try to get nice Marketing-Version-Numbers

SemVer is a technical solution - if you want to get great Marketing-Version-Numbers this will probably fail, so maybe you should split the “commercial” and “technical” version number.

Learn more

I had read the “Breaking.Feature.Bugfix” summary somewhere else (maybe from this blogpost?), but I can’t remember the original author (Kudos!), but I received this Tweet with a full talk about exactly this topic, so if you want to learn more:


Just for fun:


Hope this helps!

Written by Robert Muehsig

Software Developer - from Saxony, Germany - working on primedocs.io. Microsoft MVP & Web Geek.
Other Projects: KnowYourStack.com | ExpensiveMeeting | EinKofferVollerReisen.de