The documentation team reviews every new commit in a release to determine whether any documentation needs to be updated. The Jira Epic ref, GitHub Issue ref or Docs note in the commit message tells them why the commit was made to better inform their work on the documentation and release notes. 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 at least an Epic ref, an Issue ref or a Docs note.

If the commit does not require a release note and there is no Epic ref or Issue ref, use Docs note: None.

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?

The Documentation team uses “Release note” texts in commit messages to identify user-impacting changes in the product that might require documentation updates. However, those texts alone don’t help Docs writers understand why a change was made. This new information takes care of that, helping writers either connect the change to a high-level epic (e.g., on the product roadmap) or by simply adding additional context about why the change was made when there’s not a connection to an epic.

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

...

Amidst a large and ever-growing volume of changes, connecting work to product roadmap epics via GitHub Issue and Jira Epic references (Issue and Epic Refs) improves the ability to make the connection between product changes and roadmap epics for the docs team, and provides traceability and context for revenue, product, management and engineers.

Who is the audience for Issue and Epic Refs   

GitHub Issue and Jira Issue and Epic References (Issue and Epic Refs) benefit multiple audiences. 

• The Docs Team. These references help to ensure that the context needed to generate documentation is more consistently available, by improving the team's ability to make the connection between product changes and roadmap epics. This will enable automation to properly route docs issues and help the docs team properly evaluate changes that may impact the docs.

• Engineering. The additional context can help in understanding why a change was made and in making future modifications.

• Revenue, Product, Management and Engineering. The connection between product changes and roadmap epics provides traceability and context for internal teams and enables automated tooling such as automatically setting Fix Version for Jira issues.

For comparison, the following table presents the audience of commit release notes and commit message bodies:

When to include an Issue or Epic Ref

All PRs should include Issue and/or Epic References. This includes PRs submitted by external contributors and CRL employees alike.

How to write an Issue or Epic Ref

High-level rules

• Every commit should have at least one Issue ref or Epic ref.

  1. If all commits relate to all Issue or Epic Ref(s), the Issue or Epic Ref(s) can be put into the PR description.

  2. Issue refs can either be GitHub or Jira issues. Epic refs must point to Jira issues only.

• Issue or Epic Refs can go anywhere in the PR body or commit message, preferably before the Release Note.

• The most preferred to least preferred reference types are:

  1. An issue ref where the issue contains an /wiki/spaces/JIRA/pages/1925283849

  2. An issue ref to an issue without epic link and an epic ref

  3. An epic ref or issue ref without epic link

  4. An Epic: none ref

Recommended reference placement

• If the PR relates to only one issue or Jira epic:

  1. Put the issue or Jira epic reference either in the PR description or in each relevant commit.

  2. If the reference is in the PR description, put “Epic: None” in each commit that doesn’t relate to the epic. This is particularly important if the commit contains a release note.

• If the PR relates to multiple issues or Jira epics:

  1. Put the issue or Jira epic reference in each relevant commit.

  2. If a single commit relates to multiple Jira epics, put all relevant issue or Jira epic references in that commit.

  3. If all commits relate to all the Jira epics, put the issue or Jira epic references in the PR description or in all of the commit messages.

  4. Put “Epic: None” in each commit that doesn’t relate to any issue or epic.

• If the PR relates to no issues and no Jira epics:

  1. Preferably, put “Epic: None” in the PR description or in each commit containing a release note.

Format

Issue Ref

Supported Issue Identifiers

• GitHub issue numbers: #58420

• GitHub issues in other repositories: cockroachdb/docs#14958

• Jira issue keys: DOC-2356

Supported Keywords and Key Phrases

The standard GitHub keywords for linking and closing issues are supported. 

• Only one issue should be included per keyword. If multiple issues are included for a keyword, GitHub will only close the first issue in the list.

• Only referenced GitHub issues are closed.

Select phrases for referencing issues are supported.

• Supported phrases:

  • Informs

  • See also

• A list of issues may be included for each phrase.

• These issues are not linked or closed.

Examples:

Fixes: #64276
Closed cockroachdb/pebble#482
Informs: #33316
See also #62585, DOC-4023

Epic Ref (Jira Epic References)

To include an epic reference, use Epic: <jira-epic-key>

• It must be on a line by itself with no white-space whitespace before it.

Examples

...

:

closes #16750Epic: CRDB-8035

Fix:# #64276if no informs:Issue #33316or Epic Seereference
also #62585, #43784

What information needs to be in the issue?

If the issue has an epic link in its body, that is all that is needed.

Otherwise, the issue should explain why the change was made as described in the “What information do I need to put in the Docs note?” section below. If the issue does not explain why the change was made, please add it to the issue or to the Docs note.

How do I include a Docs note?

The rules for a Docs note are:

• The first line must start with [Dd]ocs note:

• It may span multiple lines

• The Docs note text will be this line and every subsequent line until another section is reached (Release note: or Release justification:) or until the end of the commit description is reached.

• The contents will describe why the commit was needed.

What information do I need to put in the Docs note?

Whereas the “Release note” text explains what changed in the product, the “Docs note” text should explain why the change was made. What motivated the change? Was the change made for Postgres compatibility or to support a specific third-party tool? Was the change made to improve the usability of a specific feature? Please provide enough detail for writers to understand the context for the change.

When there is a link to an epic, that epic answers this why question. The “Docs note” is required only in cases where an epic link or an issue link doesn’t clarify the context for the change.

When the commit does not require a release note and there is no Epic ref or Issue ref, use Docs note: None.

What are some examples of Docs notes?

Do I still need to add a release note to commit messages?

Yes. The “Release note” text identifies what changed in the product. Those texts are used in our public-facing release notes as well as by our Docs team to identify product changes that might require documentation.

...

Epic: none

Pull Request linter

In GitHub, a linter will check your PR and its commits for the presence of an epic or issue reference:

...

This check contains logs that will print helpful information about whether the PR body and/or the commit messages are missing an issue or epic reference. The check is not required, but that may change in the future with advanced warning.

How to help external contributors add issue and epic references

We will occasionally receive PRs from external contributors. Unfortunately, they likely won’t know which issue or epic is associated with the change they are making. It is the reviewer’s responsibility to identify the issue / epic associated with the PR.

Once you've identified the issue / epic to reference, you can ask them to amend their commit(s) message(s) or the PR body with the appropriate references.