Why we're switching to calendar versioning

Last edited on February 25, 2019

0 minute read

    One small step for Cockroach Labs, one giant leap for our release numbering.

    Since our initial launch, Cockroach Labs has used semantic versioning in our release cycle guidelines. Two years, one major release, and n-patch fixes later, we're making the switch to Calendar Versioning. This means subscribers to our release notes will see quite the jump in today's version numbering, from last week's 2.1.5 to today's 19.1 beta.

    Why the switch?

    While working on our upcoming April release, we kept butting up against some problems with our semantic versioning system. We knew the next release would be significant for our community and user base. Among other things, it includes a cost-based optimizer that can complete the TPC-H benchmark, CDC, and two major enterprise security features. But was this enough of a value jump to merit the leap to 3.0? Or was this a 2.2? Strictly following the semantic versioning rules would specify 2.2, as there are no backwards incompatible API changes. But with that logic guiding the major version bump, we could potentially remain on 2.x forever.

    We wanted to find a solution that would minimize frustration (and time-consuming meetings) internally, while setting the correct expectations with users around quality and stability.

    Switching to calendar versioning side-steps versioning discussions now and in the future, and helps us (and our users) avoid the confusion around the significance of a release. It also eliminates the mental gymnastics needed to figure out how old a release is or how much time has elapsed between two releases.

    Another significant advantage of this approach is that naming guidelines are essentially baked in. Since we release on a 6 month cadence, we're starting to name releases by season and year, which means our next release is now CockroachDB Spring '19. Keep your eyes peeled.

    Notes on numbering

    A couple details on the semantics of our numbering system: we're using a two-digit year for the major component and release number within the year for the minor one. We chose release number rather than two-digit month to reduce the chance users inadvertently violate our constraint that we don't support skipping versions for upgrades.

    For patch releases, we'll use the third, "micro" number in the versioning scheme to indicate the patch number, omitting the micro number on the first release number for external representations of the version number. Our Spring '19 (formerly 2.2) release will now be 19.1. Our Fall '19 release will be 19.2, the first patch version in Fall will be 19.2.1.

    For more information about today's beta and our upcoming release, check out today's release notes.

    New to Cockroach? Click here to install CockroachDB.