How it works
SemVer 2.0.0 says: given a version number MAJOR.MINOR.PATCH, increment
- MAJOR when you make incompatible API changes,
- MINOR when you add functionality in a backward compatible manner,
- PATCH when you make backward compatible bug fixes.
A pre-release label hangs on with a hyphen, as in 1.0.0-rc.1, and build metadata with a plus sign, as in 1.0.0+20130313144700.
Precedence, the part apps get wrong
The specification defines the order. The first difference, read left to right, decides:
- Major, minor and patch are compared as numbers:
1.0.0 < 2.0.0 < 2.1.0 < 2.1.1, and1.9.0 < 1.10.0. - A version with a pre-release has lower precedence than the same version without one:
1.0.0-alpha < 1.0.0. - Pre-release identifiers are compared one by one. Digits-only identifiers compare numerically, others compare in ASCII order, and numeric ones rank below text ones. A longer set ranks higher if everything before it is equal.
The specification’s own chain:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
< 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0
Tested: where a naive comparison fails
The Clavem docs show an update check that compares versions as dotted numbers with localeCompare(..., { numeric: true }) and warn that pre-release tags need a semver library. Here is the difference, run with Node and the semver package (the results are 1 for “left is newer”, -1 for “left is older”):
| Left | Right | Naive numeric compare | semver.compare |
|---|---|---|---|
| 1.9.0 | 1.10.0 | -1 | -1 |
| 1.0.0-beta.2 | 1.0.0-beta.11 | -1 | -1 |
| 1.0.0-rc.1 | 1.0.0 | 1 | -1 |
| 2.0.0-beta.2 | 2.0.0 | 1 | -1 |
A plain string sort is worse: it puts 1.10.0 before 1.9.0. The naive comparison treats a release candidate as newer than the final release, so an app on 2.0.0 could be offered 2.0.0-beta.2 as an upgrade.
SemVer versus a marketing version
Users see “Inkwell 4”, while the build is 4.0.2. A marketing name is for people. The version string in the update check is for machines, and must sort correctly. Keep both.
How Clavem handles it
Clavem takes a release version of up to 64 characters: letters, digits, dots, dashes, plus signs and underscores, so 3.2.1 and 4.0.0-beta.2 are both valid. A product cannot have the same version twice. Clavem does not sort versions. The latest release is the one most recently published, not the highest number, and your app decides what counts as newer. If you use pre-release tags, compare with a semver library, as the table above shows. What a MAJOR bump means commercially is covered in upgrade pricing, and tracks such as beta in release channels. See Releases and downloads for publishing.
Questions
Does build metadata affect version order?
No. The SemVer specification says build metadata does not figure into precedence, so 1.0.0+20130313144700 and 1.0.0+exp.sha.5114f85 have the same order.
Should a desktop app use SemVer?
The specification is written around public APIs, so for an app the number is a convention you choose. Many apps use MAJOR for a release big enough to charge for again, which is a pricing decision, not a SemVer rule.