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 engineers, docs, management, and other departments within the company.

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.
Internal teams. 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:

Commit Requirements

Audience

Commit Message Body

Engineering. Specifically the reviewers and future maintainers. Often verbose, to explain what was before/after, and why.

Release Note

The end-user (developer, operator). Communicates any potential impact that this change has to the user.

The Docs Team. Alerts the team to product changes that need documentation.

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 reference either 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 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

note

The most helpful context for the docs team is that an Epic is linked to each commit. This can be either directly as an epic ref or as an issue ref where the issue contains an /wiki/spaces/JIRA/pages/1925283849 in its body. For engineers and other parties, the most helpful context is usually a reference to an issue or an issue and an epic.

The most helpful context for the docs team is that an Epic is linked to each commit. This can be either directly as an epic ref or as an issue ref where the issue contains an Epic Link in its body. For engineers and other parties, the most helpful context is usually a reference to an issue or an issue and an epic.

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 whitespace before it.

Examples:

Epic: CRDB-8035

# if no Issue or Epic reference
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:

CockroachDB > Issue and Epic Refs in Commits and PRs > index.png

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.