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:

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

• Either the PR body or each commit message 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 body or in each commit.

  2. If different commits relate to different issues or epics, then either 1) the PR body can contain a primary reference and any commits that differ need their own reference or 2) each commit needs its own issue or epic references.

• 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 epic link

  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

• GitHub URLs: https://github.com/cockroachdb/cockroach/issues/78601

• Jira issue keys: DOC-2356

• Jira URLs: https://cockroachlabs.atlassian.net/browse/DOC-5432

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

  • Part of

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

• These issues are not linked or closed.

Examples:

Epic Ref (Jira Epic References)

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

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

Examples:

Pull Request linter

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

Open

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.

What happens if the linter fails?

In the case where this linter fails, you may receive an email about it from GitHub. If you wish to disable these emails, follow these steps:

1. Log in to GitHub and open up your notification settings.

2. Under System > Actions, disable the Email notifications.

I don't work for Cockroach Labs. How do I resolve this?

If you don't work for Cockroach labs, the person reviewing the PR will take care of resolving this for you.

How to help external contributors add issue and epic references

When we receive PRs from external contributors, 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(s), you can either update the PR body with the reference or amend their commit(s) with the reference(s). If you'd like, you may let them know you made the edits.