Semantic Versioning

Semantic Versioning

When you write software-artifacts, each of them has a version. But how should the version numbers be created? Are there several rules when to increment which part?

Parts of a version-number

A version number should consist of a group of 3 numbers separated by a dot. The first number is called major, the second minor and the third one patch. After that a small text called meta-data can be appended to the version-number, but this is not discussed here.

Rules for incrementation

When you create a new version of a new component, you should follow these rules.
  • Major is incremented when you make API changes incompatible to the current version
  • Minor is incremented when you add functionality that is backwards compatible
  • Patch is incremented when you fix a bug and the API is not affected
An API change means you change an interface or a class such that an existing program that uses it, cannot use the new version without adaption. This includes changing the signature of already existing non-private functions, remove an existing non-private function, changing the access specifiers to a lower access level.
Adding functionality means adding (new) non-private functions or overloading existing ones. If the parameter-list of an existing non-private function is changed, it is an API-change.
Fixing a bug means only changing code of a non-private function for correcting errors, but without changing expected behaviour.

General rules

If you need a version number for a component you should obey these general rules.
  • Every release gets a new version-number
  • Patch is reset to 0, if Minor is incremented
  • Minor and Patch are reset to 0, if Major is incremented
  • Meta-data may be appended after Patch
If you act on these rules you are using semantic versioning.

Advantages of using semantic versioning

If you are using a component supporting semantic versioning, you can safely upgrade to a version with the same major, but higher minor or patch level.
If you want to use a library with a higher major, then you know that it might be incompatible with your code.


Using semantic versioning makes it easier to use components and know about affected code. There is no disadvantage or reason why not to use these rules.