List

GitHub labels

Label design

Label naming convention

• Labels are lower-cased by default, unless there is a strong reason to use capitals.
• Words are separated with whitespaces. If it’s not possible, we use -, to concatenate words.

Global label 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:

• (high) Our team member can work across different repositories without learning different conventions.
• (mid) We can transfer issues between repositories without creating duplicate labels.
• (low) Our users can consume code from different repositories without learning different conventions.

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: