Versions Compared

Version Old Version 17 New Version Current
Changes made by

Nick Vigilante

James Linder

Saved on

Key

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

...

Who is the audience for Issue and Epic Refs   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.

...

How to write an Issue or Epic Ref

High-level rules

  • Every commit 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 descriptionthe 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 /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

...

  • 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 “EpicEpic: None” None in each commit that doesn’t 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 “EpicEpic: None” None in each commit that doesn’t doesn't relate to any issue or epic.

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

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

...

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

...

Code Block
Fixes: #64276
Closed cockroachdb/pebble#482
Resolved: https://github.com/cockroachdb/cockroach/issues/77376
Informs: #33316
See also #62585, DOC-4023
Part of https://cockroachlabs.atlassian.net/browse/CRDB-13558

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:

Code Block
# key-only reference:
Epic: CRDB-8035

# URL reference:
Epic: https://cockroachlabs.atlassian.net/browse/CRDB-8035

# if no Issue or Epic reference
Epic: none

...

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

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

Once you've identified the issue / epic to reference(s), you can ask them to either update the PR body with the reference or amend their commit(s) messagewith the reference(s) or the PR body with the appropriate references. If you'd like, you may let them know you made the edits.