Managing issue tracker labels
In the post Preparing for Hacktoberfest contributors, I said you should “make sure issues are well-labeled.” But what does that mean? Labels (or tags, as some trackers call them) are pretty simple, conceptually: they’re arbitrary tags that either apply to an issue or not. But how you use them in your project can get very complicated.
Less is more
I often see people putting a lot of thought into a repository’s labels before the first issue gets filed. While this sort of planning ahead seems like a good idea, it’s really more of a premature optimization. Labels are most useful as a workflow tool or a filtering tool. For the latter to work, you need to have enough issues to need a filter in the first place. If there are only a few issues in the tracker at any given time, there’s not much utility in labels.
This implies that you shouldn’t have too many labels. As a rule of thumb, I suggest if a label doesn’t apply to at least 10 issues, you don’t need it. This is a totally made up number, but you get the idea. Adding more labels adds cognitive overhead to creating and managing issues, so you don’t want to add complexity when you don’t have to.
Sidebar: Labels as workaround
Here’s a hot take for you: labels are often a workaround for insufficient tracker features. What does this mean? I’ve often seen labels used to track state, indicate priority, etc. These are better served by native fields in the tracker, but popular code forges have intentionally simple issue trackers. GitLab supports “scoped labels“, which can make labels more suitable for replacing these missing features, but at the cost of having a lot more labels to choose from (and display). The appendix of Program Management for Open Source Projects and my “Your bug tracker and you” talk cover the fields you may want in your issue tracker.
Adapt your usage
Whether or not you’re trying to predict what labels are going to be important, you need to adapt how you use labels over time. What labels are unused? What labels do you wish you had? Listen to your contributors and users and find out what difficulties they encounter. What information do you wish you could report on? As your project evolves, you’ll need to evolve the metadata you’re tracking.
This post’s featured photo by Angèle Kamp on Unsplash.
