...
Create a GitHub issue representing the Epic.
Use a consistent issue title:
[Epic] [<FEATURE NAME>] <EPIC TITLE>
.Add a description of the Epic.
If the Epic has other related Epics, point to a top-level Issue that describes the overall project, and uses a GitHub task list to enumerate the Epics.
If you choose to also use milestones, see See instructions below for adding milestone details to the Epic description.
To track tasks related to the Epic, you can do one or both of the following:
Option 1:
Create a GitHub task list in the Epic.
This list could include text-based acceptance criteria, links to issues/PRs (in any repo), etc.
Note: The GitHub project board cannot show Epic task-list associations for issues/PRs.
WhenAdditionally, when directly viewing an issue or PR, you can only see if it is in a task list
, but onlywithin the same org (or possible the same repo?).
See milestones for a workaround.
Options 2:
Use milestones and a search link.
See notes on adding milestone details to the Epic.
Create milestones representing the Epic
In each repo that will contain GitHub issues/PRs for the Epic, create a related GitHub milestone.
For consistency, add the milestone details in the Epic description:
Code Block Milestone Details: - Title: [<FEATURE NAME>] <EPIC TITLE> - Description: See Epic <LINK TO EPIC ISSUE> for details. - (Optional) Due Date: <DATE>. - Important: Date changes need to be fixed in all repos with this milestone defined. - Open issues/PRs with milestone: https://github.com/pulls?q=is%3Aopen+milestone%3A%22%<MILESTONE TITLE>%22
Create an instance of the milestone in the same repo as the Epic, and add the milestone to the Epic issue.
Milestones link:
https://github.com/<ORG>/<REPO>/milestones
Since the milestones need to be duplicated, it is useful to have its details in the shared Epic issue.
Milestones can be seen in a project’s board view, if it is configured to display them.
From an issue/PR, you can easily see its milestone and get a back link to the Epic.
This is very important when working in a repo that is maintained by another team, so they can easily see when new issues have plans to be handled.
Private Issues
If an issue needs to be private, some options include:
Create the issue in a private repo, or
Create the issue in a public repo with reasonable public details, and reference a private ticket (like private Jira) for the full story.
...