Keep your bug tracker unified

A ladybug crawling on a leaf

One thing that happens in large projects — particularly Linux distros, but any project with semi-autonomous teams — is that bug trackers start to separate. One giant, unfiltered bug tracker is hard to manage. The project either starts using a tracker that supports multiple queues or individual teams have their own tracker. Either option is fine for strictly internal work, but it turns out users file bugs, too.

Your project’s users aren’t necessarily familiar with the inner workings of the software. They shouldn’t have to be. When you let Conway’s Law configure your bug tracker, you’re being hostile to the user. The user will file a bug in the place that makes the most sense to them or presents the lowest friction. Occasionally, people will file Fedora bugs against the 0ad (a real time strategy game) component in Bugzilla because it is the first component listed.

So one thing is clear: if you have separate trackers, you must be able to move reports between them. I talk about this and other important features in the appendix of Program Management for Open Source Projects. The other option is to tell your users “oh, you have to go file a report over there, actually.” You might as well just tell them you don’t want bug reports. Thankfully, GitHub and GitLab both support moving issues between repositories. If you’re using either of those platforms, then you have that option. (Note that for GitHub, the same user or organization has to own both repositories, so if you’re too scattered, that won’t work.)

If your project is scattered among different platforms, organizations, or using a tool that doesn’t allow moving bug reports, then the other option is to have a separate tool just for user issue tracking. Arguably, this is the most correct approach. To use ITIL terms: the user’s unexpected experience is an incident; the underlying bug is a problem. And not all user issues are software bugs. Sometimes they’re documentation bugs or problems with an outside system. It makes sense to track and treat incidents and problems differently.

Of course, this requires that you have a team of people to provide user support and connect the incidents to the underlying problems. In volunteer-driven projects, that’s really hard to sustain. User support is hard and under-rewarded work. Most people won’t choose to do it voluntarily. It’s not a viable option for most open source projects. That means the best way to serve your users is to have a unified tracking tool, with easy-to-understand entry points. Unfortunately, that’s easier said than done.

This post’s featured photo by Neringa Hünnefeld on Unsplash.

Ben formerly led open source messaging at Docker and was the Fedora Program Manager. He is the author of Program Management for Open Source Projects. Ben is an Open Organization Ambassador and frequent conference speaker. His personal website is Funnel Fiasco.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.