Semantic Versioning Explained

Subscribe to my newsletter and never miss my upcoming articles

In this article, I want to deep dive into an important concept when you have to deal with versioning your software and let the users know which version to use based on the version number. This concept is really important because it's the base of many platforms for sharing and publishing code such as npm, pub.dev, Apache Maven, Python Package Index, Android and iOS follow the same rules and not least a lot of the Open Source code present on GitHub.

Semantic Versioning

The Semantic Versioning concept is very simple and it's based on the concept that all software versions have 3 digits:

x.y.z

  • x is the major version
  • y is the minor version
  • z is the patch version

So for example, at the time of writing, the LTS version of Node.js is 12.19.0 so:

  • the major version is 12
  • the minor version is 19
  • the patch version is 0

When you release a new version of your software you should comply with the following rules:

  • You should increment by 1 the major version when you make changes that are not compatible with the previous version;
  • You should increment by 1 the minor version when you add a backward-compatible feature with the previous version;
  • You should increment by 1 the patch version when you make backward-compatible bug fixes;

Real Life example

Let's make a practical example of how to deal with semantic versioning in real life:

  • You just release a brand new library with version number 1.0.0
  • You find some bug and you quickly correct them so you release version 1.0.1 (increment the patch number)
  • After one week of development you add some features that can be used with existing software and they don't bring compatibility problems so you release version 1.1.0 (increment the minor version)
  • After two months of rewrite you have completely changed the functioning of your library and this is not backward compatible with the previous one so you should release version 2.0.0 (increment the major version and reset the middle and last digits to zero)

Simple! If you follow these simple rules anyone who uses your code will know very easily which version of your library to use to avoid compatibility problems or to try new versions.

Bye, Alberto.

Comments (1)

Maria Kristina Salada's photo

Thank you very much for sharing these things Alberto Bonacina. It's easy to follow and understand. 🙏