Semantic Versioning

I. Format

Version number is MAJOR.MINOR.PATCH, dots are separators:

• MAJOR. Made incompatible API changes

• MINOR. Added backwards-compatible new features

• PATCH. Made backwards-compatible bug fixes

So, generally don't update the major version (MAJOR) of dependent packages

II. Ranges

Used for dependency management, declare target package version range, provide support for automatic dependency updates

• * | x | X

  Accept any available version, default to latest. Don't use, major version updates may cause bugs

• MAJOR | MAJOR.MINOR

  Represent <m+1 and <m.n+1 respectively, can also use \* or x (m.x.x | m.n.*) to express same range

• -, <, <=, > and >=

  m.n.p - M.N.P means >=m.n.p and <=M.N.P

• ~

  ~m.n.p means >=m.n.p and <m.n+1.0

• ^

  ^m.n.p means >=m.n.p and <m+1.0.0

• 0.n.p

  Major version 0 indicates in preliminary development stage, everything may change at any time, MINOR and PATCH have no meaning. At this time ^ prefix is invalid, ^0.n.p is equivalent to 0.n.p. ~ prefix is still valid

III. Notes

Semantic Versioning is only for development environments. That is to say, if you worry semantic versioning will introduce bugs into production environment, it means you're using it wrong.

Specific methods for use only in development environments are as follows:

• Use package.json's "bundledDependencies" to package dependencies

• Use npm shrinkwrap command to create snapshot of dependency hierarchy structure at specific moment

• Add dependencies together with application into version control (such as git)

IV. About Test Versions

Alpha, Beta, Gamma are homophones with α, β, λ, first three letters of Greek alphabet, used to represent three testing stages in software development process:

• Alpha

  Internal test version, for internal communication or professional testers

• Beta

  Public test version, for professional enthusiasts large-scale testing, has some defects, this version is also not suitable for general users to install

• Gamma

  Relatively mature test version, little difference from upcoming official release version

• RC

  Abbreviation of Release Candidate, meaning release countdown, candidate version, in Gamma stage, this version has completed all functions and cleared most BUGs. At this stage will only fix BUGs, won't make any major changes to software. From Alpha to Beta to Gamma is improvement sequence, but RC1, RC2 are often trade-off relationship

• Stable

  Stable version. In open source software, all have stable version, this is open source software's stable release version (not like this for Node, details please see [Windows/Linux Node Update](/articles/windowslinux 下 node 更新/))

For range >1.2.3-alpha.3, version 1.2.3-alpha.7 meets conditions, while 3.4.5-alpha.9 doesn't meet conditions. Although 3.4.5-alpha.9 is actually greater than 1.2.3-alpha.3, but according to SemVer sorting rules, this version range only accepts test versions of 1.2.3, doesn't accept test versions of other versions. Of course 3.4.5 meets conditions, because it's not a test version, and is greater than 1.2.3-alpha.7

Doing this has two purposes, first test versions will update frequently and may contain major changes not suitable for public, therefore excluded from range. Furthermore, although users explicitly use risky test version this time, it's still inappropriate for next version's test version to be included

V. Summary

Don't use fixed version number dependencies, because patch (PATCH) updates may fix existing bugs, generally there are three types:

• Carefully control dependency versions: Use ^ prefix, indicates only update patch versions, don't follow major and minor versions. Suitable for infrequently updated tending-to-stable projects (such as should)

• Slightly looser: Use ~ prefix, indicates don't follow major version, only update minor and patch versions. Suitable for long-term frequently updated large projects (such as express)

• Most lenient: Use * prefix, take latest version. Suitable for personal small projects, experimental projects (such as myproj)

Reference Materials

• Semver: A Primer

• Semantic Versioning (SemVer) Ranges