Effective Bug Reports with Pivotal Tracker

As someone who is a tester that was once an application developer, I’ve seen both sides of the bug report world: both writing them as well as being the one to receive them and have to act on the information. Here’s my take on what is included in a good bug report when using Pivotal Tracker as your system for work item tracking.

  • Story title: The title ought to give a quick, one-line indication of the issue. While many bugs require nuance and details, we need an easy way to reference this work item.
  • Story type: Bug. This one’s easy 🙂
  • Description: This is the meat of the bug. Let’s explore this a bit. Note that Pivotal Tracker supports Markdown, so you can add formatting if it helps clarify the bug report.

A bug work item will provide information for three audiences: the product owner who will prioritize the importance of this fix, the developers who will be tasked with doing the work to resolve the defect, and the tester who will eventually verify that the problem is resolved.

If this was a straightforward bug, we may not need much further explanation. But there’s probably some context to be shared.

Bug - by emil_kabanov on Flickr

First, clarify what happened and why this is a bug. What did you find, and why do you think it’s a bug. How did the behavior differ from your expectations. Is the behavior directly in conflict with the behavior outlined in the feature story you’re testing? That’s an easy one. Or maybe you’re finding a consistency problem. Outline how the behavior is inconsistent. Perhaps it’s a usability issue. Why is it a problem?

Provide steps to reproduce the issue. What were the data conditions? What did you click on? What user role were you in? What job or process did you run? What browser were you using? What window size? Any of these things can be relevant for reproducing the issue. Use your best judgement as to how much detail to include.

It can also be helpful to include some severity analysis. How bad is the problem? How often will it occur, and what will be the implications if the bug isn’t fixed? While the product owner controls prioritization of the work items, we can provide information to help them make an informed decision. If the bug makes the program unusable, or causes data loss, we ought to be clear (and perhaps note elsewhere such as Slack or a face to face conversation that there’s a very severe defect to be addressed). If the bug only occurs in rare circumstances, we should note that as well. Not all bugs are showstoppers; accurate severity information will help the project team ensure we’re addressing the right work at the right time.

Include or attach supporting documentation as appropriate. For user interface issues, a screenshot is often helpful. If it’s a complex data situation involved, attaching a database test script might help.

Finally, remember that a bug report is the first step in the conversation around a work item. We may gather additional information, learn more from the development team, or alter our perspective on a defect based on changing project conditions.

image by Flickr user emil_kabanov, used under Creative Commons licensing