We publish detailed release notes describing most non-test changes. The Docs team uses this script to automatically generate release notes from "Release note" texts in cockroach
PRs. This page provides guidance on when and how Cockroach Labs engineers should write these texts.
When to write release note texts
Write release note texts for:
Changes to how users interact with the product
Examples: New/changed functionality, backward-incompatible changes, build dependencies
Changes to how the product behaves
Examples: Performance changes, command response changes (that aren't backward-incompatible)
Changes that are otherwise interesting to users
Example: Architecture changes
Do NOT write release note texts for purely internal changes, such as:
Code refactors
Testing/infrastructure work
How to write release note texts
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 in PR descriptions.
If they are only in PR descriptions, they may 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.
Put "Release note" texts at the end of commits.
Everything after the "Release note" annotation gets picked up by the script.
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" below.
For guidance on writing a good description, see "Release note descriptions" below.
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.
When a commit falls into more than one category, choose the category that makes the most sense from a user perspective.
These categories are very imperfect and will evolve over the course of this next release cycle.
Category | Valid alternate | Focus |
---|---|---|
|
| Changes to CockroachDB features requiring an enterprise license, e.g., |
|
| Changes to This includes changes to logging configurations and behavior, environment variables, integrations with service managers, CLI flags for server commands, exit codes, etc. |
|
| Changes to This includes changes to the SQL shells, |
|
| Changes to SQL statements, functions/operators, or execution. |
|
| Changes to APIs, including classification and versioning. |
|
| Changes to the DB Console or any associated endpoints. |
|
| Changes that impacts the use of security features (IAM, TLS, etc.) or the security profile of the product. |
|
| Changes that improve performance, often at kv, storage, and SQL engine levels. |
|
| Changes that fix known problems as opposed to add or improve functionality. |
|
| 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. |
| Changes to requirements for building CockroachDB from source. | |
|
| Changes that can break programmatic usage of an interface. This will be defined more clearly soon because not all interfaces are programmable, but examples are when an interface is remove, stops accepting a certain syntax or values, or has a new default value. See past examples. |
This list is also documented in the commit message template, which lives in githooks/prepare-commit-msg
.
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 |
---|---|---|
Bad | Release note (ccl): Default interval for the closed timestamp cluster setting is different. |
|
Better | Release note (enterprise change): Shortened the default interval for the |
|
Best | Release note (enterprise change): Shortened the default interval for the |
|
Bug fix
Rating | Text | Why |
---|---|---|
Bad | Release note (bug fix): No more duplicate rows for |
|
Better | Release note (bug fix): Fixed a bug that caused duplicate rows in the results of or Multiple nodes attempting to populate the results of |
|
Best | Release note (bug fix): Fixed a bug introduced in v19.2.3 that caused duplicate rows in the results of or Multiple nodes attempting to populate the results of |
|
Backward-incompatible change
Rating | Text | Why |
---|---|---|
Bad | Release note (sql): Match |
|
Better | Release note (sql): Casting intervals to integers and floats now values a year at 365.25 days in seconds instead of 365 days. |
|
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. |
|
How to change release note texts
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 add it in a comment to the relevant release notes tracking issue.
Details required:
Link to relevant PR
Type of change
Add release note text
Change release note text
Tell Docs to ignore release note text
New text
Expected release