How to report a problem effectively. Read about best practices for software bug reporting.
The key to properly processing bugs (defects) is to report them effectively. Let’s then evaluate what a good bug report has to contain.
How do we define a bug?
Contrary to what is commonly believed, the definition of bug is not so obvious. Here is our definition:
If you are creating a bug, please try to add as much of the following information as possible, otherwise the bug might not be processed and it can end up as
When reporting a bug, what information should be included
10 information that should be included in a bug report:
- Choose a non-generic subject describing what and where is failing.
- Use plain English, don’t use words that only a few might understand.
- Avoid acronyms.
- Is the problem observed persistent or temporary?
- Actual behaviour.
- Steps to reproduce.
- Expected behaviour.
- When possible, include logs, screenshots, video recordings, the app version, and any other supporting information.
- Check if the bug has not been previously reported (checking for duplicates).
- When applicable, ensure the bug is filed in the correct place (product, component, team).
We think the bug report could be grouped into the user or internal type. The user type of bug reporting form is usually much simpler as we don’t want to overload users with too many details. Internal type of bug reporting is the issue filled directly inside the issue tracking management. For the user type of bug reporting use the above wisely and keep the report form short. Remember that some details may be detected automatically, such as the version of the application so you don’t need to ask about that the user.
Choose a non-generic subject describing what and where is failing
The subject of the bug report should clearly describe what happened and where. It is much more useful when doing reports, or scrolling list of bugs.
Unclear: Cart counter doesn’t work.
Better: The counter of added products does not update after adding a product to the cart.
Use plain English, don’t use words that only a few might understand
As much as possible use plain English so everyone can understand the content. Avoid jargon and offensive words.
Acronyms are quite often overused. While it makes the content shorter, it doesn’t have to necessarily make the content clear. Use full description or at least wrap the acronym into the link that explains it.
Is the problem observed persistent or temporary?
When the issue appears again it would be very helpful if the person that reports or processes the bug mentioned that the bug was observed before. Additionally, when possible, try to find in your project management system bugs reported previously and connect them with a new ticket.
The actual behaviour is what happens after the reproduction steps have been executed. This is exactly what you observe when experiencing the described problem.
Steps to reproduce
The steps to reproduce are the path any other user has to follow to experience the same bug you reported. That also helps when you eventually plan to cover those steps with automated testing.
The expected behaviour is when a feature doesn’t work as specified originally. You may also make some research to include the link to the original task, ask the product owner for details or search through the documentation.
When possible, include logs, screenshots, video recordings, the app version, and any other supporting information
Include as much as possible supporting information’s like logs, screenshots, video recordings, the app version and the like. This information is very helpful as it makes simpler the issue examination and its reproduction.
Logs: while developing the app keep the developer console always open. It’ll help you to notice unexpected messages or statutes.
Screenshots: adding one or more screenshots is extremely helpful as it helps not only determine the place where the bug occurred but also might be handy when comparing the screenshot with the current, live behaviour on production. The bug might be reported for quite a while and the app may change meanwhile.
The app version: it helps to look back into history and determine when changes occurred.
Video recordings: whenever possible, record a session with a reproduction of the problem. This will make the investigation of the problem much easier. Sitelint provides such feature User Feedback Recordings where you can ask the user to record his activity and send it back to the platform. You can also record directly from the platform (quite often used by QA testers).
Discussing root cause
You may want to discuss bugs and ask following questions:
- Why did this bug occur? Technical explanation.
- Why didn’t our tests catch it?
- What tests can we add to catch this issue in future?
- How can we prevent this from recurring?