About the process
We use GitHub issues, project boards, and milestones to track our work. We use four categories of issues:
Theme. A top-level/overarching objective that will span the project leases. A theme will often have an associated document describing those objectives.
Epic. This is a higher level grouping of related user stories, it can span up to the entire release. For example "Enterprises have a first class experience acquiring and deploying .NET 6.0"
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. For example: "As an IT Pro I have easy access to .NET Core installer release information and scripts in my air gapped environment so I can use this to determine which updates need to be deployed"
Issue. 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.
All four of them are represented as GitHub issues. The first three are encoded
by applying a label called
The last one is simply any issue that doesn't have of these special labels applied.
The general structure is that a
Theme will have one or more
issues, which in turn has one or more
User Story issues under them. Since
GitHub has no formal way of declaring children, the nesting is expressed by
referencing the issue inside a task list. The task list item is meant to be
marked when the referenced issue is completed.
How does the web site find issues?
Note: This guide is intended for members of the .NET product team. The community should generally not file themes, epics, or user stories as they represent our planning. However, based on your feedback we might end up creating corresponding items or just mark yours as a user story.
- This site looks for issues labelled
User storyfrom a specific set of root repos
For each issue it finds, it parses the Markdown to find linked issues:
- For each issue it finds, it recursively finds it children
Links are considered children when they appear in a Task List.
All normal linking methods are recognized (raw URL,
- Links are considered parents when they are outside of a task list and the link is in the form of
- You only use a parent link if you need link an issue in a private repo to an issue in a public repo. Otherwise you just use child links.
- An issue can be linked from multiple parents and the UI will show the issue in multiple places. However, cycles aren't allowed (and will be detected and broken)
We review themes, epics, user stories with the .NET directors:
- You should generally not add new themes
- You can add new epics and user stories, but you need parent them accordingly under existing themes or epics
We generally don't want to bottom up work (i.e. feature work driven by the engineering team) to show when reviewing the plan with the directors.
However, do we want the ability to see all feature work, regardless of whether they came from the top down planning or via bottom up planning.
The compromise is that we mark bottom up work with the label
bottom up workwhich hides them by default.
To indicate cost, use these labels:
To indicate priority, use these labels:
To indicate the release, such as .NET 6.0, add it to the corresponding project:
- You do this by clicking on the gear icon in the project area of your issue on the right hand side
- After a few seconds, you're able to select a status. You generally want to start in
You can add a team marker so that you can filter the list to items relevant to your team
- You do this by applying a label such as
Theme:Runtime. Feel free to create new team labels as necessary.
- You can mark issues marked with other teams. This isn't mean to indicate ownership but "I want this issue to show up in my team specific view".
- You don't need to mark all parents for an issue to show up in your team view; just mark the leaves you care about.
- You do this by applying a label such as
- The latency between editing GitHub and
themesof.netis about ~10 seconds.
- Do not add new themes
- Do parent epics under themes or epics
- Do parent user stories under epics or user stories
- Do add all themes, epics, and user stories to the .NET 6.0 project
- Do mark bottom up work by applying a label
bottom up work
- Do track progress of items you own by changing the project status to
- Do mark items that need director review by setting the status to
- Do not set the status to
committedunless we reviewed & approved it with the directors (marking bottom up items as committed is fine of course)
- Avoid setting the status to
cutoutside of a director review
- Do try to add cost and priority information prior to a director review