Noob Tidbit #2: Semantic Versioning

One of the Many Things I wish I knew when I first started programming

November 24, 2019

Even if you've only been programming for a short while, chances are that you've installed your fair share of packages and plugins while building an application. You're probably also aware that any package or plugin you install with npm will show up in your package.json file, leaving you with a list of devDependencies and dependencies. But did you ever stop and wonder what those 3 little numbers mean?

All packages will be installed with a version number that looks something like this: react: 16.12.0. From left to right these numbers stand for: major, minor, and patch.

  • major: A major version update, often referred to a breaking change, is an update that includes incompatible API changes, meaning the package is backwards incompatible. When you notice a package has a major update, take caution when updating and look into the release details to gain a better understanding of how the update may affect your app.
  • minor: A minor version update is an indication that there has been a change in functionality but it remains backwards compatible, meaning you shouldn't run into any issues when you update a package that has a minor version update.
  • patch: Patch updates are also backwards compatible and involve a bug fix. If you notice a difference in the patch version of a package you've installed and its most recent release, it's a good idea to update the package to ensure the bug isn't left lurking around in your application.

Along with increasing the number, if there has been a major version update, both the minor and patch versions will be reset to zero, and if there is a minor version update, the patch version will be reset to zero.

If you look at a package.json file in any application you'll probably notice that there are a couple of symbols at play as well. These proceed the major version number and can give you greater control when updating the versions of your packages. If you were to delete your node_modules folder and reinstall it and none of the packages included any symbols, the package that would be installed would exactly match that which you have specified in your package.json file. Adding the following symbols will give you more granularity over what versions are installed:

  • ^: the caret symbol is used to declare that you only want versions that are compatible with the one you're currently using.
  • ~: the tilde is a little more finite. When you use this symbol you're telling NPM that you want only approximate version updates. These may include patch or minor updates, depending on how the author decides to manage their package versions.
  • >: the greater than symbol indicates that any version installed must be greater than what is currently installed. You can also use <, >=, <=

If you've been installing packages willy-nilly and not paying any attention to those little numbers that end up in your package.json file, it might be time to start thinking about how you can use various symbols to better control your updates, and time to start looking into what the authors have included in their patch, minor, and major package updates.

Share this post: