January 2023
3 minute read time

Understanding semantic versioning: A guide for npm developers. Part 1

By Martin Torp
Cofounder of Coana
PhD in Computer Science

<m>Semantic versioning, also known as SemVer, is a widely used method for assigning version numbers to software packages. For example, npm recommends following semantic versioning as described [here](https://docs.npmjs.com/about-semantic-versioning). It consists of three sub-numbers: the major number, minor number, and patch number, separated by dots. For example, version 3.2.1 has major number 3, minor number 2, and patch number 1. </m>

<m>When a package developer releases a new version of a package, they assign a new version number based on whether the update is backwards compatible or not.</m>

<m>![Compatible and incompatible semantic version numbers](https://raw.githubusercontent.com/coana-tech/assets/main/blogs/semver.png)</m>

<m>**Backwards compatible updates**: An update that is backward compatible and adds new features or capabilities is marked as a minor update, and assigned a version number where the minor number is incremented and the patch number is reset to 0. For example, from 2.5.2 to 2.6.0. An update that doesn't change the existing feature set but only includes bug fixes or performance improvements is marked as a patch update and assigned a version number with the patch number incremented and the minor number unchanged. For example, from 2.5.2 to 2.5.3.</m>

<m>**Backwards incompatible updates** An update that includes backward incompatible changes, referred to as breaking changes, is marked as a major update and assigned a version number where the major number is incremented, and both the minor and patch numbers are reset to 0. For example, from 2.5.2 to 3.0.0.</m>

<m>As package consumers, we often don't put much emphasis on the distinction between minor and patch updates. What we really care about is whether an update is backward compatible (minor or patch) or backward incompatible (major). That distinction is important since package consumers need to invest (sometimes considerable) time and effort adapting their applications to breaking changes.</m>

<m>Now that you have had a quick introduction to the principles of semantic versioning, we're ready to dive into how it's used in practice as an npm application developer in [part 2](https://www.coana.tech/post/understanding-semantic-versioning-a-guide-for-npm-developers-part-2).</m>

<m>You can learn more about SemVer by through the [Semantic version specification](https://semver.org/), which also covers advanced features such as pre-release versions and major version 0.</m>

Questions or opinions?

Feel free to reach out to us by email or through our Slack Community anytime. We'd love to hear from you.

Subscribe to future posts via email?

(or grab the RSS feed)