The documentation team reviews every new commit in a release to determine whether any documentation needs to be updated. The Epic ref, Issue ref or Docs note in the commit message tells them why the commit was made so they can figure out what needs to change in the documentation. This page provides guidance on when and how Cockroach Labs engineers should include these references or write these texts.

When should I include an Epic ref, Issue ref or Docs note?

Every commit must include an Epic ref, an Issue ref or a Docs note.

How do I choose which one to include?

If the change in the commit is made as part of an epic choose one of:

Epic ref
Issue ref where the issue contains an Epic ref in the issue body (description)

Else if the commit is part of an issue but not an epic:

Issue ref

Otherwise, when there is no issue for the commit

Docs note

Why is including this information necessary?

A big part of the documentation team’s job is to review every commit made for a release to figure out if any documentation needs to be updated because of that commit. To do that, they need to understand why each commit was made.

When they know why a commit was made, they have the context needed to determine what in the documentation needs to be updated (if anything) because of the change.

How do I include an Epic ref?

The rules for an epic reference are:

It must be of the form [Ee]pic:? CRDB-123
It must be on a line by itself with no whitespace before it.

An example line in a commit message might be:

Epic: CRDB-8035

How do I include an Issue ref?

The rules for an issue reference are:

It must be of one of these formats:
- KEYPHRASE:? #123(, #456)* where KEYPHRASE is one of:
  - See also
  - Informs
- KEYWORD:? #123 where KEYWORD is one of (following the GitHub PR / issue linking format):
  - Close
  - Closes
  - Closed
  - Fix
  - Fixes
  - Fixed
  - Resolve
  - Resolves
  - Resolved
The issue ID in the above formats must be one of:
- #123
- org/repo#456
It must be on a line by itself with no whitespace before it.

Examples of valid issue references:

closes #16750

Fix: #64276

informs: #33316

See also #62585, #43784

How do I include a Docs note?

DRAFT: Epic Ref, Issue Ref, Docs Note