Personal blog of Gunnari Auvinen. I enjoy writing about software engineering topics.

Picture of the author, Gunnari

What is Semantic Versioning?

December 11, 2014

Versioning and Software Development

As you've probably seen while writing your own software, your code can change a little bit from version to version, or it can change quite a bit, or it can be completely overhauled. As you write code and go from version to version, are you using a versioning system to keep track of the types of changes from build to build? If so are you following a defined system? To my understanding there is currently no universally adopted specification for software versioning, but one specification that many people use is called Semantic Versioning specification or SemVer.

What Is Semantic Versioning?

Alright now that you know about the SemVer specification, what exactly is it and how is it defined? SemVer uses the following three categories: major, minor, and patch. These map to the x.y.z numbering system, eg 1.2.3 would be major version 1, minor version 2, and patch version 3.

Ok... what exactly do major, minor, and patch mean with respect to software versions? The following information has been taken directly from the SemVer website:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

There are a couple of main takeaways from this information. The first being that you should always review what changed in a piece of software when they update the major version number. Specifically due to the fact that certain aspects of the API may or may not have changed. The documentation should be examined to ensure that either the changes allow continued functionality of your own project or that your project will need to be refactored due to the changes. On the other hand upgrading a dependency when the minor or patch version is updated, is less concerning, as all of these changes are expected to backwards compatible. Armed with this information you now know when it is possible to upgrade a dependency without fear of likely breaking anything and when you will need to review the new software to see if you will need to change any of your own code.

Why Is This Important?

Well all of that is great information, but why should you care? As you develop software you want to avoid something coined "dependency hell". Specifically you don't want to be put into a position where changes in your dependencies will break your entire system or leave it in a state where you cannot easily make changes. The Semantic Versioning specification assists you in avoiding that unenviable position. This is made possible by the ability to determine whether or not when a dependency is updated whether or not it is backwards compatible. If the update is either minor or a patch in nature, you will be confident in updating that dependency, as by the SemVer definitions the public API of that dependency will still function the same as it was previously defined. While on the other hand if changes in a dependency result in incompatibility you can require that your software uses a specific version of the software, such that you ensure continued functionality.

When you work on your next project work on implementing the SemVer specification as your versioning system. There's additional thoughts and points behind SemVer on the specifications website. This will make all of our lives as developers that much easier and fruitful!