How to Write an Effective Bug Report That Actually Gets Resolved (and Why Everyone Should)

I want you to take a moment and make a mental note of all the software you use on your computer or phone. Which percentage of the software did you pay for? 50%? 20%? 0%? Chances are if you're anything like me, most of the software you use, you got for free. I use almost exclusively open source software. Just because I use free software, however, does not mean that the software did not come at a cost. Thousands of developer hours went into each piece of software I use.

Free or not, good software makes our lives better. That is why we use it. So what can we do to give back to the developers who are adding value to our lives? A thank you email perhaps? Donate via PayPal to the developers (even better)? Become a ravenous fan who tweets and Instagrams incessantly about the awesome software?

I would argue that one of the best ways we can support the software we love is by showing an interest in the development of the software by submitting bug reports. So next time you are bugged by a bug (see what I did there?), consider taking a more proactive approach than complaining or throwing your computer out the window, and actually take the time to report the bug.

What is a bug?

Everyone that has used software has run into a bug. According to what someone wrote on the Wikipedia article for a software bug, “A software bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways.”

Most of the time a bug is a source of minor (or major) annoyance. Sometimes bugs are so severe that they can cause us to stop using certain software altogether. While spending the last year doing quality assurance for Lucid Software, I realized that finding and reporting bugs does not always have to be a nuisance; in fact, it can be quite empowering. The reason why I believe that everyone should report bugs is that finding and reporting a bug can empower a user to help make the software they use every day better.

Before you start reporting bugs left and right, I would like to guide you through some things that I have learned that make reporting a bug effective and consequently increases the likelihood of the bug actually getting fixed.

How to report a bug

Step 1: Try to reproduce the bug to make sure that it is indeed a bug and not a user or environment error.

This might seem like an obvious first step but I have surprised myself with how many times I would be in the process of reporting a bug then halfway through try to reproduce the bug only to realize it was either a user error on my part or an environment issue. If you cannot reproduce the bug you found, there is a good chance that it is not actually a bug.  

Step 2: Check if the bug has already been reported.

Once you have verified that you indeed have found a bug, you should see if the bug is already documented or reported. For popular software, it is probable that the bug you have found has already been reported. Aside from doing a direct Google search for your specific bug, one thing you can do is go to the bugs page for the software you are looking at and see if the bug has already been reported. Most software you are using will have a page dedicated to finding bugs. For example, if you do a Google search for “photoshop bugs,” the first link that will come up is Adobe’s bug reporting page. If a bug report already exists, that is great. You might even find a solution or workaround to the bug you are experiencing. If you cannot find an existing bug then you can create a new bug report.

If a bug has already been reported, you should not create an additional bug report. You should, however, read through the bug and write any additional comments that might help the developer to resolve the bug.

Step 3: Report the bug (or make a comment on an existing bug report).

Any developer will attest that not all bug reports are created equal. While a good bug report increases the likelihood of the bug getting fixed, a bad bug report can be a waste of time for everyone involved and can result in confusion and annoyance.

Bugzilla has a detailed list of the anatomy of a bug, detailing fields to be included in a bug report. I won’t go over all these fields, but I will share my personal list of what I think every effective bug report should have.

• Descriptive title
• Environment
• Expected Behavior
• Actual Behavior
• Steps to reproduce
• Demonstration of bug

Note: For all of the examples below I will list an actual bug that I encounter all too frequently while using the (sadly) now discontinued Picasa photo viewer from Google.

Descriptive title

When you searched for the bug (remember step two) what words did you type to do a search? These are probably the same words you should include in your bug report title so that other people can easily search for and find the bug report. Think of words or phrases that might often be worded differently and include both wordings in the title. Avoid using ambiguous words like "broken" or "not working." That is implicit in the fact that it is a bug. Specifically mention how something is not working. A well-written title can often be sufficient for the bug to be fixed.

Example: 
Picasa 3.9 in Ubuntu crashes when clicking the link “Sign in with Google account.” The window closes and an error report comes up.

In my example, I include the environment and list what is happening. While “crashes” and “window closes” can be synonymous, I include both phrasings just in case someone were to search for one phrasing but not the other. While you don’t want to make the title a long run on sentence, it is good to be descriptive enough so that it is clear what the bug is.

Environment

Often bugs only happen in certain environments so it is good to be as specific as possible. Make sure to list the operating system or browser you are using, and if applicable, which version of software and hardware you are using. If you are able to, help out the developer by testing on multiple environments to see if the bug is present in multiple environments or not.

Example: Ubuntu-Gnome version 16.04.1. Running Picasa from PlayOnLinux
Here I make it clear that I am not running this software in Windows.

