What is semantic versioning? We have all seen software releases with a series of numbers to show which version it is. But what do the numbers mean, and what information can we get from the change of a single digit? In this post, we will look into semantic version conventions with a focus on the ITxPT specification versions.
Version 4.5.6 – what does it mean?
Let us say we have a specification version called 4.5.6. What can we read from the different numbers and their positions? What are major, minor, and patch versions?
First position – Major version
The first position from the left has the highest significance level and tells us which major specification version. In this case, the fourth.
So, what constitutes a Major version? According to strict semantic versioning rules, it is not about a specific technical height or added functionality to qualify as a major release. Instead, it comes down to if the version is backward-compatible or not.
A specification update that affects the compatibility of existing functionality is a major update or release where both the service(s) and their client(s) need to be updated. There is, however, a need for some flexibility. Too rigid rules are hard to follow. We will discuss it further down.
A major version summary
After a Major version release, not all existing implementations will function without adjustments, and both services and their clients need updates.
Second position – Minor version
The second number in 4.5.6 tells us that there have been five minor updates since the latest major version. The second position starts at zero for every new major release.
A minor release means adding new services or functionality without affecting the functionalities of the previous version. Anything that worked with the latest version should also work after a minor release. However, if you want to use the added functionality or services in the newest version, it needs an update. The client should still work – without any new functions, of course.
In the strictest sense, the new version should be backward-compatible with all preexisting functionality. However, there are situations where the rule needs to be adjustable, as we will discuss further down.
A minor version summary
It is OK to add services and functionality in a minor release, but not to break the existing functionality.
Third position – Patch version
The third position number in 4.5.6 tells us that there have been six patch releases since the latest minor version.
The patch/bug releases should not affect implementation at all. It should just be small improvements or text adjustments for readability purposes. Any functionality or service should work in the same way after the update as before. The update should not introduce new functionalities or services, and both client and service should work without changes. If changes are needed, they should be very insignificant.
Even with the patch version, the rules have to be a bit flexible. For example, if something is not working or is missing, an implementation-affecting change can be made.
A patch version summary
A patch release should not affect implementation at all. Any functionality or service should remain compatible after the update.
Challenges – what kind of update, what to include?
In the strictest sense, the version level rules are straightforward. However, with an extensive document like the ITxPT specification, different factors need to be considered. Some aspects might demand a major update from a version semantic point of view, while other factors point towards a minor or even patch update.
Suppose a small part of the document, only concerning functionality affecting very few users, is updated so that it, in a strict sense, should result in a new major version. In that case, there is a risk of sending the wrong message and create expectations that the update addresses all known issues. Then it might be wiser to name the version according to a minor or even patch release, even if it means breaking the semantic versioning rules—the choice of the lesser evil.
Clear communication
An essential aspect of the release process is clear communication. For each ITxPT specification update, all users should have a clear understanding of both the update’s overall scope and the consequences of the changes made in that update. There is always room for improvement in communication; ITxPT welcomes feedback on the communication about releases.
