We publish detailed release notes describing changes that impact external users of CockroachDB. Engineers provide "Release note" texts in their cockroach repo commits. These are then aggregated and edited by the Docs Team. This page provides guidance on when and how Cockroach Labs engineers should write these texts.

This information is also provided as a CockroachU course to all new hires, though all current roachers are welcome to review it. The course largely tracks with this wiki page. It does not contain the the detail on release note categories. For feedback on the course, contact @Doug Weatherbee . For other release notes questions, contact @Michael Lewis.

Who is the audience for release note texts

Release notes are primarily for external users, that is, users of CockroachDB who are not employees of Cockroach Labs. Roachers in different parts of the company are also an audience, but release note texts should not be written exclusively for them. For example, if a product change applies only to an internal user group (internal to CRL, e.g. the change only affects CC and is only visible to SREs), we should not write a release note text that gets included in the public release note docs (and added to the Docs team queue of potential documentation work).

Note that a change that affects the operation of CockroachDB in Self-hosted, for example how to run or administrate a cluster, deserves release notes because it needs to be documented for our customers' SREs that run the Self-hosted clusters.

When to write release note texts

Write release note texts for changes that impacts external users, for example:

Changes to how users interact with or experience the product
- Examples: New/changed functionality, backward-incompatible changes, build dependencies, UI changes
Changes to how the product behaves
- Examples: Performance changes, command response changes (that aren't backward-incompatible), architecture changes

Do NOT write release note texts for internal changes, such as:

Functionality that is not accessible to, or intended for, external users (e.g., multi-tenant capabilities)
Code refactors
Testing/infrastructure work

How to write release note texts

1 High-level rules
2 Format
3 Categories
- 3.1 Cloud Categories
4 Descriptions
5 Examples
- 5.1 Enterprise change
- 5.2 Bug fix
- 5.3 Backward-incompatible change

High-level rules

Every PR should have at least one “Release note” text.
- If a PR is missing a "Release note" text, the script will put it in a "Changes without release note annotation" section, and the Docs team will have to investigate. This can be time-consuming.
Ensure “Release note” texts are in commit messages and optionally copied into PR descriptions.
- If they are only in PR descriptions, they will not get picked up.
- If a commit covers multiple user-visible changes in different areas (e.g., a bug fix and a performance improvement), write multiple, distinct release note texts within the same commit message.
Put "Release note" texts at the end of commits.
- Everything after each "Release note" annotation gets picked up by the script.
Exclude changes to reserved interfaces from release notes. Refer to the table of interfaces in the API Support Policy. This is new guidance!

Format

To include a release note texts in our published release notes, use: "Release note (<single category>): <description>".
- For guidance on choosing the right category, see Release note categories.
- For guidance on writing a good description, see Release note descriptions.
To exclude a release note text from our published release notes, use: "Release note: None".

Categories

In your release note texts, try to use the following categories verbatim to make sure your notes get placed in the right section of the generated release notes. The script tries to catch spelling mistakes and alternate categories that we have seen multiple times, but if it can't find a matching category, the note will be placed in a "Miscellaneous" section and the Docs team will have to investigate. ,

Only use one category per release note. When a commit falls into more than one category, choose the category that makes the most sense from a user perspective.

These categories are imperfect and will evolve over time.

Category	Valid alternate	Focus

Category	Valid alternate	Focus
`backward-incompatible change`	`backwards-incompatible change`	Backward-incompatible changes to CockroachDB interfaces. This may include changes to SQL statements, `cockroach` commands, logging, and endpoints that normally belong to another category. If the change is considered backward-incompatible (i.e., the change can break programmatic usage of an interface), use the `backward-incompatible change` label instead of the usual label. This is mandatory if the change applies to a stable CockroachDB interface (refer to the table of interfaces in the API Support Policy). If the change is introducing a new version number, also announce the new version number here. See example.
`enterprise change`	`enterprise`	Changes to CockroachDB features requiring an enterprise license, e.g., `BACKUP/RESTORE`.
`ops change`	`operational change`	Changes to cockroach commands and endpoints that affect primarily operators tasked with setting up and maintaining production clusters. This includes changes to logging configurations and behavior, additions or removal of metrics, health and monitoring endpoints, HTTP endpoints, environment variables, integrations with service managers, CLI flags for server commands, exit codes, etc.
`cli change`	`cli`	Changes to cockroach commands that affect primarily application developers, CockroachDB developers and contributors, and operators running experiments or small-scale testing/staging clusters. This includes changes to the SQL shells, `userfile`, `workload`, `debug` commands that operate on non-running servers, etc.
`sql change`	`sql`	Changes to SQL statements, functions/operators, system catalogs, or execution.
`ui change`	`ui`	Changes to the DB Console and any associated metrics.
`security update`	`security` `security change`	Changes that impacts the use of security features (IAM, TLS, etc.) or the security profile of the product.
`performance improvement`	`performance` `performance change`	Changes that improve performance, often at kv, storage, and SQL engine levels.
`cluster virtualization`	`multi-tenancy`, `virtualization`	Changes pertaining to the cluster virtualization and multi-tenancy infrastructure and that are potentially user-facing.
`bug fix`	`bugfix`	Changes that fix known problems as opposed to add or improve functionality.
`general change`	`general` `core change`	Changes that don't fit anywhere else. Only use this if you have no other good option. This might include changes to logs and user-facing configs for Kubernetes, Prometheus, Alertmanager, etc. We probably need new, meaningful categories.
`build change`		Changes to requirements for building CockroachDB from source.

This list is also documented in the commit message template, which lives in githooks/prepare-commit-msg.

Cloud Categories

The following categories should be used for release notes in the managed-service repo.

Category	Valid alternate	Focus

Category	Valid alternate	Focus
`General changes`	`general`	General changes and major feature releases (for example, multi-region capabilities for Serverless and support for Azure on Dedicated).
`Console changes`	`ui`	Changes to the Cloud Console and any associated metrics.
`Cloud API changes`	`api`	Changes that affect the Cloud API (for example, new endpoints or feature support).
`ccloud changes`	`ccloud`	Changes that affect the `ccloud` command line tool.
`Security updates`	`security` `security change`	Changes that impact Cloud security (for example, FGAC, PrivateLink, and CMEK).
`Bug fixes`	`bug fix`	Changes that fix known problems as opposed to add or improve functionality.

Descriptions

The release note description (the part after the colon) is obviously the most important part. Here are some best practices:

Default to more information than less.
- A thin/unclear release note text causes Docs writers to have to read the full PR description anyway.
Explain what changed, how it changed, and why it's relevant to users.
- For bug fixes, describing the cause and symptoms of the bug and since when the bug existed.
Use past tense (e.g., "Added the xxx statement...", "Fixed a bug...") or present tense ("CockroachDB now supports...", "It is now possible to...").
Note if the change is part of progress toward a broader feature on the roadmap.
- This is new guidance! But it will tremendously help the Docs team correlate granular changes to larger feature work.

Examples

Enterprise change

Rating	Text	Why

Rating	Text	Why
Poor	Release note (ccl): Default interval for the closed timestamp cluster setting is different.	Category is not valid. Description does not use requested format. We know a default changed but not the name of the exact cluster setting, how it changed, and why it is relevant to users.
Better	Release note (enterprise change): Shortened the default interval for the `kv.closed_timestamp.target_duration` cluster setting from `30s` to `3s`.	Category is valid. Description uses requested format. We know what changed, how it changed (shortened from 30s to 3s), but not why it is relevant.
Best	Release note (enterprise change): Shortened the default interval for the `kv.closed_timestamp.target_duration` cluster setting from `30s` to `3s`. This allows follower reads at 4.8 seconds in the past, a much shorter window than the previous 48 seconds.	Category is valid. Description uses requested format. We know what changed, how it changed (shortened from 30s to 3s), and why it is relevant to users (less stale follower reads).

Bug fix

Rating	Text	Why

Rating

Text

Why

Poor

Release note (bug): No more duplicate rows for CREATE TABLE ... AS

Category is not valid.
Description does not use requested format.
We know the symptom of the bug (duplicate rows) but not the cause and when the bug was introduced.

Better

Release note (bug fix): Fixed a bug that caused duplicate rows in the results of CREATE TABLE ... AS when multiple nodes attempt to populate the results.

or

Multiple nodes attempting to populate the results of CREATE TABLE ... AS no longer causes duplicate rows in the results.

Category is valid.
Description uses request format.
We know the symptom of the bug (duplicate rows), the cause of the bug (multiple nodes attempting to populate results), but not when it was introduced.

Best

Release note (bug fix): Fixed a bug introduced in v19.2.3 that caused duplicate rows in the results of CREATE TABLE ... AS when multiple nodes attempt to populate the results.

or

Multiple nodes attempting to populate the results of CREATE TABLE ... AS no longer causes duplicate rows in the results. This bug was introduced in v19.2.3.

Category is valid.
Description uses requested format.
We know the symptom of the bug (duplicate rows), the cause of the bug (multiple nodes attempting to populate results), and when it was introduced (v19.2.3).

Backward-incompatible change

If a backward-incompatible change is made to a stable CockroachDB interface, it must be categorized as such in the release notes. Refer to the list of backward-incompatible changes and the table of interfaces in the API Support Policy.

Rating	Text	Why

Rating	Text	Why
Poor	Release note (sql): Match `extract('epoch' from interval)` behavior in PostgreSQL/CockroachDB to 365.25 days.	Category is valid but not correct. Although this is a SQL change, it is backward-incompatible. Description does not use requested format. We do not know what changed, how it changed, although there's a suggestion of why it changed (Postgres compatibility).
Better	Release note (sql): Casting intervals to integers and floats now values a year at 365.25 days in seconds instead of 365 days.	Category is valid but not correct. Although this is a SQL change, it is backward-incompatible. Description uses request format. We know what changed (how a year is valued when casting intervals to integers and floats), how it changed (365.25 days in seconds instead of 365 days), but not why it changed.
Best	Release note (backward-incompatible change): Casting intervals to integers and floats now values a year at 365.25 days in seconds instead of 365 days, for Postgres compatibility.	Category is valid. Description uses requested format. We know what changed (how a year is valued when casting intervals to integers and floats), how it changed (365.25 days in seconds instead of 365 days), and why it changed (Postgres compatibility).

How to change release note texts

If the PR is not merged yet:

Push a new commit with the updated release note text.

There is currently no way for Engineers to add or amend release note texts to a merged PR. For now, if you have a text you need to add, change, or tell the Docs team to ignore, please:

Figure out what release that commit will appear in.
Create a “Product Change” Jira issue in the DOC project.
1. Add the release note text in the description.
2. Add the PR link.
Link the issue you created to the relevant release note tracking issue.