Understanding Semantic Versioning

Semantic Versioning (or Semver) is a methodology for releasing software with a universal versioning system. You have probably seen semantic versioning in many places, such as in node package files or Github tags and releases. So how does it work?

---

The Basics

Semantic versioning consists of 3 numbers, each separated by a decimal. An example of a semantic version would be 3.6.4, or 4.12.11.

• The first digit is a MAJOR version which should be incremented when there are incompatible API changes
• The second digit is a MINOR version that is incremented when new functionality it added in a backwards compatible manner
• The third digit is a PATCH version used for backwards compatible bug fixes.

To visualize this, semantic versioning follows the pattern MAJOR.MINOR.PATCH

Sometimes, you may also see a pre-release tag appended to the version with a dash, such as 1.0.0-alpha or 1.0.0-beta.12, which are both valid semantic versions.

---

Version Updates

In your package files, a majority of the dependencies will have a special character at the beginning of it, such as ~ or ^. These are special characters that are used to signify how a package should be updated.

• ~ tells us that the package can updated to the latest PATCH update, but has a fixed MAJOR and MINOR version. ~4.5.6 means all releases from 4.5.6 up to, but not including 4.6.0 can be used.
• ^ is similar to ~ but also allows updates to the MINOR version, so ^1.2.3 can be updated all the way to, but not including, 2.0.0. However, below 1.0.0, it will act the same as ~ in that it will only update the PATCH version, the MINOR version will be fixed.

For anything below 0.1.0, all versions prefixed with ^ will not update, even to the next PATCH.

---

Version Ranges

Other than specifying a version with a special character, there are also ways to write ranges of versions:

• > and >= will signify any version greater than, or greater than or equal to, the specified version, including MAJOR versions, such as >=2.0.0. < and <= work the same but with less than.
• Putting two versions next to each other will specify a range, such as 1.0.0 - 1.5.0 (equivalent to >=1.0.0 <1.5.0)
• An x can be placed in any version number as a wildcard, it just means any version is acceptable, such as 2.x or 1.2.x

---

Here are some examples of valid semantic versions:

1.2.3
0.0.1-alpha.2
1.0.0-beta
0.9.0-b.89.z
^1.4.5
~1.9.1
>2.0.0
>=19.4.3
5.x
<4.0.0
<=4.0.0
1.2.3 - 1.2.6
>5.0.0 <=2.1.0
>=10.1.8 <11.0.0-beta.9

I hope this brief explanation can help you understand your package files, and also help you in releasing your own projects! There is much more to learn more about semantic versioning, and you can check out the official site which goes into way more detail about each requirement for naming your versions.

Comments

[Waylon Walker]

Thanks for the description of ~ and ^. Coming from 🐍 python I was always confused by these in my package.json