CockroachDB Release Cycle

Owned by Peter Mattis
Last updated: Jun 22, 2021 by Raphael ‘kena’ Poss (Deactivated)

Overview

CockroachDB targets a supported major release every 6 months, breaking down that time period into 5 months of development and 1 month of stabilization. For example, v21.1 is a major release. A major release is maintained by issuing periodic patch releases to fix crashes, security issues, and data correctness issues. For example, v21.1.2 is a patch release.

In between the supported major releases, monthly alpha releases are performed for the planned next major release. For example, when v21.1 is current, v21.2-alpha.1 is an alpha release. The alpha releases see one week of testing before release and are considered unsuitable for production usage. They are intended for users who need early access to a feature before it is available in a stable release.

Timeline

The CockroachDB release cycles start on April 1 and October 1. The cycle dates were originally chosen to offset from the Go release cycle so that a major release of Go will precede a major release of CockroachDB by 2 months, though historically we have not upgraded to the latest Go release before a CockroachDB release.

The first four months of a release are used for primary development work. The riskiest changes should be worked on first in order to provide the most time for discovering unexpected issues. The fifth month sees a gradual switch from primary development to stabilization, though minor (low risk) feature development may take place. Any high risk development needs to be signed off on by managers and TLs and should be gated behind a setting.

April 1 / October 1

The previous release ends and development on the next release begins. Development occurs on the master branch. The new cycle does not begin if the previous cycle was delayed for any reason.

August 1 / Feb 1

Primary feature development for the release begins to wind down and a focus shifts to stabilization, testing, bug fixing, and polishing. Minor feature development may take place in the fifth month of the cycle, but that work should be low risk.

September 1 / March 1

Feature freeze: all effort is directed towards bug fixing, and testing. This work takes place on the master branch. The release branch is cut shortly before the release in order to minimize the burden of back porting fixes. Multi person feature development can take place on feature branches.

Beta candidates take the place of the alpha releases and are released every week starting at the end of the fifth month. The beta releases are not expected to be bug free and should not be used in production settings where data loss or corruption cannot be tolerated. The beta releases are expected to see a decline in issues leading up to the release (i.e. later beta releases should be more stable than earlier ones).

August 15 / February 15

Planning begins for the upcoming cycle, soliciting input from users and developers.

October 1 / April 1

The previous release ends and development on the next release begins.

Version Naming Convention

As of Spring 2019, CockroachDB follows a calver scheme: <2-digit-year>.<release#>.<patch>. The first release following this scheme is 19.1. The <release#> portion of the version corresponds to the 1-based count within the year of the release. So the first release in a year is .1, the second is .2, the third (if such ever occurs) is .3. Prior to the switch to calver, CockroachDB nominally followed semver, though we bumped the major version number without breaking backward compatibility. The switch to calver provides regular progression of the major number without argument and discussion of whether that follows semantic versioning.

All versions post-1.0.0 should sort correctly with github.com/hashicorp/go-version and sort --version-sort. This ensures compatibility with downstream package managers’ version ordering. Note that the calver scheme is compatible with the previous semver scheme in this regard. Importantly, alphabetic components (e.g. beta, rc) can only appear after a - character, and must be separated from any following numeric components by a . character to ensure that e.g. 1.1-rc.2 sorts before 1.1-rc.10. For example, the following tags sort in the listed order:

  • 20.1 (official major release - also named 20.1.0 internally)

  • 20.1.1 (official patch release)

  • 20.2-alpha.1 (alpha release)

  • 20.2-alpha.2 (alpha release, second alpha)

  • 20.2-beta.1 (beta release)

  • 20.2-beta.2 (beta release, second beta)

  • 20.2-rc.1 (first release candidate)

  • 20.2-rc.2 (second release candidate)

  • 20.2 (final major release)

There are some legacy cases:

  • pre-1.0 beta releases were tagged beta-YYYYMMDD, which incorrectly compares as greater than 1.0.0, even with version-aware sort orders.

  • pre 20.1-beta, alphas and betas were named alpha.YYYYMMDD and beta.YYYYMMDD, which sorted correctly.

Code that must handle old CockroachDB versions, like our registration cluster, must special-case versions that begin with beta-, but should not expect to special-case any future versions.

Release Maintenance

Patch releases for the previous major release are issued periodically to fix crashes, security issues, and data correctness issues. A reasonable balance is maintained between fixing serious issues and potentially causing additional destabilization via the fix. Note that in this context, a major release corresponds to <major>.<minor> (i.e. a release that occurs every 6 months). Historically, patch releases for the previous major release are performed once a month. The schedule is not rigid, and faster patch releases have been performed to fix significant bugs or to work around holiday calendars.

Patch releases of older major releases are issued as needed to fix serious issues that are affecting customers.

Branching

Development primarily occurs on the master branch during the last month of the previous cycle and the first four months of the new cycle. The end of the fifth month of each cycle sees a freeze on feature development and a focus on testing, bug fixing, and polishing which occurs on the master branch.

Each release has a corresponding release branch named release-<major>.<minor>. Each release has a tag named v<major>.<minor>.<patch>. For example, the 1.0 release has a branch named release-1.0 and a tag named v1.0.0. The 1.0.1 release was performed on the release-1.0 branch and has a tag named v1.0.1.



Copyright (C) Cockroach Labs.
Attention: This documentation is provided on an "as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or conditions of title, non-infringement, merchantability, or fitness for a particular purpose.