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!!