In an attempt to help developers better understand the semantic versioning spec, the folks at NPM have created the SemVer calculator.
Over the past few years, developers may have noticed that a particular package they used has version numbers that increment quickly. While the package authors may be prolific coders, another possibility is that the package is using "Semantic Versioning" or SemVer.
The goal of SemVer is to allow package consumers to reliably determine if a dependency upgrade will break existing code. According to the SemVer website, the versioning pattern is as follows:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Based on this recipe, whenever a package introduces a breaking change, the MAJOR version number should increment.
In the NPM post, Lin Clark say they decided to make the tool because of SemVer's intracacies:
[Kent Dodds] was looking for a semver range for Angular that would include everything in the 1.3.x range and would also allow the beta version of 1.4.0. It turns out that there is a range which allows that, 1.3.x || >1.4.0-beta.0, but when I asked around, very few people knew that… including folks at npm.
Speaking about lodash, John-David Dalton explains why it uses semver:
By following semver, devs can better plan when to update their lodash dependency and can trust that their code won't break out from under them due to a minor/patch update from lodash. They'll know that a patch bump is bug fixes, a minor bump is new features (and possibly bug fixes), and a major bump has back-compat breaking changes.
Not everyone is a fan of SemVer. According to Jeremy Ashkenas, creator of CoffeeScript, "It's alright for robots, but bad for us."
SemVer tries to compress a huge amount of information — the nature of the change, the percentage of users that will be affected by the change, the severity of the change (Is it easy to fix my code? Or do I have to rewrite everything?) — into a single number. And unsurprisingly, it's impossible for that single number to contain enough meaningful information.
The result is a contrast in the way packages are versioned. For example, Underscore.js does not use SemVer and is currently at version 1.8.3 while lodash, the fork of Underscore, is now at version 3.6.