Software products have malfunctions and weaknesses, called "bugs". Such should be reported to the development team of the company that shipped the software. Mostly the according bug report is written by some company helpdesk staff member that answered a customer call.
This article focuses on the essential ingredients of a bug report, and why they are needed.
Report Outline
Following informations are needed for a bug report:
- Title, a significant but generalized summary of the problem (not the solution!)
- Reproduction Steps, a list of user actions that led to the bug occurrence
- Expected Result, what was expected to happen
- Actual Result, what really happened
Nice to have:
- Environment, exection context like platform (operating system), version number, configuration, user category, ...
- Screenshot(s)
- Stack Trace
You need a good issue tracker (like Jira) for bug reporting. It automatically should generate an issue ID, create a confgured default priority, and add the author and date/time to the issue. The tracker should work fast and not demand lots of fields to be filled, because the more complicated it is to file a bug, the less bug reports the product will have, the less successful the software will be.
Example
Required
Optional
In many cases the "Environment" may be not optional but required. Operating system and application version are essential informations for software that is platform-independent and not completely new.
Do not include assumptions about the reason of the bug if you are not actually sure. It could confuse the developer that tries to fix it, and it is his/her job to find the cause. You can add a "Hints" paragraph to the description if you have suspicions.
Ingredients
Title
This is more important than we'd expect. In Scrum Sprint view you may see only the title of the issue, nothing else, and that list is the decision basis of the Scrum Sprint Planning. So imagine sitting before such a list and having to go into details for every issue to just understand what it is about!
We should reuse an already existing issue before writing a new bug report. Thus the helpdesk will try to find the problem by looking at a list of issue titles. Imagine the trouble when titles are not significant!
The title should be as short as possible and, at the same time, as precise as possible.
Yes, it's a contradiction. Find the best compromise between these two extremes!
Please do not hesistate to use "quotes" in a title to separate technical and business terms. Imagine above example stating
Clicking the blue button ....
instead of
Clicking the "Blue" button ....
The developer might resolve this as not-reproducible, commented "There is no blue button on our UI", because the button actually is white.
Reproduction Steps
A step-by-step instruction how to reproduce the bug. This can become quite time-consuming to achieve. If the customer did not report it (which is rare), a support member or developer will have to find out the reproduction by experimenting. Every click on the UI may be significant and should be mentioned.
Bad or not always working reproduction descriptions are the main reason for slow fixes. Not nice for the customer, not nice for anyone. It is very difficult sometimes to find out the real reason for a bug. Imagine a date bug that happens just on February 29 in leap years and you get the report the next day!
Expected Result
A description of the expected (but not happening) application behavior after the last step of the reproduction.
Although "everybody knows what is expeced to happen" it is very frequent that the fixing developer does NOT know, because he is new. Or there are several things that could happen on a correct reproduction, and it is needed to know which of these actually was expected. So do not forget the expected result, even it seems redundant.
Actual Result
A description of the actually happening application behavior after the last step of the reproduction.
If we do not know what happened and the reproduction does not work, we can not even start to experiment with the reproduction. We will not be able to find out what we should fix (unless the application crashes on reproduction).
Environment
The reproduction just lists steps to take, but not under which circumstances this must happen. Besides operating system and application version, also the performing user (access rights!) and the application configuration may matter.
If the bug report comes from the company-internal quality assurance, there may exist deployment stages like "develop", "test", "production" that are configured differently and may influence the reproduction, so this could matter.
Screenshot(s)
Screenshots are always helpful to express the problem. Mind that a screenshot can not replace a well-formed good title!
Use some screenshot utility (like Greenshot for Windows, or ksnip for LINUX) that allows to add markup like text, arrows, circles, rectangles, or even speech bubbles. You can point to the problematic input field on a complex UI that may contain ten more such fields. This makes it much easier to correctly understand the screenshot.
Stack-Trace
A stack-trace of the error situation is a really valuable help for developers. Customers will not deliver such, but they could attach the application's log file. A stack-trace directly points to a source-line where the bug happened. This can help to fix even bugs where the reproduction failed.
Resume
It is essential to be able to quickly write a bug report. Software quality will be connected directly to that capability. So keep it simple and avoid mandatory input fields in your issue tracker whereever possible.
An issue done in the form reproduction / expected / actual can be quickly turned into an acceptance test of the form reproduction / expected. By adding such a test you can keep the bug from coming back after some time. That form is also usable for feature requests, just leave out the "Actual Result".
Keine Kommentare:
Kommentar veröffentlichen