Semantic Versioning (DevOps)

You may have noticed that programs, apps and libraries for your favourite code may use a numbering system that is not just sequential whole numbers. For example, a look at a Python requirements.txt file shows the Python libraries in use and the version. This is called semantic versioning.

A list of Python libraries and the version of each library.
Library and version from a requirements file

What Does Semantic Versioning Mean?

Semantic versioning gives three values to the softwares version value so that three different types of updates can be carried out. These three values are major, minor and patch. The three values are applied in that order as well, e.g. major.minor.patch or x.y.z. So if a requirements file says flake8==5.0.4 then it means Flake8 was installed using major version 5, minor version 0 and patch version 4.

Why Use Semantic Versioning?

Unless it is no longer being developed, software changes over time. These changes can vary from bug fixes, to security fixes, to full blow new features or the removal of old features. End users of the software may need to know about these changes as they could be reliant on a class / function / API that has been renamed or removed, which would break their usage of the software.

An increment increase in the major version (e.g. from 1.0.0 to 2.0.0) indicates that a change has been included that breaks an API (or multiple APIs) from earlier major versions. I would recommend reading release notes if the major version changes.

An increment increase in the minor version (e.g. from 1.1.0 to 1.2.0) indicates that a backwards compatible change has taken place.

An increment increase in the patch version (e.g. from 1.0.1 to 1.0.2) indicates that a bug fix has taken place.

The patch version resets to 0 when the minor version increments, and the minor version resets to 0 when the major version increments.

For example, I could use a library called “example_lib” in a Python program and all is okay when I develop my Python program which calls on “update_example” from “example_lib”. Some time later I go to use the same Python code and it fails, leading to time spent finding out why before eventually finding out that “update_example” was renamed. If I had recorded the semantic version of “example_lib” I would have noticed that it had changed from 1.0.0 to 2.0.0, indicating that some changes have taken place that break APIs (e.g. renaming “update_example”). I could then either install the earlier version (which would mean taking into consideration bugs / security issues) or update my Python code to use the new functionality.

What About Major Version 0?

If a piece of software is at version 0.y.z (e.g. 0.1.1) then it is still in a developmental phase and anything could change, so expect potential breakages.