SemVer Prerelease and Metadata

SemVer for major, minor, and patch are simple to understand. What about prelease? Here's a quick post for the that, and also about the build metadata.

Prerelease

So, is there a predefined list of prereleases in SemVer? No, it can actually be anything (well, as long as it follows the limitation specified in the BNF). The following are common in the industry for published APIs:

• alpha
• beta
• rc

So how do SemVer implementations, such as npm, know that alpha is before beta, and beta is before rc? As per SevVer 2.0 #11 spec, it's basically checking the ASCII string sort order — and alpha, beta, and rc happen to be in the correct sort order that we want.

Metadata

Sometimes you might see a date string appended to the version number, such as 1.0.0+20190826, and those are called build metadata, and should be ignored in SemVer comparison. Note that they must start with a plus sign, and prereleases must start with a hyphen.

Examples

Here are some examples using the semver package in interactive Node.js, including what happens when the prerelease characters are same but are different in lengths, and mixing capital letters, etc.

User@COMPUTER MINGW64 /c/dev/npm/semvertest
$ npm i --save-dev semver
User@COMPUTER MINGW64 /c/dev/npm/semvertest
$ node
Welcome to Node.js v12.7.0.
Type ".help" for more information.
> const semver = require('semver');
undefined
> semver.gt('1.0.0-aaa', '1.0.0-aaaa') // length difference
false
> semver.gt('1.0.0-abaa', '1.0.0-aaaa') // letter difference
true
> semver.gt('1.0.0-A', '1.0.0-a') // ASCII(A) = 65, ASCII(a) = 97
false
> semver.gt('1.0.0-aaa.1', '1.0.0-aaaa.5') // length difference variation
false
> semver.gt('1.0.0-a.256', '1.0.0-a.64') // number in prerelease
true
> semver.gt('1.0.0-a.aaa', '1.0.0-a.bb') // same length as above, but not a number
false
> semver.gt('1.0.0-a.3.b.8', '1.0.0-a.4.b.7') // period separation - not just last number.
false
> semver.eq('1.0.0-aaa+2019-08-26', '1.0.0-aaa+MetaDataHere') // Build metadata are ignored
true