Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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 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>".

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

...

Changes that can break programmatic usage of an interface.

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, health and monitoring 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, userfileworkloaddebug commands that operate on non-running servers, etc.

sql change

sql

Changes to SQL statements, functions/operators, system catalogs, or execution.api change

api

Changes to public /wiki/spaces/OI/pages/856851129, including classification and versioning.

ui change

ui

Changes to the DB Console or and any associated endpointsmetrics.

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.

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.backward-incompatible change

backwards-incompatible change

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

...