This is a WIP. We are actively discussing and trying different ideas to see what works best, with a hope for some level of standardization.
Create a GitHub Project for your team
Create a GitHub Project Beta (also known as v2).
See the Arch-BOM board as an example.
Show labels and milestones on your board by choosing the first option under the board view’s drop-down.
Associate an issue/PR with your team’s GitHub Project
An issue/PR will display any associated Projects in the right-hand sidebar, but only if the Project is in the same org. See notes on using milestones (below) as a workaround.
Add issues/PRs to your team’s board as needed.
In certain cases, this association is only viewable from the board itself (see warning).
Board and Backlog views
You may want a separate view for your board and you backlog.
Add a “backlog” label to an issue/PR that should be on the backlog.
If the label doesn’t exist, see the “Project Labels” for creating a consistent label.
You can filter out backlog items from your Board view using
-label:backlog
and filter them in to your Backlog view usinglabel:backlog
.Note: The shared “backlog” label is not scoped to a team. If multiple teams are tracking the same item in their backlog, it will become a board item for all teams as soon as any one team removes the backlog label, unless another label is added for additional filtering.
Tasks/Sub-tasks
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 deliverable.
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.
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.
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:
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.
Project Labels
GitHub labels can be used for many reasons, including another way to group related tasks.
For example, since Event Bus work will likely contain a variety of milestones, an
event-bus
label will be used to quickly find all of its associated tasks.To see and define labels, use:
https://github.com/<ORG>/<REPO>/labels
Since labels need to be recreated in each repo, these definitions allow the labels to be consistent.
Name | Description | Color |
---|---|---|
backlog | Item is on a team's backlog or wish list. | #c5def5 |
event-bus | Work related to the Event Bus. | #C56F68 |