Version 2 of Semantic versioning

Updated 2016-07-07 20:21:20 by EMJ

Semantic versioning or SemVer is an approach to API versioning that says roughly the following:

  • Your version number should have the format "MAJOR.MINOR.PATCH" where each of MAJOR, MINOR and PATCH is an integer >= 0.

Once you hit 1.0.0

  • Increment MAJOR when you break compatibility;
  • Increment MINOR when you implement features or deprecate features without breaking them;
  • Increment PATCH when you fix bugs;
  • If you increment MAJOR reset MINOR and PATCH to zero; if you increment MINOR reset PATCH to zero.

There is a specification for semantic versioning that goes into more detail at http://semver.org/ .

There is a proposal to use Semantic Versioning for Tcl in TIP 439 .

bll 2016-7-7: The specs state:

9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen 0-9A-Za-z-. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its 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.

(and 11. for precedence)

But I have found that normal people assume that 3.1.1a is a later version than 3.1.1. Some software uses 'rc' to indicate a "release candidate", but even so, regular people who are not cognizant of that will assume that it is a later version.

I am thinking that perhaps using the odd numbers as development only versions would work out better. e.g. 4.2.0 (release), 4.2.1a (dev) 4.2.1b (dev), 4.2.1c (dev), 4.2.2 (release), 4.3.0a (dev), 4.3.0b (dev), 4.4.0 (release). Then the version numbers always have a progression from smallest to largest. No strange precedence comparison code to strip off the trailing -dev or other characters in order to do version comparisons (which I have in my code now).

I disagree with changing the major number only when it breaks compatibility, but that's an opinion, and there can always be a separate public version number and internal version number.

EMJ 2016-07-07:

What are normal people and regular people and how do you tell them apart? :-)

More seriously, 3.1.1a does not match the Semantic Versioning specs, it would need to be (at minimum) 3.1.1-a, and the examples in the specs would make it 3.1.1-alpha which is a lot more obvious.

The odd/even thing is fairly common, but not at all obvious to "normal" people. Does everyone who uses it use it the same way round? If not it's even less obvious. You have version comparison code? For what, and why?

For software using Semantic Versioning, "normal" people should be advised never to go anywhere near a version with a "-" of "+" or both in it unless they know exactly why they need that specific version.

I'd like an example of a non-compatibility reason for changing the major number (so that I can try to demolish it of course).

Separate public version and internal version numbers are a very bad idea indeed unless there is zero chance of ever mistaking a occurrence of one for an occurrence of the other, so one of them would have to be of a totally different format from the other. This is why so many unreleased things have code names.

Category Concept