Versioning Your Software Correctly : A Guide to Semantic Versioning
I don’t believe enough has been written towards understanding how software products are and should be versioned. I have always meant to read through proper documentation and understand semantic versioning but have procrastinated furiously. Today though, I took out the time to go through the documentation and I am writing this post to summarize what I’ve understood. Let this be a
tldr; for the next project you're going to release, and how you're planning to version it.
There are three components to a project version name, with an additional extra component for test releases. There are as follows:
major-version.minior-version.patch with an additional optional dash-separated specifier for pre-releases, such as in:
major-version.minior-version.patch-alpha.1. The following definitions would provide better understanding of what these terms actually mean:
major-version: a breaking release which is backwards incompatible
minor-version: a feature addition which maintains backward compatibility
patch: a bug fix, without any feature addition, and maintains backward compatibility
pre-release-specifier: the existence of a dash-separated pre-release-specifier tells your users that any given release might not be fully stable. It can be added to any release at any point, and the test-specifier in itself can have versions, indicated by semantic integer or other standing versioning protocols.
- Having a
0as your major-version tells users that the release is a development release and features might be broken.
- In addition to semantic versioning and pre-release specifier, build metadata can also be added to version names by using a
+at the end of the semantic name. Eg.
The examples listed below provide different scenarios of versioning:
0.1.33- a development release, with an additional feature release and the 33rd bug-fix.
1.4.2-alpha.2- a breaking release from the previous major-version (
0), with the 4th backward compatible feature addition and 2nd bug-fix. Additionally, this is an alpha pre-release, with the pre-release version set at
alpha.2- the second backward compatible iteration over the pre-release. Note that version
1.4.3would have higher precedence over
The information covered here should be enough to get you started with semantic versioning without any gaping holes in your knowledge. If this interests you, I would suggest you go through the documentation of semantic versioning available at https://semver.org/.
Originally published at https://vivekkaushal.com on January 3, 2021.