label-scheme-management

Curating what a repository's labels mean

Labels are a shared vocabulary, and every change to one changes the meaning of every issue already carrying it. This is a repository-wide edit dressed up as a small one.

Sequence

1. See the whole set at once. list_label returns every label ordered by issue count, most used first. That ordering is the audit: the tail is where the dead vocabulary lives.
2. Find out what is actually in use. For anything you are considering changing, list_issues filtered by that label, omitting state to include open and closed issues, shows what carries it. A label with no issues has no cost to retire; one with two hundred is load-bearing.
3. Read the one you are about to change. get_label returns its exact name, colour and description. Names are case-sensitive in ways that are easy to get wrong, and the description is often the only record of what the label was meant to distinguish.
4. Make the change. label_write with method set to create, update or delete. Renaming is update with new_name.
5. Report what moved, including how many issues were affected by each change.

Decision points

• Retire or leave? A label unused for a long time is clutter; a label used once a year is a category someone will look for. Check the age of the issues carrying it before calling it dead.
• Rename or create-and-migrate? update with new_name carries every existing issue with it, keeping the history intact. Creating a second label and applying it by hand splits the set in two, and the older issues stop appearing in the filter people use. Rename unless the meaning is genuinely changing.
• Merging two overlapping labels is not one call. The issues on the losing label have to be moved before it is removed, and moving them is issue-by-issue work that belongs to whoever is triaging. Say that rather than removing the label and orphaning the classification.
• Colour carries meaning. Projects usually encode severity or kind in hue. Read the existing set before picking; a new colour that clashes with an established convention is worse than a dull one that fits.
• Descriptions are worth writing. A label whose meaning has to be inferred from its name gets applied inconsistently, and that is the actual cause of most label sprawl.