Image for post
Image for post

Sane GitHub Labels

Dave Lunny
Feb 22, 2016 · 6 min read

TLDR; the default GitHub labels kinda suck; use a sane labelling scheme instead; and use git-labelmaker to simplify GitHub label editing.

If you work for a company that manages any part of their codebase using GitHub, or if you work in some open-source repositories with at least a few contributors, then I’m sure you’re aware of how wonderful labels can be at organizing everyone’s work. Maybe you never touch them, maybe your team already has an extensive label system in place, but regardless of how your team uses them, I think we can all agree that those seven default labels GitHub provides us with are kinda weak:

Image for post
Image for post

So obviously they had some good ideas here, such as flagging issues with question if there is a question related to how the code works. But the main issue with these labels is that they offer us no context about the status of an issue, only what type of issue it is, such as an enhancement or a bug.

This may be totally fine if you’re the only contributor, or are only working with a small team of developers. But if you are a team lead/similar role, it is much more helpful to see the status and type of all issues at a glance.

Let’s step into a repo and delete all of the existing default GitHub labels. We are going to follow a simple approach to a more rational labelling system.

We’re going to introduce three different types of labels to this particular repo. Those three types are status labels, type labels and priority labels. We prefix the name of each label with what type of label it is, so something like “Status: <Name of Label>”. Let’s begin with our status labels:

Image for post
Image for post

These new status labels cover a broad range of states that an issue may be in during different stages of development. The idea is that only one status label will be applied to any particular issue; for instance a new feature can’t both be “In Progress” and “Abandoned” because that doesn’t really make a lot of sense. Or maybe it does, who knows how you’re running your projects.

So this list is fairly opinionated and may seem extraneous for your smaller projects. If on your team, for instance, “completing” an issue means that it is also “accepted” for release, then you may be able to do away with one of those labels, or perhaps add more if needed. These are just a general guideline, the important bit here is that they are all status labels.

Now we can tell, at a glance, what the progress of each issue is. It would also be helpful to see what type of issue it is that we are dealing with, which is where these handy type labels come in:

Image for post
Image for post

Here we see a lot of concepts recycled from GitHub’s default labels, such as the question label. Note that, again, we’ve prefixed these label names, this time with “Type:” followed by the type of issue it is. You project may have more different types of issues — again, the important part is the prefix.

There are other types of sane labels you can add beyond just status and type labels. For instance, a lot of teams like to add priority labels so that everyone knows what issues are most critical. Personally, I find that as soon as priority labels are introduced to a project, every issue suddenly becomes “absolutely-mission-critical-fix-now-or-the-business-will-fail”. Here’s what some might look like though if you’re interested:

Image for post
Image for post

Using this sane system for labelling, we can categorize and track issues a lot better than we could before. Here’s what our issues board might look like now that we’ve applied our sane labels:

Image for post
Image for post

Even by just glancing at the labels, we can learn so much about each issue. In this repo there are only four issues, but in larger repositories the benefits of a sane labelling scheme really shine. Instead of a wall of 92 issues marked with wontfix, you’d be greeted with clarity and sanity.

Image for post
Image for post
Some issues necessitate a table-flipping or two…

GitHub has a mechanism for filtering by labels; so if, for example you wanted to see all of the bugs that are currently being worked on, you could add the following to the little filter/search bar at the top:

label:”Type: Bug” label:”Status: In Progress”

The biggest issue with GitHub’s labelling system is that it requires a lot of tedious clicking and typing inside of the GitHub UI to set up a system like this. You don’t want to be wasting precious time at the start of a project setting up labels, which is why there is an easier way to accomplish this task.

Like all great companies, GitHub has a public API. You can use it to read/write a repository’s labels. But you’re not going to meddle with an API every time you create a repo, which is why I built git-labelmaker. Now you can organize your labels directly from the command line.

Install it globally to your system, and then navigate into a git repository so that you can run the command:

$ npm i -g git-labelmaker$ cd my-cool-git-repo$ git-labelmaker

Interacting with the GitHub API requires that you use an access token, which you can generate right here. Make sure that your generated token has repo permissions. After you input your token, git-labelmaker will ask you to create a password which you will need to input each time you run it. This will ensure that you token is secure, and remembering a password is a lot easier than remembering a token.

Image for post
Image for post

git-labelmaker offers you a few different options for interacting with your project’s labels:

  • The first is to create custom labels, which where you can literally add as many labels as you like just by directly specifying the name and colour.
  • You could instead add new labels from a JSON package that looks something like this, which is useful if you have a set of labels that you’re going to re-use.
  • Finally, you are also able to remove labels currently attached to your repo using the “Remove Labels” option.

Additionally, you can reset the token/password if ever the need be.

I hope this tool helps you and your team maintain a better labelling system, in a way that is better than working within the often annoying GitHub UI. Not to crap all over GitHub or anything, because shit’s crazy over there right now. :( Plus everyone else has somewhat more substantial grievances.

Shoutouts to Jason Bellamy, who pioneered this approach to sane GitHub labels and created a bunch of great packages that you can use. He also made the core git-label package used by git-labelmaker to add/remove labels.

Feel free to hit me up on the Twitters with any questions or comments you might have, or just to let me know what sort of labelling systems have worked for you/your team in the past. :)

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store