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?
Semantic versioning consists of 3 numbers, each separated by a decimal. An example of a semantic version would be
- 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
Sometimes, you may also see a pre-release tag appended to the version with a dash, such as
1.0.0-beta.12, which are both valid semantic versions.
In your package files, a majority of the dependencies will have a special character at the beginning of it, such as
^. 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.6means all releases from
4.5.6up to, but not including
4.6.0can be used.
^is similar to
~but also allows updates to the MINOR version, so
^1.2.3can 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.
Other than specifying a version with a special character, there are also ways to write ranges of versions:
>=will signify any version greater than, or greater than or equal to, the specified version, including MAJOR versions, such as
<=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
xcan be placed in any version number as a wildcard, it just means any version is acceptable, such as
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.