Semantic Versioning

By eidias on (tags: versioning, categories: architecture)

We’ve been using semantic versioning for a while now and it’s been paying out. Though there were some ‘quirks’. Now, version 2.0 is (almost) out and guess what, it addresses them! Let’s take a look at the new version and see what changed.

I’m going to start with a little propaganda. Why you SHOULD use semantic versioning or at least some sort of reasonably (though that’s subjective) described versioning scheme instead of using just a build number, or the day of the week.

So what’s the reason behind choosing semver?

First of all, it ‘just makes sense’™ – think about it.
Second of all, it has clearly defined rules and guides on when to change what, which makes your life easier. The time and effort should go into the application itself, not it’s version number.
Third, it gives you a clear indication on the history and well, the future – yes, a timestamp does the same, but it’s hardly as readable.
Fourth, it gives you an indication on how much has changed – if it’s just a minor release or a release that may make you change your code or habits.

With that out of the way, let’s get to the point:

Changes in semver 2.0.0 (-rc.1)

CHANGE - Version segments as non-negative integers

2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically by increments of one. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

A minor change here – previously it stated that the numbers were integers, now it’s non-negative integers

CHANGE - Deprecated functionality increases the minor version

8. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

The new bit here is the part about deprecated functionality. Apart from that, nothing else has changed.

CHANGE – Pre-release versions

10. A pre-release version MAY be denoted by appending a dash and a series of dot separated identifiers immediately following the patch version. Identifiers MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-]. Pre-release versions satisfy but have a lower precedence than the associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Parts of this rule were previously stated in point 4. of semver 1.0.0. In essence – previously a version of 1.0.0-rc.1 was invalid (though 1.0.0-rc1 was valid), now it’s ok - notice the dot.

NEW – Build number as part of product version

11. A build version MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch version or pre-release version. Identifiers MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-]. Build versions satisfy and have a higher precedence than the associated normal version. Examples: 1.0.0+build.1, 1.3.7+build.11.e0f985a.

NEW – Version precedence calculation

12. Precedence MUST be calculated by separating the version into major, minor, patch, pre-release, and build identifiers in that order. Major, minor, and patch versions are always compared numerically. Pre-release and build version precedence MUST be determined by comparing each dot separated identifier as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or dashes are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0-rc.1+build.1 < 1.0.0 < 1.0.0+0.3.7 < 1.3.7+build < 1.3.7+build.2.b8f12d7 < 1.3.7+build.11.e0f985a.

REMOVE – The part about SemVerTag is gone

Not sure why, but the vcs tagging guides have been removed.