Versions Compared

Version Old Version 18 New Version 19
Changes made by

James Linder

James Linder

Saved on

Key

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

...

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.

...

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

...

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.

...