Semantic Versioning – Why is Build.Number an ‘Abuse’ of Semantic Versioning?

buildscontinuous integrationcontinuous-deliverysemantic-versioningversioning

I was explaining a proposed build system (Gradle/Artifactory/Jenkins/Chef) to one of our senior architects, and he made a comment to me that I sort of disagree with, but am not experienced enough to really weigh-in on.

This project builds a Java library (JAR) as an artifact to be reused by other teams. For versioning, I'd like to use the semantic approach of:

<major>.<minor>.<patch>

Where patch indicates bug/emergency fixes, minor indicates backwards-compatible releases, and major indicates either massive refactorings of the API and/or backwards-incompatible changes.

As far as delivery goes here is what I want: a developer commits some code; this triggers a build to a QA/TEST environment. Some tests are ran (some automated, some manual). If all tests pass, then a production build publishes the JAR to our in-house repo. By this point the JAR should be versioned properly, and my thinking was to use the build.number that is automatically generated and provided by our CI tool to act as the patch number.

Thus, the versioning would actually be:

<major>.<minor>.<build.number>

Again, where build.number is provided by the CI tool.

The architect dismissed this, saying that using the CI build number was an "abuse" of semantic versioning.

My question is: is this correct, and if so, why? And if not, why not?

Best Answer

Your build number won't be reset to 0, when minor and major versions increase, this violates sections 7 and 8 of the specs:

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.

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

So, version numbers (major, minor, patch) must be provided manually, as these are used to tell your users about changes in one place without them having to look at your changelog or some other document.

If you want to include your build number, then you may append them after a + (section 10):

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

Related Solutions

Semantic Versioning – Allowing 4 Components in Version Numbers

It sounds like you are bypassing normal conventions just to avoid process overhead/audits. That... strikes me as concerning.

What you are doing is effectively making an extra version number (your minor PCI digit) somewhat intentionally in order to move your feature/minor version numbers back a place, to no longer trigger your internal audit criteria.

Anyways, getting to your question about semantic versioning, the spec for Semantic Versioning states:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

MINOR version when you add functionality in a backwards-compatible manner, and

PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Emphasis mine.

So the question is, are you using the fourth character for pre-release/build metadata? Or is it basically another version indication that you are releasing?

If "yes" then semantic versioning's spec does allow for it. If "no" then you technically are not following semantic versioning.

And as a higher-level and more arguable side question, does it really even matter?

Whether you want to rigidly follow it or not is a decision you and your team have to make. The purpose of semantic versioning is to help with API compatibility:

Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

I call this system "Semantic Versioning." Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.

It's a system that helps make it more clear when versioning affects downstream users of the API.

As long as your API is similarly clear it's not a huge deal which way you choose. Semantic versioning just happens to be straightforward, for example if I'm using 3.4.2 and need to upgrade to 3.4.10 I know I can do so without breaking anything. If the new version is 3.5.1 I know it's backwards compatible. And I know version 4.0.1 would be a breaking change.

That's all part of what the version numbers mean.

@enderland Yes basically. MAJOR(PCI).MINOR(PCI).FEATURE.HOTFIX+BUILD. We're basically only allowed to change the 3rd and 4th component without getting PCI (and subsequently the PCI overlords at the company) involved. To me it feels like this is a bit contrived, I am not sure they are justified in the way they manage the version number, but I do not know enough about PCI and audit process to say otherwise.

Ok, this is fine. You have a system which works for you and meets your needs. That's the point of versioning.

If your API is private (only internally facing) it really doesn't matter how you version as long as it makes sense to you and everyone using it. Where versioning in a standard format matters is when you have many other consumers of your API that need to know "what does this version mean?"

Having an arbitrary versioning system will confuse people who are used to other systems, such as semantic versioning. But if no-one is really using your versioning system except the people creating it - it doesn't really matter.

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

Semantic Versioning – Allowing 4 Components in Version Numbers

Semantic Versioning in OpenAPI with Enum Strings

Related Topic