List

GitHub labels

Label design

Global namespace

The GitHub label namespace is unique. Meaning, if one repository has a bug label called bug 🐞 and another repository is calling it bug 🐛 , they should be updated to be identical. The same concept should have the same name. This is to ensure that we can:

• our team member working across different repositories
• transfer issues between repositories
• our users using product from different repositories

Should I create a new label?

We shouldn’t aim to create all the GitHub labels that can exist. For a label to help (not make things worse), it has to:

1. Be high-level enough to group enough related work.
2. Be low-level enough to filter out enough of the other issues.
3. Fit with one Labels categories.

When in doubt, don’t create labels per: Delete as much as possible. You will know if you delete enough if you are forced to add back > 1/10 of the things. Otherwise, you carry too much overhead. The challenge with this step is to override our emotions. Very likely, in the past, we faced a lot of pain because we deleted something that we truly needed..

Labels categories

We use 4 categories of labels, solving 4 different kinds of problems:

1. “Product scope” labels. They are meant to help:

   • Maintainers stay laser-focused on their scope and ignore the rest
   • Users/maintainers use the backlog, e.g., find duplicates
   • Users/maintainers appreciate the amount of focus we have on a given scope

   For example: scope: docs-infra.

2. “Prioritization” labels. Those labels are used to help us decide what to work on next. You will find regressions (usually of the utmost priority), bugs, enhancements, new features, items waiting for upvotes, those of low priority, and those on hold, etc.

   Subsets:

   • “Type” labels: Those are about the relationship between current behavior and expected behavior. They bring clarity to users. They are mutually exclusive and comprehensive.

     Those also help PMs appreciate how much we are focused on depth vs. breadth.

     • bug: It doesn't behave as expected.
     • regression: A bug, but worse, it used to behave as expected.
     • new feature: Expand the scope of the product to solve a new problem.
     • enhancement: It’s an improvement, but we can’t make up our mind whether it's a bug or a new feature.
     • expected behavior: The current behavior is already the one expected.

3. “Kind of work” labels. Those labels are used to group related work together, so some people can only look at them. It can be either because they require specific skills or awareness of related work.

   For example: l10n, docs