Versions Compared

Old Version 64

changes.mady.by.user Michael Lewis

Saved on

compared with

New Version Current

changes.mady.by.user Michael Lewis

Saved on

Key

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

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 /wiki/spaces/ED/pages/1134166401 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 Douglas Weatherbee . For other release notes questions, contact Michael Lewis.

Table of Contents
maxLevel1

...

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

  • To exclude a release note text from our published release notes, use:  "Release note: None".

...

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

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

...

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

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

...