...
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.
Exclude changes to
reservedinterfaces 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".
...
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.
...
Category | Valid alternate | Focus | ||
|---|---|---|---|---|
|
| Backward-incompatible changes to CockroachDB interfaces. This may include changes to SQL statements, If the change is considered backward-incompatible (i.e., the change can break programmatic usage of an interface), use the See example. | ||
|
| Changes to CockroachDB features requiring an enterprise license, e.g., | ||
|
| 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, health and monitoring endpoints, environment variables, integrations with service managers, CLI flags for server commands, exit codes, etc. | ||
|
| 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, | ||
|
| Changes to SQL statements, functions/operators, system catalogs, or execution. | ||
| Changes to public /wiki/spaces/OI/pages/856851129, including classification and versioning. |
|
| Changes to the DB Console or and any associated endpointsmetrics. |
|
| 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
...
This list is also documented in the commit message template, which lives in githooks/prepare-commit-msg.
...
Backward-incompatible change
| Info |
|---|
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 |
|---|---|---|
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. |
|
...