Does Semantic Version use zero-based numbering

semantic-versioningversioning

Does 1.0.0 represent the first patch of the first minor version of the second major version? Or does it represent the first major version, with no minor or patch versions? I've always assumed it to be the latter, and it seems so have many others. I typically see new packages in various package management systems start out at 0.1.0, which I've always assumed to be the first minor release.

I was surprised to see this wasn't explicit in the spec. It can be implied from points 4, 7, and 8, but it's never stated. Surely there must be a right or wrong answer here? If there is a simple answer to this question shouldn't it be stated somewhere in the spec?

Best Answer

Semantic versioning 2.0.0 clarifies this point explicitly:

The major version is 0 for unstable initial development, before the first stable API version is published:

4. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

It also clearly states that the first public version starts at 1.0.0:

5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

The wording of clause 8 is not explicit, on purpose:

8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced

The wording makes clear that any major version must be strictly greater than 0 and that it has to be incremented in case of major change. But the wording leaves it open to have a version 0 for which the constraint doesn't hold, because for version 0, any change can happen any time, without need for formal increments.

Semver herewith uses the logic of mathematical induction: if you prove something for an initial starting iteration, and demonstrate if the property is true at one iteration, it's true for the next, then it's true for all the iterations starting with the initial one.

These principles are not new and were already true for earlier versions (e.g. semver 1.0.0) although with some differences in paragraph numbering.

Related Solutions

What version numbers should I assign to builds on different branches as part of continuous integration for NET Core-based projects

You need to better understand the specific requirements you have from versioning.

Most of my cases are end user applications. In this scenario a single version number is sufficient, all I require from the version is to match it to a commit ID.

Other, less frequent, cases are libraries. In this case there is an additional requirement to match to an API version. v123.2 and v124.1 refers to API versions 124 and 123, while 1 and 2 refers to a sequential patch number (it might refer to some bug corrected in both API versions).

This a summary of my requirements. You need to understand yours and be aware to not fall to a situation where mantaining version numbers hinders development, that is not the point. Latelly I've been using a build process to inject the actual commit id, but not sure if I like it that much.

Semantic Versioning in OpenAPI with Enum Strings

It's my understanding that you have to increment the major version number if your code introduces breaking changes.

If Thing is used strictly for input and you're now accepting a couple of new values, then you won't break any existing code.

However, if you're returning Thing and I have code like

switch (myThing) {
    case PreExistingValue1:
        doProcess1(myThing);
        break;
    case PreExistingValue2:
        doSomethingElse();
        break;
    default:
        throw new NotImplementedException();
}

returning new values will break my code. That's something I'd like to know about.

Best Answer

Related Solutions

What version numbers should I assign to builds on different branches as part of continuous integration for NET Core-based projects

Semantic Versioning in OpenAPI with Enum Strings

Related Topic