The following comes from working in large IT organizations for almost two decades at large companies and based on working relationships with Quality Assurance and User Assurance test teams and as such, this is written from personal experience.
Bug reports are essential in helping developers quickly identify and resolve issues. A well written bug report will ensure a faster turnaround time than one that causes confusion for a developer. Here are some hints, tips and reasons for filing good bug reports.
Why a Good Bug Report?
An effective bug report results in better chance of it getting fixed. When a developer has to attempt to determine how to reproduce a bug or setup an environment in a certain way to reproduce a bug without any prior knowledge, it slows down the time to repair. Also, a good bug report allows a developer to quickly identify what is being conveyed and they can more effectively determine what the issue is.
The first task that a developer will perform when receiving a bug report is to attempt to reproduce the bug. Without that ability, there is little chance of fixing the bug as the developer will not have a clear idea as to what code is causing a problem in the first place. Steps that occurred to get to the bug or logs that were created around the time of the bug are very helpful. Often, if a bug cannot be reproduced, the developer has little ability to repair the bug.
While an essay is too much information, four or five words is just as bad. For example, when my wife tells me “the car doesn’t start” I first go to the car and check the gas gauge, then the headlights (is the battery dead?), try to turn over the vehicle (what sound does it make? No sound? Clicking? Humming?), and then open the hood and look around at a bunch of mechanical items that I do not understand. On the opposite end of the spectrum, if she tells me about the weather outside, the color of the bird that flew by, the way that the sunlight glimmers on the leaves of our maple tree and then that the car doesn’t start, more time is spent trying to figure out what the point of the story is. The same goes for software bug reports.
This forum supports Markdown. When pasting large logs, errors or chat messages, they can be placed within three back-ticks like so:
This is a message
This helps greatly when reading through reports.
This Doesn’t Work
Providing a snippet showing that something doesn’t work without any context does not help. This goes back to the point on a bug being reproducible and providing specifics in a bug report. Please provide details on what led up to something not working. If a permission issue, what are the permissions? If an issue with groups, what group was the person in, and what group were they going to? If an issue with an API, provide any error logs that may indicate what happened with the API call.
Let’s face it, not everyone has the same hardware and operating system and version of Java and the same web browser, and may not even have the same version of PhantomBot. While this may not always be applicable, it is good to know simple items like:
OS (Linux, Windows, OSX)
Browser (for Web Panel)
A Feature Request is not a Bug Report
Reporting a bug and then adding that it would be nice if x, y and z could also be added is not a bug report. It is a bug report and a feature request. Please try to keep them separate.
Anger and Fear Lead to the Dark Side
Is it frustrating when something doesn’t work the way it is expected to? Yes. Of course. Believe it or not, the developers are just as frustrated as you are and possibly embarrassed. Tossing in comments with colorful metaphors do not help the situation any. Sometimes things slip out. Type the bug report. Read it, maybe edit it, then submit it.