CockroachDB Release Cycle

Overview

CockroachDB targets a supported major release every 3 months, breaking down that time period into 2 months of development and 1 month of stabilization. For example, v24.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, v24.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 v24.1 is current, v24.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

Historically CockroachDB released in May and November every year. In 2024, we added two Innovation Releases (“skippable” releases), released in February and August.

The first two 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 third month sees a switch from development to stabilization, where the only allowed changes are fixes needed to unblock delivery of a successful GA. Any high risk development that hasn’t had enough time to “bake” before the start of the stabilization period should be gated behind a setting.

Development: February - March

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.

Focus Shift/Wind Down: Late-March - Mid-April

Primary feature development for the release begins to wind down and a focus shifts to stabilization, testing, bug fixing, and polishing, in order to ship a beta candidate by the start of stabilization. Any minor feature development that takes place during this time should be low risk. This work takes place on the master branch.

Stabilization: Mid-April - Mid-May

Feature freeze: all effort is directed towards unblocking the delivery of a successful GA. This is when we cut the release branch, which minimizes the burden of backporting fixes.

Beta candidates take the place of the alpha releases and are released every week. 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).

Development: May - June

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

For current release dates, see the CRDB Release Dashboard, which follows our Release Support Policy.

Branching

Development primarily occurs on the master branch during the last few weeks of the previous cycle and the first two months of the new cycle. The latter part of this development cycle sees 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 24.1 release has a branch named release-24.1 and a tag named v24.1.0. The 24.1.1 release was performed on the release-24.1 branch and has a tag named v24.1.1.