Moving to semantic versioning in 2019

Linc

I wish I could have back the dozens of hours I've spent pondering and debating how to number the versions of our product.

It's one of those topics that seems very straightforward at first blush, and gets incredibly complicated when you fully consider the logistics of running a codebase that is both continuously deployed to cloud (but at different intervals to different parts of the cloud) and periodically distributed as an open source build. Add a sprinkling of historical precedent and expectations-setting, and it gets worse.

After much discussion, the product team has agreed with my proposal to move to [semantic versioning] as of our next non-patch release following 2.8.

From semver.org:

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

1 - MAJOR version when you make incompatible API changes,

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

3 - 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.

We're going to take a non-strict view about what constitutes an incompatible change. For instance, adding a CSS class to something in our views could technically be considered a breaking change in our theming paradigm, but it's extremely unlikely to actually affect anyone, so that would not constitute a breaking change.

Internally, this clears up confusion about how and when to change the version number. I'll be honest, it's mostly just been whatever I decided to make it for the last 7 years. We had a general pattern, but the decision was fairly capricious. It also absolves us of the perennial debate about whether a feature is "big enough" to do a major version increment. Less debate, more releasing.

For open source, it should hopefully clear up what level of breakage you might experience in an upgrade. To modernize our codebase, we may remove some things in the coming year. It seems useful that a full-number increase to the version number would alert folks to do extra testing before upgrading.

Practical summary:

This change makes it very likely (but not certain) that the next non-patch release of Vanilla will be 3.0.

In the future, our version number will likely move up very quickly compared to our historical trend.

We will continue to number the 2.8 series according to our old method, which is to simply add a third number for any level of change. Thus the first security or functionality patch will be 2.8.1.

On `master` and cloud, we will use a build or pre-release number to avoid overlapping with open source release numbers.