...
Add an issue to the most appropriate repo.
Use GitHub task lists for sub-tasks.
Note: The parent/child relationship will only be visible from inside the task or sub-task. It will not be visible from the board view.
Epic
A Jira Epic is a grouping of related tasks into a larger deliverableIn agile development, an Epic represents a series of user stories that share a broader strategic objective.
Create a GitHub issue representing the Epic.
It is recommended that you choose a single org (and maybe repo) for all related epics.
Enables search for these epics within the org, rather than across all of GitHub.
Example search: https://github.com/pulls?q=is%3Aopen+org%3Aopenedx+label%3Aevent-bus+label%3Aepic
Add the “epic” label. See “Project Labels” section for details.
(Optional) Consider a consistent Epic issue title, like:
[<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.
From the top-level issue, add a search link, or use a GitHub task list to enumerate the Epics.
Example top-level issue: https://github.com/openedx/platform-roadmap/issues/28
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. Additionally, when directly viewing an issue or PR, you can only see if it is in a task list within 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.
See example Epic issue: https://github.com/openedx/openedx-events/issues/63
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 <LINK TO EPIC ISSUE> for Epic 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%<URL-ENCODED MILESTONE TITLE>%22
If you will be creating issues/PRs in multiple orgs, and you want to search the milestone across multiple orgs, you’ll want the milestone name to be unique.
To get the URL-encoded search URL, go to https://github.com/pulls?q=is%3Aopen and add
milestone:"<MILESTONE TITLE>"
afteris:open
in the search bar.
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.
See example milestone: https://github.com/openedx/openedx-events/milestone/1
...