Bug tracking guide A best practices guide to bug tracking

If you’re going to write software of any size, you're going to have a few bugs along the way, and you’ll need to keep track of them somehow. If you’re going to track your bugs, you may as well do it right. Here are some best practices to keep in mind, as you set up your bug tracker.

Make it easy

Bug tracking should introduce as little overhead to the development team as possible. This means that whatever you use for bug tracking should be simple and organized, which is not always an easy combination. For instance, keeping a notepad on your desk makes it easy to record when you see a bug, but if you do this for a couple weeks you’ll quickly find out that the lack of organization causes more problems than it’s worth. The best solution is to find the simplest way possible of getting a bug into a bug tracker for the person reporting it.

If you’re a developer, then that means filling out a simple form like this one:

If you’re a customer, then you should have a form on a website to fill out, or better yet, an address to send an email to with a bug report. Remember, if your customers find a bug, they’re doing you a favor by reporting it, so make their life easy.

The other half to removing bug tracking overhead from the team is organization. Your bugs should be easy to categorize by functional area, product, build, etc. and they should be easy to find with filters and searches. Functional area is easy: “We found a bug on the 401k site of the Intranet Site”—so then you’d probably record that information somewhere in the bug report. In OnTime we go one step further and represent this as projects and present them in a hierarchical manner like this:

Knowing the actual release for planning purposes, the customer or source of the bug report, build number, and any other information about where the bug came from, will be important as well. If at all possible, try to make as much of this information auto-populate in the bug report to reduce user-input problems and just generally make life easier for everyone. Having all of this information will allow you to find a bug faster, which will lead to fewer duplicates and less time in the bug tracking tool (if searching is easy it’s usually fast too); this means that you can spend more time fixing bugs rather than tracking them.

Make it right

A bug report is effectively useless if it doesn’t include enough information for the development team to find and fix the offending code and therein lies the challenge. Ideally, every developer would see every bug report properly filled out with screenshots, error codes, stack traces, reproduction steps, and a little mint on the pillow.

The truth of the matter is that you’ll occasionally get a bug report that looks like this:

As fun as it sounds, someone needs to investigate this or at least contact that person to figure out:

• What type of error are you seeing?
• What are you doing in the application when you see the error?
• Can we reproduce it on your machine?
• Can we reproduce it in a test environment?
• And so on...

Depending on their answer, we may have an actual bug to fix and so, with the first step, our bug report is on it’s journey to being fixed.

Verification

Verification of a bug report serves two purposes: it makes certain that the reported bug is valid and not just user error, and it also makes certain that the bug report contains enough information to fix it.

So who does the verification? Depends on you and your team, it may be the Development Team, it may be your Quality Assurance Team, or it may be the Support Team. It really doesn't matter who verifies the bug so long as it actually gets done. Keep in mind that this step will usually involve actual interaction with a customer, so we want to make that as easy as possible on them. Either input your notes and information into the bug report yourself (if talking over the phone) or make an easy portal for your customers to integrate the bug tracker with email. That way, the conversation with all of the information you gather is located in the bug that will be eventually assigned to a developer.

At a bare minimum, you’ll probably want to have a short description of the bug and reproduction steps (that work) for every defect logged. More information, such as build number, functional area, etc. is better but most of the time, you can figure these things out if you have the brief description and repro steps.

Once your bug has been verified to actually be a bug, you can start to fix it which would be the next step in the overall workflow of bug fixing. You’re probably familiar with this part: you assign the bug a developer, they fix it, and we all call it a day. Not really! There’s one last (major) step before we can call a bug “fixed.” Someone needs to verify that it’s been fixed. This usually means that the person who verified it will attempt to reproduce it again; but, if we can get the customer involved so that they can verify the fix, it’s even better.

We’re now tracking the whole bug from beginning to end. Your bugs will likely have their own type of workflow, but you’ll probably want to include at least some of the basics, such as:

• Verify the bug
• Fix the bug
• Verify the fix of the bug

Going back to earlier, you’ll want to make certain that each bug is easily found relative to its workflow step, easily moved along the process by the correct team member, and easily visualized for the entire team by the project manager, so you can get a sense for how these bugs are impacting your development efforts, overall.