SemVer: Don’t be afraid of Major Versions

On multiple occasions over the last couple months I have experienced the phenomenon where the rules of SemVer are bent to avoid a major version. One such case is what I am calling the marketing problem.

There isn’t anything BIG enough to warrant a major release.

And with that, I set out to explore my options…

Warning: The following approaches to the problems of major versions are bad!

Vanity Numbers (marketing.major.minor.patch)

This isn’t without its challenges. For example, a library may be at 1.2.10.3 and a large external event triggers a change the version 2 of the library. If it is merely a vanity number, should the new version be 2.0.0.0 or 2.2.10.3? Note that this doesn’t work with some tools such as NPM.

Prerelease Versions (major.minor.patch+something)

Still waiting for marketing to approve your version 2 release, then use a prerelease flow. Instead of jumping straight to 2.0.0, use the following progression and precedence: 2.0.0-alpha.1 > 2.0.0-beta.1 > 2.0.0-rc.1 > 2.0.0-rc.2.

The issue here is that library users may have something similar to ^1.10.3 in there dependency list as is the case for NPM. This now requires two branches while waiting on the release of the major version so that patches can be applied to current users.

Public Versions (Foo 2, 1.36.2)

This approach assumes the two versions become decoupled. Unfortunately, this is never the case and the history of Angular releases should be enough to warn us against it. The gist is that a package having a version of 1.36.2 or 3.0.1 does not make sense when the package is publicly being called version 2 in marketing.

Note: The following approaches are less bad.

Calendar Versions (2020.3.1)

For some, this is equivalent to saying I give up on semantic versioning. For others, it is an acknowledgment that semantic versioning is nearly impossible for their specific case. The calendar approach completely removes marketing and pushes the challenges on the user.

Cheap Major Versions (123.11.2)

This may be the least bad approach for most libraries. In reality, 99% of us maintain a package where no one cares about marketing or the fact that we are on a major version in the triple digits. It’s cheap, easy, and has the best usability for developers and their tools.

Caveats

Semantic versioning is not without flaws. Consider that one developer’s bugfix may be another’s breaking change.

As one Hacker News commentator put it:

Why are we relying on fallible humans to examine an API and encode an assertion about its backwards compatibility into a number?

Or as another stated in their critique of semantic versioning:

Basically, Romantic Versioning, not Semantic Versioning.