So what exactly are those pesky versions in your package.json and Gemfiles anyway? An introduction to Semantic Versioning

3 min readMar 14

You may not give it a second thought, but as a software engineer, you come across Semantic Versioning every day. Simply put, it’s a way of standardizing how version numbers are assigned and interpreted. It follows a three-part numbering system: Major.Minor.Patch. And trust me, understanding what each number means can save you a lot of time and headaches down the line.

Let’s start with the PATCH version. This level is for implementation level detail changes, like small bug fixes. It’s denoted by a number in the form of 0.0.x. So, if you see a new version of software that has changed the PATCH number, you can safely update your code without worrying about backwards compatibility issues.

Moving on to the MINOR version, which is denoted by a number in the form of 0.x.0. This level is for any backwards compatible API changes, like new functionality/features. So, if you see that a new MINOR version has been released, you can safely update your code and expect it to work as expected.

Finally, the MAJOR version, which is denoted by a number in the form of x.0.0. This level is for backwards incompatible API changes, such as changes that will break existing users’ code if they update. So, if you see that a new MAJOR version has been released, proceed with caution and make sure you thoroughly test your code before updating.

Let’s take an example. Suppose you want to build a toy ‘magic-8-ball’ application that can predict the future. Using semantic versioning, you might keep track of changes in your CHANGELOG like this:

  • v0.1.0: Initial release, with the core ‘magic-8-ball’ prediction functionality.
  • v0.2.0: Added color to the 8-ball because black and white is so last century.
  • v0.3.0: Added a ‘shake’ method that shakes the ball so you don’t have to.
  • v1.0.0: Added a ‘reveal’ method to see the prediction without shaking the ball. Breaking change: prediction string now includes question asked.
  • v1.1.0: Added a ‘history’ method to view previous predictions. Backwards-compatible: still returns only the latest prediction by default.
  • v1.1.1: Fixed a bug in the ‘history’ method that prevented it from returning more than one prediction.
  • v1.1.2: Fixed a bug in the ‘reveal’ method that was caused by the previous bug fix.

Semantic Versioning is a simple and powerful tool that can save you time and prevent headaches. Understanding what each number means can help you stay ahead of the game and make informed decisions when updating your code. So, next time you come across a new version of software, take a moment to check the version number and make sure you understand what each number means before updating!

Want to learn more? Check out Preparing for a software engineering interview? Checkout


Staff SWE / Manager @Opendoor, Ex @Twitter Ads Engineering, part time entrepreneur — built, options and algorithmic trading enthusiast