Labels, projects, and milestones roadmap

  • Article

The .NET docs team makes extensive use of GitHub labels to organize our work. By filtering on combinations of labels, we can quickly focus on sections of interest on the .NET docs website. For example, we could filter to all of the open issues on the architecture guides with a query to is:issue is:open label:"dotnet-architecture/prod".

We use GitHub projects to organize sprints and other goal-oriented epics. We also use GitHub milestones to track work. It is best to think of projects for planning (issues), and milestones for work (pull requests).

This roadmap explains how we use these organizational tools and has links to handy filters we use to find areas of interest.

Labels

If this is your first experience contributing to dotnet/docs, start with the up-for-grabs issues. These are issues that have a more focused scope. They are a great way to make your first contribution. From the up-for-grabs view, you can further filter issues based on areas and priority. We've identified good issues for beginners with the good-first-issue if you want to try a smaller first contribution.

We use labels to classify issues in many different ways:

You can combine a label from each set (guide, release, priority) to create a narrow focus to find issues you want to work on.

Find issues for a single .NET guide

We use labels for each of the architecture e-books and for each .NET Guide. All ebooks are noted with the dotnet-architecture/prod label. Each book has a unique label that ends with /tech.

Each .NET Guide is noted with the /prod suffix and has a blue-gray background. Here are current issues filtered for each of the .NET guides.

Other product labels are defined for areas that cross repositories.

Find issues for one section of a guide

The .NET guides are large, so these labels further limit the scope by a section of a guide. Each .NET Guide subarea is noted with the /tech suffix and has a light blue background. Many of these labels apply to multiple guides, while others are in only one guide. After filtering on an area, add one of these labels to further limit the scope of issues.

Releases

:checkered_flag: Release: on dark yellow

Issues tagged for a specific release are noted with the :checkered_flag: Release: prefix and have a dark yellow background.

Priority

Priority labels are all Pri followed by a single digit. Lower numbers are higher priority:

  • Pri0 - Critical priority

    Security issue or legally required for compliance. We drop everything else to fix.

  • Pri1 - High priority

    Essential for common scenarios. Or highly visible error on high page view article. We do these before P2 or P3 work.

  • Pri2 - Medium priority

    Helpful for common scenarios but not blocking. We do these if quick and easy, or fit them in while addressing a P1 issue in the same article.

  • Pri3 - Low priority

    Helpful for edge cases, trivial corrections for common scenarios, low page view article, or deprecated technology. Not worth our time but up for grabs for community contribution. A P3 issue may be closed if not addressed after two months.

What about the other labels

There are many other labels used by the content teams to manage different classifications of issues. If you're not on the content team, you can ignore these other labels.

Projects

Projects are intended for planning purposes, where prioritized work is automated through a Kanban board. Projects should only ever contain GitHub issues, not pull requests. Projects differ from milestones, in that milestones only contain pull requests.

We use projects in two ways:

Milestones

Milestones typically follow the same naming convention of projects Month YYYY, but they're different from projects. We use milestones to track completed work. Milestones should not contain issues (potential work), but rather exclusively contain pull requests. The current milestone is automatically applied to new pull requests.