openSUSE:How to Write a Good Bugreport
Why to Write Good Bug Reports at All
Let's first talk about the most important thing: Why should I bother with writing a (good) bug report at all? And this is really simple: Because you want to see the problem fixed, right? Anything else just does not make sense.
And to make it possible, the process must work for everyone involved. Starting with the reporter, through the bug-triage, debugging, bug-fixing/development, QA, maintenance, documentation... and finally the customer.
If you want to see the bug being fixed, you have to start yourself by providing enough relevant information about the issue.
What Makes Bug Report a Good Bug Report
Obviously the most important are the bug Summary and Description. They need to provide enough information for anyone looking at the bug to understand the problem.
- Summary needs to really summarize the problem itself as seen by the user, e.g., Application X crashes with Y message when Z happens. This helps to search for duplicates and speeds up the bug-triage rapidly.
- Component must really fit the reality, not everything that happens during installation is an Installer bug
- Assignee is typically aligned with the component, if you know more precisely what exactly is the problem, you may try to find the bug bugowner by yoursef, e.g., in OBS
- Description must contain all the important/relevant pieces of info to understand the problem in depth
- All the information about the environment that is relevant
- Brief description of what the reporter believes is a bug, e.g., the expected versus the actual result
- Steps to reproduce - If you can't reproduce it, the developer might not be able to do so either
- Additional info, e.g., versions of packages where/when it started to happen
- Attachments
- Logs (mandatory for YaST/Installer/D-Installer/Agama), see more at Report a YaST Bug
- Screenshots (and their translation to English if it's about translation or behavior in a particular language).
All the relevant information should be provided by the reporter without asking for them. It's the task of the reporter to think first and to make the bug report self-contained.
Don't assume that those who handle the bug later can read between lines and know the information that is not there. Some people don't have the access to, e.g., internal links, or they disappear later.
What Makes Bug Report a Bad Bug Report
- The reporter should understand what they are actually reporting. See Why to Write Good Bugreports above. Reporting by copy'n'pasting random texts from a console or logs is not helpful.
- Please, don't report failing openQA test-cases, report bugs instead. We debug and fix bugs, we don't debug or fix failing test-cases. An openQA test-case is usually quite a complex scenario with several hidden expectations, dependencies, etc. These must be spelled out or eliminated first.
- Don't only link a failed openQA test as they disappear later. Bug report must be self-contained and still ready for review in 10 years, e.g., openQA test results disappear much faster. See Description and Attachments above.
- Don't mark everything with Severity Major or even Critical, it's usually not. For instance, Critical means loss of data. Keeping it Normal is usually fine.
- Don't report duplicate bugs, search first. For that, others also need to write good bug reports.
- Don't use a generic Summary (Title), e.g., "openQA test test_name failed" does not contain any real information. See Summary above. If a test fails, we may consider it to be the problem in the test itself.
- Don't report wrong content of repositories, package conflicts, incorrectly built media, errors or timeout of some commandline tools, etc. as Installer/YaST bug. Use something that fits better or just Other.
- Don't report feature requests as bugs, we have a tool for that. We usually close them as FEATURE anyway.
- A picture might be worth a thousand words, but even a picture might need some explanation, don't assume everything is clear without it. Describe what the picture contains, what's wrong there, etc.
- Don't set the bug Priority, that's a task for the Project/Release manager.
What Happens with Bad Bugreports
The developer does not have an unlimited time for processing bugs. We are truly sorry, but we reserve the possibility to close such bugs as INVALID and bugs we don't plan to fix as WONTFIX and feature requests as FEATURE.
More Reading
Learning is part of the fun. Simply searching for "how to write a good bug report" will find much more for you.