Software Upgrade Versioning: Semantic Versioning
The aim of this article is to describe semantic versioning briefly yet thoroughly. Semantic versioning is a simple set of rules and requirements. We can use this set of rules and requirements when we want to assign versions to each state of our product. At the time of this writing semantic versioning is at (2.0.0).
Why Semantic Versioning?
There are many reasons why semantic versioning is now one of the most popular SUVs and it has many benefits using it. I will glimpse into three of these reasons in the following.
- It is an inside common language and it helps everyone to be on the same page about the current state of the product. Developers will know the state of the underlying code they are working on. DevOps team will know which versions of the product and when to deploy and strategize better for their A/B testing and continuous deployment. Even the marketing department can better represent features to customers. Using semantic versioning can save up a lot of the team’s time and also hinder many incompatibility tensions.
- It is also an outside common language for whoever use your software. This could be your users, other teammates or even other codes in your software. When packaging your product, whoever uses your product will have a correct idea of the underlying code state. This will prevent wrong expectation of your code when using or integrating with your product.
- Another reason semantic versioning points out in their documentation is to avoid “Dependency Hell”. As Tom Preston-Werner states the bigger your system grows the more probable it is to find yourself in this “Dependency Hell”. I will explain this in the following section.
I am sure most of you know the concepts of versioning and semantic versioning and its benefits. But if you have a slight doubt about 4.1.6-alpha.2+2019.exp.sha.5114f85 and 4.1.6-alpha.3, I suggest continuing reading because it will save you a lot of trouble one day as it saved me after reading semantic versioning in details.
Dependency Hell
Most of the time as your products grow, your dependencies list increases.
Dependency Hell is when you can’t move your project forward due to Version Lock or Version Promiscuity. Don't get carried away by them.
Version Lock occurs when you set your dependency specifications to tight. At some point, you will be unable to upgrade the package without releasing a new version of every dependent package.
Version Promiscuity is when you set your dependency specifications too loosely for not being myopic and to provide compatibility with more future versions than is reasonable. This will also hinder the progress of your product at some point in the future.
Semantic Versioning Scheme
The general form of semantic versioning is a version number like:
MAJOR.MINOR.PATCH{format}
As the docs state increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backward-compatible manner
- PATCH version when you make backward-compatible bug fixes.
The {format} is an extension to the version number for labels for pre-release and build metadata.
Semantic Versioning Specification
There are some interesting points in semantic versioning specification which I like to mention in this article. If you are interested in more details please refer to the complete semantic versioning specification section.
Public API
If you want to use semantic versioning, you must declare a public API for your code usage. Public API can be declared in code itself or exists in the documentation.
Const Versions
When you release a version do not change or modify that version code. Release updated versions for any modification.
(0.MINOR.PATCH)
If your version starts with Zero, It means that the code is in the development stage. Anything may change in future and public API is not stable at these versions.
(1.0.0)
Version 1.0.0 defines the first public API.
Patch version (major.minor.PATCH | major > 0)
Patch version number must be incremented only for backward-compatible bug fixes.
Do not increment it if your bug fix is not backward-compatible.
Minor version (major.MINOR.patch | major > 0)
Increment minor version number if you introduce new functionality to the public API or mark a functionality as deprecated in the public API.
Reset patch version number to zero when incrementing the minor version number.
Major version (MAJOR.minor.patch | major> 0)
Increment major version number when you introduce any backward-incompatible changes to public API.
Reset patch version and minor version number to zero when incrementing the major version number.
Extensions
The {format} is an extension to the version number for labels for pre-release and build metadata.
pre-release
A pre-release label is appended to version number using a hyphen (-) and a series of dot-separated ASCII alphanumerics strings. e.g. (2.0.0-alpha.3)
A pre-release version indicates that the release is unstable and might not meet the compatibility requirements, specefied by it’s assosiated normal version.
build metadata
A build metadata is appended to version number using a plus sign (+) and a series of dot-separated ASCII alphanumerics strings following the patch or pre-release version. e.g. (4.0.0-alpha.3+exp.sha.5114f85)
The build metadata must be ignored when determining version precendence.
Version Precedence
The version precedence is for comparing versions of a product.
here is an example:
0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.
Backus–Naur form of the semantic versioning is available in this section of docs.
Take a look at the semantic versioning FAQ section if you are interested in reading more.
Thanks for reading and I hope this article was useful for you.
