SemVer for Absolute Beginners
As a software developer you are probably aware of versioning and its
importance. Probably somewhere you came across this term - SemVer - and wondered
what exactly it is or how does it relates to versioning in general. To that end
this post briefly describes what SemVer is.
SemVer is a short form for Semantic Versioning. SemVer is a specification
that describes how software version numbers are to be given. The official
website detailing this specification can be found
here.
The Basics
As per SemVer specifications a version number takes the following form:
<major_version>.<minor_version>.<patch>
Major version is a number that indicates a major release of
a software. By major it means that this release is not backward compatible with
earlier major release. In other words, if two versions of a software have the
same major version it implies that the later is backward compatible with the
former.
Minor version is number that indicates the some new
functionality or features has been added to the software. The additions won't
break existing code because the software is still backward compatible.
Patch is a number that indicates that some bugs have been
fixed. The software is backward compatible and provides the same functionality
as before, except that the bugs have been fixed.
A simple example
Let's understand what we just discussed with a simple example.
Suppose, you developed a jQuery plugin that renders a fancy calendar in a web
page. You wish to follow SemVer to version your plugin.
So, version number of your plugin would be :
1.0.0
Now suppose that you decide to add some functionality to the plugin. This is
an addition to what you already have. The additional functionality is not going
to break anything.
So, the new version number would be :
1.1.0
For more additions under the same major number, you keep incrementing the
minor version number.
Further suppose that you discovered some bugs in the code-base and you fixed
them.
Since this is just bug fixing your version number would be :
1.1.1
For more bug fixes under the same major version you keep incrementing the
patch number.
Few months later you decide to revamp the plugin so as to make it more
optimized and rich. However, in the process you introduced breaking changes.
Thus the plugin is no longer backward compatible.
So, you would call it :
2.0.0.
Notice that since the major version has changed, the minor version and patch
have been reset to 0.
Version numbers during development stage
In the above example it was assumed that you developed the plugin and
released the fully developed plugin that was then used by various applications.
So, we started the version number as 1.0.0.
Suppose you wish to maintain version numbers during development stage also.
In that case you won't call it 1.0.0 because the plugin is not yet ready for
consumption. You will call it :
0.1.0
Anything that is developmental is below the
major version of 1. You increment minor version as and when the development
moves ahead but since it's not yet fully ready, the major version would be 0.
Version numbers for pre-release software
Now a days many companies release pre-release versions of their software to
the public. This way developers can get an idea as to what is coming up in the
next release. So, releases such as alpha, beta, release candidates are quite
common. How do you deal with pre-release software under SemVer?
SemVer allows you to add a string identifier to the version number. For
example, alpha version of your plugin would be called :
1.0.0-alpha
Similarly,
beta2 of your plugin would be called :
1.0.0-beta.2
RC4 release would be called
:
1.0.0-rc.4
and so on.
Indicating build metadata
Build metadata can be appended to the patch number like pre-release
identifier. But it uses + rather than -. For example,
1.0.0+001 and
1.0.0-beta+1234.
As you can see, following SemVer immediately gives a definite meaning to the
version number. As a developer and as a consumer you are immediately aware of
the impact a particular version is going to have. That's why jQuery, Angular and
many NPM and NuGet packages follow SemVer.
That's it for now! Keep coding!!