Home Projects Philosophy Hobbies About Me Updates

Purpose of a Bug Tracker

It seems that "tracking issues" is a very broad term. This here is an attempt to identify it a little better and try to see what it means in the context of small opensource projects.

Communication with users

When I look at how small and medium projects use the issue trackers, I can't help myself thinking about them as just a specialized forum software. Sure, the "new topic" form is a little more elaborate, and the search function is a little more complicated, but other than that they are mainly used like a forum, for communicating with the users who have the issues.

The most important feature is the issue reporting form: we want users to be able to report issues, with as many details as possible. The second thing is communication related to already reported issues: clarifications, additional information, dumps, screenshots, finally workarounds and patches. We want to have all those things related to the issue together in one place (or at least linked from there).

It seems that making it easy to report a bug is possible by just giving the users a simple form with a text box and a "submit" button. The user types the explanation of the problem, clicks the button, and the issue report is added to the database. The user is then redirected to the newly created issue description page, and can – if she knows how and wants – add any additional information, like component, severity, tags, descriptive title, attachments, contact information, etc. She can also edit the original text of the bug report there. The page should have an unique URL, so that it can be bookmarked or sent in an e-mail.

The communication about reported features is very similar to discussions on online forums, and the same features are desirable. It seems that the bug tracker could be maybe integrated with some external forum software, instead of having its own version build in.

Note keeping and progress checking

Why do you keep all those issue reports anyways? Because it's easy to forget about things and then keep stumbling upon some old bug that you always meant to fix, but never actually remembered about it when coding. Many developers will keep a TODO list, or a list of issues in a text file. Bug tracker is just a more elaborate version of that for them. You can look at it when you feel like bug fixing, but there is no particular bug at the top of your mind. Or you can look at it to decide what needs to be done before the next release.

At the minimum you want to be able to mark bugs as fixed. You might also mark which ones are newly reported and which ones you already know.

You also want to be able to add details to the report, such as links to particular places in code, test cases and automatic tests, etc.

You might want to divide some items into smaller steps – dependent bugs, as they are often called.

Knowledge base for users

It's maybe not the intended use, but bug trackers are often used for looking for solutions and workarounds by the users. Suppose that you have this nasty bug that only happens in a very specific situation. You managed to pinpoint the exact situation when it happens, then wrote a patch to be released with the next version. But in the mean time, users who still use the buggy version can use you description of the exact situation to avoid that situation and thus work around the bug.

Finding this information usually involves searching for an exact error message or backtrace.

This is one of the reasons why you don't want to simply delete the issue reports of fixed bugs.

Documenting project history

It's nice to know which version has which bugs, when the bugs were fixed and how – and sometimes even by whom. This is more of a joint task of the source code repository, the project's documentation and the bug tracker – but still the bug tracker plays an important part here.

This is another reason why you want to keep the bug reports for fixed issues around.

Enforcing the process

I think this is the least useful use of a bug tracking system, but it may become important if your project and team starts to grow. You want to start assigning tickets to people, give them priorities, design a whole life cycle for an issue report, etc. In small projects it only detracts from the actual task of writing software…

You may also want to set milestones, track burndown lists, analyze various metrics and so on – this is not very interesting for me as a programmer, but probably essential for a manager. I guess it could also be done with external tools taking the information from bugtracker using some kind of API.