Summary

We use GitHub issues and milestones to track our work. We use four categories of issues:

• Theme. These are big initiatives, each will have a dedicated document and owner. These are often cross-cutting features across the product. We'll have very few of these (less than ten per release usually).

• Epic. This is a higher level grouping of related user stories, it can span up to the entire release.

• User story. An explanation of the feature written from the perspective of the end user. Its purpose is to articulate how a software feature will provide value to the customer. Once implemented, it will contribute value towards the overall epic.

• Task. These are all other work items. These could be bugs, features, or developer tasks. We leave it up to the engineering team/area owner how and if they want to use these.

Issue types

The type of an issue in GitHub is tracked via a label. Each issue should only have a single one of these labels:

• Theme
• Epic
• User Story
• If no label is present, the issue is assumed to be a Task.

It is expected that a Theme is decomposed into multiple Epic issues, each of which in turn are decomposed into multiple User Story issues.

Status labels

• Status:Proposed. Indicates that the work is proposed, pending reviews.
• Status:Committed. Indicates that we intend to deliver this work.
• Status:InProgress. Indicates that the work has started.
• Status:Completed. Indicates that the work is completed.
• Status:Cut. Indicates that we no longer plan to complete this work.

Cost labels

• Cost:S
• Cost:M
• Cost:L
• Cost:XL

Priority labels

• Priority:0
• Priority:1
• Priority:2
• Priority:3

Parent/child relationships

The children of an issue are found by parsing the markdown of the issue description. In order to link a child, you need to include it in task list. Any of the following links are recognized:

- [ ] #123
- [ ] org/repo#123
- [ ] https://github.com/org/repo/issues/123
- [ ] [SomeLink](https://github.com/org/repo/issues/123)
- [ ] https://foo.visualstudio.com/bar/_queries/query/5cc24ce1-2bec-4ba8-80df-ccdf86131d99/
- [ ] https://foo.visualstudio.com/foo/_queries/edit/1267177

You can also link to Azure DevOps items and queries from GitHub issues. Those are always considered private. The Azure DevOps queries can be flat or hierarchical but indexing will always include all children, regardless of query type. It is also possible to link a parent issue. This is useful when the child is in a private repository while the parent is in public repository. This avoids having to publicy link to a private issue. This is done by putting a link like this anywhere in the child's issue description:

[Parent](https://github.com/org/repo/issues/123)

Teams and areas

For the most part, your issues should be automatically tagged with the corresponding area and team, based on the subscription configuration, which can be found in the (private) repo here:

https://github.com/dotnet/themesof.net/blob/main/subscriptions.jsonc

This file lets you automatically map issues to areas and teams based on repo and area: path labels. Teams are generally associated with a list of areas. However, you can still label an issue explicitly for a team by applying a label like Team:Libraries. This is useful for themes and epics that live in an other unrelated repo for your team.