Semantic Versioning

Jon McBee

​One of the many things I can stand to improve upon is how I version my software.  I say this because throughout my career I have never adhered to a strict versioning scheme for the software I write.  This has been tolerable because my decisions typically only impacted me or at worst my team, but now that I am diving into the world of open-sourced software I think it is time to embrace a standard for software versioning.

In my research to understand what other people are doing with regard to versioning their software I came across the Semantic Versioning specification (SemVer).  I'll be honest there is nothing earth shattering here, SemVer follows the standard X.Y.Z (Major.Minor.Patch) semantics for versioning that we probably all already use.  What SemVer adds to the discussion is a very well defined standard for how/when/why the X.Y.Z versioning numbers are changed.  This is important with open source projects like Stream because if we all agree to follow this standard then we now have a common language we can use to discuss changes to the software and what impacts those changes have on our respective code bases.

SemVer is made up of a list of 11 rules that dictate how software versions are updated.  At a high level the software version number is structured as Major.Minor.Patch where the components are incremented as follows:

• Major version is incremented when you make incompatible API changes
• Minor version is incremented when you add functionality in a backwards-compatible manner
  
• Patch version is incremented when you make backwards-compatible bug fixes
  
  

​We can see that the Patch version number identifies the number of backwards-compatible bug fixes that have been implemented under the current Minor version.  SemVer defines a bug as an "internal change that fixes incorrect behaviour".  The Minor version number identifies the number of backwards-compatible features that are added to the current Major version.  This number is also incremented when existing features have been deprecated but not yet removed from the codebase.  The Major version number identifies backwards-incompatible changes to the codebase.  This a subtely powerful feature of SemVer because it allows me to guarantee that a consumer of my open-source code can update my published package without breaking their code that depends on my package as long as the Major version does not change.

In the context of Stream I like the idea of using SemVer to explicitly define how releases are versioned.  When you decide to use a package that I publish you and I have entered into an agreement that allows you to make a few assumptions.  These assumptions include that I will maintain the code base behind the package, I will notify you when I make changes to the code base, and that I will give you the information that you need to decide if you want to adopt the new version or not.  SemVer helps to remove the risk from the assumptions by explicitly defining how my changes impact your code base.

I encourage you to take a look at the SemVer specification and would be interested to hear your thoughts on it.  I am also curious how you handle versioning your software and if you have adopted a formal defintion for your versioning semantics.  I will be using SemVer for all open-source projects that I publish on the Composed System Bitbucket page moving forward.  Hopefully this decision will make it easier for you to use and participate in our open-sourced projects.

---

Jon McBee is the Founder and Managing Partner at Composed Systems and is a Certified LabVIEW Architect, Certified LabVIEW Embedded Developer, Certified TestStand Developer, an NI Certified Professional Instructor, a LabVIEW Champion, and a Certified ScrumMaster