I love Semantic Versioning

Sat 26 Jun 2021

Semantic versioning (aka SemVer) has been around for years and generally has been accepted as a versioning system across the board. It is important to spread the knowledge because making everybody understand will make the engine run smoothly.

Breakdown of SemVer

A version consists of three parts, referred to in their documentation as X.Y.Z. These represent the work that is done on a release of a package.

X represents a MAJOR version of your software. You can only increment the X if there are incompatible changes pushed. This will let your users know to carefully update as stuff might break.

Y represents a MINOR version of your software. Here you add new features to your software. Interestingly enough they include in their 2.0.0 docs that when deprecated API functionality is replaced the Y may only be incremented if the new functionality or improvements are substantial enough to be called a new feature.

Z represents a PATCH. Commonly bugfixes on features. This should always be backwards compatible and not introduce any new functionality.

Pre-releases are also possible. They may be denoted with a hyphen and a series of dot-separated identifiers. When you see their examples it should be clear. You can also refer to examples in the wild when it comes to that. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.

That pretty much concludes the format. Their document is a good read and is composed according to RFC 2119. There are still a couple of topics I would like to touch on.

Version 0

Version 0.X.Y represents unstable development. Your MVP has not reached stable waters yet. This as per SemVer states, SHOULD NOT be considered stable. Anything MAY change at any time.

However. I've seen projects stuck at this state for years and not change many features within their software. Version 0 is meant to be rapid development. Striding to get MVP stable. It should not be an excuse to change your software at any given moment.

I've read a blog by a software architect once, when I will remember the post I will link it back here. He stated that software development should be predictable. Make small, clear and simple functioning packages. These are easy to version and maintain. A simple common practice is to envision the functionality up-front for the MVP. Make a plan. Stick to that plan. Do not change scopes as that is the beginning of a slippery slope. This sounds simple but is actually hard to master and execute.

It Takes Three To Tango

It takes all three components to be compliant. MAJOR.MINOR.PATCH is what a version stands for. This information needs to be explicit. It will give the user a lot of information to think about when upgrading.

Working with Semantic Versioning gives you insight upfront. My rule of thumb generally with PHP packages is that patches and minors are fine. A small run of the tests in your project will prove that nothing has been broken.

Majors most of the time have not proven to be problematic in my projects either. The occasional break has happened but that was nothing that couldn't be solved with a few hours of work.

They also debunk the v1.2.3 tag as being semantic versioning. More on that here. So, for those who get the reference, It Takes Three to Tango!

Pre-release software

These -alpha, -beta, or for example -rc tags are great to let your users know that you are working hard at releasing the software. Your users can decide if they want to use these releases and know they are to proceed with caution as these are not your typical releases. They can be a tad unstable.

The flexibility in SemVer will allow this and that's great. Package managers like composer or npm make it a breeze to navigate and test these releases.

Existing software

This is great about SemVer. They explain that existing software can also start using it at any moment. In their FAQ section, you will find the following. Using SemVer will improve your workflow in releasing software. It provides clear structure and will let your audience know what is going on without going into details.

Those who are still on the fence SHOULD NOT be. To stay within RF 2119 terms :) Existing software should be using SemVer.

That's it!

Semantic versioning is not scary or hard. It is, however, an essential tool for the skilled developer. SemVer 2.0.0 stands rock-steady with clearly defined rules that provide a good framework to version your software. In turn, your audience can clearly see what you are doing and adopt your development more easily.