GitHub labels for better workflows

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.

This group also has more labels for stall reasons, such as needs decision, needs refresh, and so on.

Labels for progress status

Once an issue is actionable, it is important to keep track of the progress.

Labels for progress status clarify if the issue is being worked on and how close to completion it is. This maps out the development process with labels as development, code review, acceptance.

Yoast SEO Waffle board

Yoast SEO Waffle board


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.

Such labels clarify the involved functionality (text analysis, XML sitemap) or technology (JavaScript). They provide insight into which parts of the code base need more attention and maintenance.

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:

  • inclusion label:example
  • exclusion -label:example
  • and absence no:label

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.

Coming up next!