The Lifecycle of Bug Fixes and Creating Good Bug Reports

by Justin Alex @jusuchin85

Every product has bugs. No software is ever problem-free. When an end-user encounters a bug their first instinct is to flag it for developers to review. End of workflow.

People avoid spending time on bug reports like the plague, considering the process a time-wasting black hole or beyond the scope of their job. However, a concise, straight-to-the-point, and informative bug report goes a long way toward finding an efficient and effective solution. A good bug report ensures that developers don't commit excessive time trying to understand the problem or request, and users don't have to circle back trying to explain the issue they've raised.

At ServiceRocket, we assist customers every day. While we strive to deliver bug-free products so that users never encounter issues, we recognize that bug reports are like death and taxes. When we do receive bug reports from our customers, they expect them to be fixed as soon as possible. We agree. Often times, bugs are reported from within ServiceRocket, before a customer will face the issue. Given this, we've created bug report creation guideline for benefit of the support engineer, the developer, and the end user.

First, let's consider the typical lifecycle of a bug report.

A bug fix can get caught up at several stages in the lifecycle above. From the end user's point of view, the best way to ensure the bug gets fixed as fast as possible (and in the right way) is to submit a bug report free of potential confusion (that is, a bug report without bugs). This portion of the lifecycle is highlighted by the bright blue box. So, how to create a good bug report? Better yet, what does a good bug report contain?

How to Create a Good Bug Report in 4 Steps

There are 4 key points that are essential for every bug report:

1. The problem (What do you see?)

2. Steps to reproduce (How do you get it?)

3. Expected outcome (What do you expect from the steps you've performed in Step 2?)

4. Actual outcome (What do you really get from the steps you've performed in Step 2?)

The context of the bug report should be easily read by developers. Time spent trying to understand the meaning of a bug report is time not spent fixing the problem.

Other information that good bug reports include:

• Screenshot(s) of the problem
• Log excerpts (encapsulated in the noformat macro)
• Version of the plugin/platform
  • If it is a plugin bug, include the version of the platform (e.g. Confluence 5.6, JIRA 6.3)

An example of this can be viewed here.

Help developers help you

A good bug report goes a long way in squashing the bugs that exist in a product. By following the guidelines above you can create a more seamless process for you and the development team. Furthermore, you're more likely to reach the correct solution, fast.