CB5: Semantic Versioning

This article is part of the CodeBoosting series, where we teach to scientist how to make their code better and shareable.

This article will explain a common and widely way to give a version number to a library. If you are a scientist using libraries written by other you will definitely wonder how the library author decided to give the version name to their libraries. Moreover you definitely want to know when is save to upgrade a library to a newer version or when an upgrade could break your existing code.

Similarly if your project is growing, you may start to share your code in platform like Github so that it can be distributed to other and used by other fellow scientist that will hopefully cite your work. In this case is important to understand how versioning works, its meaning and how to comply to the rule so that other people can comfortably use your code.

Here we are going to explain one way to versioning the code, is not the only one, but is the most common. Moreover, it is important to know that no everybody will follow the same convention. It is also fundamental to remember that these are all just conventions, and even given the best effort from the developers there might be situations that will force us to break those conventions.

Let’s dive into Semantic Versioning.


In it’s simplest and purer form semantic versioning is quite simple, it is composed by just 3 integers number, separated by a dot .

The first number is called the MAJOR, the second number is called the MINOR while the third and last number is the PATCH.

Let’s make an example, the 9th of February the latest version of scipy (a common mathematical and engineering library for python) is been released, the developers released the version 1.2.1

The first 1 is the MAJOR number, the 2 is the MINOR and the last 1 is the PATCH.

Similarly the 26th of October 2018 was released the version 0.7.6 of dyplr a common R library for data manipulation.

In this case the first 0is the MAJOR, the 7 is the MINOR and the 6 is the PATCH.

Now that we have understand what are those numbers, let’s understand what those numbers means, their semantic.


The MAJOR number indicate compatibility between libraries. If two libraries have a different MAJOR number you should not expect them to be compatible and that, at least some, work would be necessary to switch between one library and the other. Indeed the change of the MAJOR number indicate breaking changes in the libraries.

You can think at the MAJOR number like an extension of the name of the library itself. Different MAJOR version, hence different library, hence breaking changes in the functionality, hence we cannot switch easily between them.

If two libraries have the same MAJOR number, then it should be safe to upgrade your library. Indeed the MINOR number is incremented when a backward incompatible change is implemented. Hence it would be safe to use a library with a bigger MINOR number. On the other hand, it may require some work to downgrade your library.

Indeed the MINOR number is incremented when a new feature is added. Of course if you are using the features added in the version 1.7.0, those features are not in the version 1.6.0 nor in 1.5.0 and so on. However, the functionality in the version 1.5.0 will be on version 1.6.0 and 1.7.0. But, of course, they don’t have to be in the version 2.1.0 or 2.8.0.

The last number is the PATCH number, it is incremented when a backward compatible change is implemented to the library. Usually this changes are bug fixes or security fixes that don’t change the functionality of the libraries.

Hence it should be possible to switch from the version 2.1.34 to the version 2.1.1 without any issues.

A note of cautions

What we described is the perfect outcome of using and applying Semantic Versioning.

However, no-one is forced to follow this standard and moreover there are several forces that tends to make us drift from this golden idea.

As a example, a very important security update changes a very small and not very used functionality, while this is technically a big breaking change that would require an upgrade in the MAJOR number, the author may decide to just upgrade the MINOR or even the PATCH number.

On the other hand, it could be possible to upgrade the MAJOR number even if not strictly required. Indeed the library could have grow enought that the author decide to upgrade the first number of the versioning, the MAJOR number. It is an useful techniques to communicate to the user that the library has growth and mature and that you should test the new one and forget about the shortcoming of the old library.


In this post we explore the idea of Semantic Versioning to understand the reasoning behind the numbers in most software releases.

We understand what the MAJOR, MINOR and PATCH numbers means and what is the logic behind increment them.


We publish new content each week, subscribe to don't miss any article.