Sane GitHub Labels
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:
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.
Sane Labelling Scheme
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:
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:
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:
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:
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.
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.
Automate Label Creation
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.
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. :)
