One of the tasks I took on this year is crunching through the GitHub issue tracker of Yoast SEO. Much of it was to organize and improve how GitHub labels shape the issue tracker workflows.
In a large and long running open source project issues have a life of their own. It’s a challenge to keep a clear picture of relevant problems, their kinds, and priorities.
Labels everyone knows
Every GitHub repository starts with a baseline set of issue labels. They cover common scenarios and make it easy to navigate even unfamiliar repositories. Most (if not all) active issue trackers keep and use native labels.
As the volume of open issues increases, native sets start to show its limits and lack nuance. It becomes hard to distinguish the state of the issue and next steps or blockers on the path to its resolution.
Labels for necessary action
The most subtle and dangerous kind of issue in the tracker is the one that stays open for too long. Such issues lose relevance, make it hard to navigate, and sap attention.
The labels for necessary action clarify why an issue is lingering around.
One of the most useful labels is wait for feedback. Most of the time it means that the issue author needs to provide more information. With the Least recently updated… sort, it’s great to discover stalled issues to follow up on or close.
Labels for progress status
Once an issue is actionable, it is important to keep track of the progress.
It also has a special role since we use a Waffle board to help visualize and plan. Waffle service provides a column view of the issues. It’s more convenient to see the current load and congestion points. The sync works both ways — the issue labels can be changed on both Waffle and GitHub sides.
Labels for components
In a larger code base separation by component becomes more important. Labels for components narrow down which part of the project issues belong to.
Developers specialize in parts of the project they’ve developed or are experienced with. Labels make it easier for them to keep track of such areas.
Tips and tricks
Normalize labels to start with either lower or upper case letter. The labels view is case–sensitive and a mix of the two makes it hard to follow.
Since GitHub labels have no descriptions be sure to document them somewhere. We use a dedicated wiki page for it.
Practice incorporating labels in your issue searches with:
- and absence
The latter is especially helpful to find issues that didn’t receive enough attention.
A combination of label and sort can create useful issue views. For example
label:bug sort:comments-desc is a sure way to discover most discussed problems.
Pay attention to label colors. Make groups easy to distinguish. Have colors convey meaning where needed. Semaphore colors are a staple for it, for example:
- green for enhancements;
- yellow for holdups;
- red for problems.
Results and plans
Dedicated attention to GitHub labels and workflows brings a lot of value to the issue tracker. In our Yoast SEO repository:
- the count of open issues went down by hundreds;
- many old lingering bugs got attention and fixes;
- the ongoing progress is more clear and visible;
- the cooperation between developers and with contributors has improved;
- there is more insight into which components show age and are up for refactoring.
Our future plans include a custom status dashboard to improve visualization of issues and labels.