How we use labels on GitHub Issues at Mediocre Laboratories


The GitHub issue tracker is pretty great. Mostly because of the deep integration with GitHub source control but also because its slim set of features isn't trying to do too much.

enter image description here

GitHub doesn't have a ton of fields to fill out when creating a new issue. Great when you want to add a new issue to the backlog quickly but comes with the tradeoff of requiring a bit more effort when you're finding appropriate things to work on.

By "appropriate" what I really mean is avoiding high effort, low impact work. I can't tell you how often I've seen developers spinning their wheels in the bottom-right section of this graph:

To help us avoid what I've been calling the "bottom-right thankless task wasteland" we've come up with a few conventions around GitHub issue labels. If you've ever managed labels in GitHub before you're probably familiar with their fancy color picker that displays a "solid" color palette over a "muted" color palette.

Here's how we use labels on GitHub Issues at Mediocre Laboratories:

  • 3 levels of priority (solid red for high, solid yellow for medium, soild green for low)
  • 3 types of issues (muted red for bugs, muted yellow for technical debt, muted green for features)
  • Developers can tag an issue with any other label as long as it starts with a ~ character and is set to light gray (#eee)

Notice anything about that list? 3 conventions, 3 priorities, 3 types of issues, 3 colors. 3 is a magic number. I love 3.

You can see an example of how we're using GitHub labels over at some of our open source projects, like Electricity.

Oh, you might be wondering... why do we start our tags with an ~ character? Because they get sorted to the end of the label list in the GitHub UI.

Any developers out there want to share their GitHub Issue protips?