Improving GitHub Issue Labels

On GitHub users can categorize issues by marking them with various text labels. However, the set of labels provided by default doesn’t seem to have any internal structure. This post, inspired by a similar article(1), proposes a labeling system for better issue management experience.

Starting point

Most online version control hosting services provide free issue trackers. These trackers typically come in the form of a list where users can submit feature requests, share found mistakes, comment, and ask questions. When projects grow issues proliferate and it becomes harder to track what is still important. To help mitigate this problem users are allowed to group their issues by marking them with different labels. A default list of labels is often provided with the ability to create new ones on demand. Here is the initial set on GitHub:

bug something is not working as expected
documentation issues related to documentation and manuals
duplicate similar issue already exists
enhancement tasks related to improving and expanding existing functionality
good first issue good first issue for new contributors
help wanted looking for outside help
invalid issue description is not valid
question question
wontfix issue will not be fixed

These labels are intuitive to understand but cumbersome to use for the reasons given below.

First, the provided labels do not cover all possible issue categories. We have labels for required fixes (bug), new feature requests (enhancement), documentation changes (documentation) and questions (question). But where should maintenance tasks be placed? Or speed improvements? Tasks related to unit testing?

Second, it is not explicitly indicated but the available labels are of two distinct types. bug, documentation, enhancement, and question indicate the type of the issue while the rest add additional information. It would be nice if this distinction was somehow made visible by, for example, using different colors.

Third, there is no systematic way for adding new labels. If we want to add more descriptions, i.e. in progress, we would have to add a new label with a separate new color. One issue is that we might run out of distinct colors while doing this. But more importantly, since there is no label hierarchy, every new label would add a new distinct category.

New labels

Below is an attempt to simplify and enhance the labeling scheme. Under the proposed system each issue is assigned a distinct label indicating its category. Category is chosen based on the effect the issue will have on the project.

bug something is not working as expected
change requests to change existing functionality
internal changes not directly visible to the user: speed improvements, unit tests
new feature requests to add new functionality
documentation issues related to documentation and manuals
meta tasks that don’t affect the project itself: questions, advertising

Besides category each issue might have any number of applicable tags that provide additional information. The actual set of provided tag labels will depend on the project and will vary from one repository to another. Below are a few examples of possible tags.

tag: duplicate similar issue already exist
tag: in progress the task is currently in progress
tag: good first issue issues suitable for new contributors
tag: help wanted maintainer is looking for some help with the issue
tag: completed issue was completed successfully
tag: canceled the proposal was abandoned and will not be implemented

Practical advice

In order to gain the most out of the proposed labeling system it is important to assing labels to every issue. Every issue in the repository has to have exactly one category label and any number of applicable tags.

Category labels are designed to stratify tasks according to the influence they have on the repository. A task can really do only one of the following: fix, add, change, adjust without changing behaviour, write about, or be unrelated to the actual contents. Each of those tasks have their own category label and a separate color which orders the issues according to their impact. Issues with most visible changes (bug and change) are colored in red and orange; issues not visible to the user (internal) are yellow; addition of new functionality (new feature) does not break anything and add something new, hence green; while documentation and meta tasks are blue.

Any additional categories are better provided via tags. Tags can be used to specify the part of the system affected by the issue (tag: database), indicate the current status (tag: in progress), or provide any other type of useful information. The actual set of available tag labels should be modified to suit the project. Tag labels are assigned light grey background in order to stand out from the title but not interfere with the main categories. This scheme makes it easy to add new tags: every new tag will start with a tag: prefix and have the same color.

Alphabetic order is another thing to keep in mind. When multiple labels are applied to one issue they are arranged in an alphabetic order. Right now the labels are constructed in such a way that categories come first, followed by tags. This naming scheme makes label placement consistent and allows to add any number of custom tags without changes to the system. But if new category names are going to be appended to the list they should start with a letter lower than “t”.

Finally, tags should not be overused to indicate status or priority. One or few tags related to status are fine but if the project requires a complex issue management system it is better to use a project board instead.

  1. “Sane GitHub Labels” by Dave Lunny  ↩︎