Page Comparison

Create a GitHub Project for your team

• Create a GitHub Project Beta (also known as v2, either in an organization (https://github.com/orgs/<ORG>/projects) or in a repo (https://github.com/<OWNER>/<REPO>/projects).

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

  • 

...

• You may want a separate view for your board and you your 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

  GitHub project custom field named “Backlog” with a “Backlog” value.

• You can filter out backlog items from your Board view using -labelbacklog:backlogBacklog and filter them in to your Backlog view using label: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

  :Backlog.

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.

• Add the “epic” label. See “Project Labels” section for details.

• Consider a consistent 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, 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:

• 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

  • Note: To get the URL-encoded search URL, go to https://github.com/pulls?q=is%3Aopen and add milestone:"<MILESTONE TITLE>" after is: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.

...

In agile development, an Epic represents a series of user stories that share a broader strategic objective.

• Add a GitHub project custom field named “Epic” with a list of epic names.

• Optionally create a GitHub issue representing the Epic with the “epic” label.

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.

...

• 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

  • Note that Axim is maintaining standard labels on openedx repos.

    • TODO: Document link to standard labels.

#98BB67

Name	Description	Color
backlog	Item is on a team's backlog or wish list.	#C5DEF5
epic	Represents a series of user stories that share a broader strategic objective.	Preview Image with Color
event-bus	Work related to the Event Bus.	#C56F68	Image Added