Expected behavior

Before writing what the bug is, it is useful to write what you expect to happen. If you just write the bug, the person reading it might not be totally clear if you are describing a bug or the desired behavior. Bugs are often "features." It can sometimes be a matter of opinion. It is never clear what the bug is unless it is clear what the bug is not.

Example: 
When I click on the “Sign in with Google account” link, it should open a window allowing me to sign in.

 Actual or observed behavior

This is the meat of the bug report and often the only thing that people write when they report a bug. Often, this is just the opposite of what you wrote previously about the expected behavior. When you write the bug, remember to avoid using ambiguous terms like "broken," "not working," etc. Make Victor Hugo proud. Go crazy on the detail. A reader can skip reading detail but cannot make up what is never written. If there are too many things that are not working as you would expect them to, consider creating multiple bugs (or a parent bug with sub-bugs). 

Example: 
When I click on the “Sign in with Google account” link, the window closes and I must reopen Picasa. I get an error report that says that PlayOnLinux crashed.

Steps to reproduce

If I had to pick one thing that EVERY bug report should have, it would be steps to reproduce. Listing step by step how to reproduce the bug usually makes everything else clear. Listing the steps to reproduce the bug can make it more obvious what environment you are using, what you expect to happen, and what is actually happening. In my mind, if you have not found a way to consistently reproduce the bug, then you have not really found a bug; you have found a user error. Each step should be documented so that anyone can clearly reproduce the bug you have.

Example:

1. Double-click on the Picassa icon in Playonlinux to open Picasa.
2. In the top right-hand corner of the main Picasa window, click on the link that says “Sign in with Google account.”
3. Notice that the main Picasa window closes and I get an error message.

Evidence or demonstration of the bug

I like to record some evidence of this bug. This does a few things: 1) It requires me to be able to reproduce it consistently. 2) It serves as evidence that there is, in fact, a bug and it is not a tester’s error. 3) It shows a clear picture for the developer to see what is going on. Screenshots with annotations are often sufficient but in cases where there is user input or action, I like to show the whole process in a gif. I try to keep all my gifs under 30 seconds. If I can't keep it under 30 seconds, I practice recreating the bug until I can do it more quickly, or I break the gif into multiple gifs.

Example:

There are a handful of great free programs to help record a gif screencast. My favorite software for this is ShareX (which sadly is only available in Windows). Linux users can use Peek. LiceCap works well in Windows and MacOS and can even be used in Linux through Wine.

One thing to keep in mind when reporting a bug is that the bug report most likely will not be for you. Pay attention to who the audience might be; someone new to the project, an intern, a tester, someone online having the same experience as you, etc.

Additional tips when reporting a bug:

• Look for an existing bug report before reporting the bug.
• Proofread any bug report before you submit it. Incorrect grammar or wording can be very confusing and discouraging.
• Provide as much relevant info as you can. This can include error logs and URLs.
• Look for an existing bug report before reporting the bug.
• Be as specific and concise as possible (without leaving out relevant details).
• Test in multiple environments if you expect it to be an environment issue.
• Look for an existing bug report before reporting the bug.
• Avoid opinions. Unless you are submitting a feature request, you should stick to the facts and leave out how you would make the software if you were the developer.
• Look for an existing bug report before reporting the bug. Seeing duplicate bug reports can be as annoying for a developer or product manager as it is to see duplicate bullet points on this list.

Step 4: Be proactive and follow up

If you really want a bug to be resolved one of the best things you can do is follow up with the bug report (but in a nice, proactive way). After filing the bug report, or in the bug report itself, you can make a comment to the developer and state your willingness to help. One nice thing to do would be to add words of encouragement to the developer to show that you appreciate the software. Something else you can do is offer to test in a different environment or even test beta versions of the software.

A developer that feels appreciated is much more likely to fix a bug than a developer who feels annoyed. Remember that when writing a bug report and following up.

Why everyone should report bugs

As I stated earlier in this article. Reporting bugs can empower you as a user to help make software better; it is probably one of the best things a non-developer can do to help improve software. Even before working at Lucid, I often would send emails to developers with bugs that I had found. I was always surprised and impressed with the response that I received. I almost always received a reply and in the end, the developer would either fix the bug or explain to me why it would not (or could not) be fixed.

Someone who sits idly by waiting for bugs to be fixed is most likely someone who will be disappointed. Someone who reports bugs is someone who shows that they care enough to support the best possible product outcome. So the next time you are using software and you encounter a bug, make the extra effort and report it. Being proactive will not only benefit you in the long run but will also benefit everyone who uses that software and ultimately improve the world of IT.