Why Explicit Versions Still Don't Solve the Problem

Jul 16 2016

Explicit Versioning, the latest attempt at solving version naming problems, still doesn't quite cover the normal use cases I encounter daily. But it does capture an idea that SemVer doesn't.

A fascinating blog post on explicit versioning is making the rounds. It proposes a new versioning scheme based on a simple formula: release.breaking.feature.fix.

Comparing it to SemVer shows both its weaknesses and strengths.

Starting from SemVer

Semantic Versioning is a well-defined way of versioning software. It is deployed broadly, and it packs a fair amount of meaning into a common mode of expression.

Here's the SemVer numbering scheme in a nutshell. A semantic version indicator follows this structure:

X.Y.Z-P+B

Where...

  • X is an integer representation of a MAJOR release. This indicates that the present version is incompatible (in some important way) with any other MAJOR version number.
  • Y is an integer representation of a MINOR release. This indicates that the present version has more features than any smaller MINOR version for the same MAJOR version. (e.g. 1.2 has more features than 1.1, but is also backward compatible with 1.1)
  • Z is an integer representation of a PATCH release. This indicates that the present version has more fixed bugs than any smaller integer of the same MAJOR.MINOR tree. That is 1.1.2 has more bugs fixed than 1.1.1, but is compatible.
  • P is a pre-release indicator, such as alpha.2 or beta. This indicates that the entire release is not considered production-ready.
  • B is a build indicator. It carries arbitrary information to distinguish it from other builds of the same source code. This is used by package managers, CI/CD systems, and other tools that operate on software. Importantly, B is not used in version comparison.

Given this, a few valid versions are:

1.2.3
500.1.77-alpha.4
3.2.1-beta+aaf3434343477888

Over and above this specification, the SemVer spec explains how versions can be compared.

SemVer is used broadly (and mis-used even more broadly). It captures many important bits of versioning information. But might we do better?

Explicit Versioning

The idea behind Explicit Versioning is that it can improve upon Semantic Versioning by adding a fourth digit and (apparently) removing the Pre-release and Build indicators. So the Explicit Versioning scheme looks like this: R.B.F.X ('Release.Breaking.Feature.fiX')

In this scheme...

  • R is the Release number, described as user-recognizable product number. I'm not totally clear on what that means because it doesn't say anything about properties of the software.
  • B is for backwards-compatibility breaking changes.
  • F is for non-breaking feature additions.
  • X is for bug fixes.

So the last three digits in Explicit Versioning seem to correspond pretty much exactly to their SemVer counterparts.

Explicit Versioning still needs more

Without pre-release and build information, many typical uses of version numbering cannot be accomplished.

  • There is no way to indicate that the current version has new features and fixes, but is not yet considered ready for production usage. Or, to say it plainly: No alpha and beta.
  • There is no way to indicate that two versions contain the same code, but were built at different times and perhaps by different build chains.

I'd be perfectly happy to see those things represented as integers (if possible). But these things were expressed as (in the words of the Explicit Versioning author) "walls of text" because we don't have an agreed-upon standard of how to represent pre-release and build information other than with text.

While we lose two important pieces of information in explicit versioning, we gain a new one: release number.

What Does the Release Number Do?

Now we're up to the most important point in the Explicit Versioning scheme: The release number. This is the very first number in the scheme, ostensibly because it is the most important.

The release number is described as something that is "important to the user". That is vague enough to be non-prescriptive. But I think I get what the idea is.

Think of various large projects. Given what I'm working on these days, Docker and Kubernetes jump to mind for me. These are projects that have many complex moving pieces. And these are also projects that attach a large amount of social importance to version number.

Neither of these projects (correctly) uses Semantic Versioning. In fact, both projects frequently break compatibility, but only increment the minor release number (the Y in X.Y.Z). The reason they do this is not because they've accidentally broken something or because they don't care about the user. It's because incrementing the major number (X) falsely signals the user base. It signals a fundamental and disruptive change.

That is the sort of change that SemVer does not accommodate.

Explicit versioning makes it possible to signal a fundamental change, and that is what makes the new release number a powerful concept.

Is it time for change?

Four numbers may be better than three. The release number does add something we didn't have before. But I haven't found explicit versioning to be clearly articulated yet. Until it can articulate a strategy for pre-release versioning and a strategy for build information, it can't accomplish the basics.

But what explicit versioning has made strikingly clear is that SemVer proponents have missed a really big piece of the puzzle. And part of the reason why SemVer is so frequently mis-applied is precisely because of this omission.

The reason that major projects cannot practically utilize SemVer is not because of organizational inertia. It's because they need to reserved that first number to indicate something of importance.

Maybe it is time for another revision of versioning.