Britt Yazel
on 30 March 2022
The Keys to Successful Bug Reporting
A key principle of open source computing is the ability for users to directly engage with development efforts, the primary avenue being through the use of bug reporting.
Bug reports are a critical component to the success of open source projects world-wide, though how to write one successfully can be, admittedly, somewhat vague. In this article, we interviewed Ubuntu extraordinaire, Sebastien Bacher, and with his insights we will explore many of the “do’s” and “don’ts” in writing concise and effective bug reports on Launchpad.
Now, what separates a poor bug report from a great one may seem at first obvious, but it’s important to remember that not everyone has experience in this regard, and even for those that do, there is nuance to effective technical communication. It’s important to remember that there is a human being on the receiving end of every bug report, and oftentimes the difference between a fixed bug and one that sits idle comes down to how you communicate your issue. The developer reading your report needs to: 1) understand your issue thoroughly, 2) ideally be able to reproduce your issue, and 3) be able to communicate with you about any further steps needed to test and/or resolve the issue at hand.
What information is most valuable?
When writing reports, the most important component is a clear, concise description of the issue at hand. This includes detailed instructions on the steps to trigger the bug, what the desired outcome is/was and what behavior happened instead, and, when possible, the inclusion of screenshots and/or videos capturing the behavior of the bug. In the world of technical problem solving, the old adage “a picture is worth a thousand words” rings true even more so than in ordinary settings, as it cuts through any possible descriptive or language barriers that may otherwise keep a developer from being able to understand and reproduce your particular issue.
It is absolutely essential to provide a thorough context for your bug report, even if the context seems silly, e.g. “I clicked the icon and the app never launched.”Sometimes, even basic levels of detail can be the difference between successfully reproducing an issue and not.
Similarly, one of the most critical, and often left out, pieces of information for a developer is data pertaining to your particular configuration. This can be as simple as which software versions and hardware you are running, but also extends to any custom and/or exotic modifications to your system. I.e. Which flavor of Ubuntu are you using? Are you running any custom extensions? Are you using any third party PPAs? Did you make any modifications to necessary config files that we should know about?
When in doubt about whether to include a piece of information, lean on the side of inclusion. As the end-user, it may be hard to intuit what is or isn’t necessary information for the developer, so it’s better to include it and leave it up to the developer to decide.
Lastly, when possible, technical log files can be an invaluable resource for developers addressing bug reports. Now, this can be an admittedly daunting task for most people. I remember vividly the early days of my open source computing having developers ask me for stack traces, kernel and/or other system logs, and to launch apps using GDB and include the output — and let me tell you, saying I was “intimidated” would be a vast understatement. Thankfully, we’ve come a long way since then, and we now have fantastic tools such as ubuntu-bug that are able to automate much of that process for you. (We will circle back to this later on.)
What are the qualities of a good bug report?
As stated above, there is a human being on the receiving end of each and every bug reported, so coming across clearly, concisely, and politely is of the utmost importance. Towards this end, one of the simplest pieces of advice we can give is to make your bug reports as efficient and compact as possible, i.e. you should not be writing a novel. In Sebastien’s words, “Any descriptions over 20 lines are not likely to be thoroughly read.” This isn’t out of any disrespect to the reporter, it just comes down to there being only so many hours in a day and only so much mental bandwidth our developers can devote to reading each issue. It turns out, reading and digesting bug reports takes a tremendous amount of time!
Further, whenever and wherever possible, the effective use of text formatting can be a huge boon in clearly communicating your issue. The use of bullet points, numbering, bolding, italicizing, and underlining, and even simple things such as adequate sentence and paragraph breaks are not only suggested, but highly encouraged!
Finally, and arguable most importantly, every bug report needs an accurate and descriptive title. An undescriptive title can be a death sentence for a bug report. Instead of a title like “Files app crashed”, perhaps use something akin to “GNOME Files app immediately crashes when clicking the launcher icon in Ubuntu 22.04 beta”. The title not only acts as a strong first-impression of the issue at hand, but also as the visual descriptor for the developer when browsing their long list of dozens (if not hundreds) of open tickets.
Mistakes to avoid?
There are a number of simple mistakes to avoid when reporting issues, and, in no particular order, they include: undescriptive titles, vague or too little information, outward anger and hostility, unnecessary hyperbole, delving into politics and arguments, and/or including details/sentiments that take away from the post or just add noise.
We understand that bug reports happen when bugs happen, and when bugs happen frustration is sure to be a component. That said, bug reports are not a place to vent your feelings, but rather a tool to solve technical problems. Yelling at the developer is a sure-fire way to get your issue ignored, and it goes without saying that bug reports fall under the Ubuntu code-of-conduct.
Don’t add “me too” or “+1” comments to ongoing reports. There is a “Does this bug affect you?” feature at the top of each Launchpad issue, use that instead. Comments should be for technical additions to the discussion only.
Lastly, stick to one issue for each report. If your issue has many intertwined issues layered within one another, please do your best to separate the individual issues into separate reports. Granted, we understand that this can sometimes be impossible, we just ask that you do your best when you can.
Other advice?
When in doubt, open a new bug report.
Ask yourself the question, should this bug be reported upstream? More often than not, issues affecting Ubuntu are actually upstream bugs with projects associated with GNOME, KDE, etc. It is often more effective to take the issue directly to the source, though, as stated before, when in doubt, open a new bug report.
If you are just looking for help, bug reports are not the correct place. Ubuntu Discourse, AskUbuntu, or the Ubuntu Hideout Discord are often much more appropriate places to ask questions and have long-form discussions.
Sadly, ~30% of bugs are closed due to lack of response from those reporting the issue. Issues get closed after one month of inactivity when “incomplete”. After reporting an issue, please check your email and respond to questions and requests for more information.
Lastly, if your issue resolves itself, please close it. At the same time, if major time goes by or major version updates happen and the issue still persists, report that information as a comment.
The Ubuntu-Bug tool:
As stated before, gathering necessary information in the form of system logs can be invaluable for the developers addressing your issues. This tool will automatically collect necessary information about the bug/package in question, upload it to Launchpad, and kick-start the bug reporting process.
To use the tool, open a terminal window and do one of two things: 1) either simply enter “ubuntu-bug” (without quotes) and follow the GUI prompts will appear to help diagnose your issue, or 2) even better, if you can narrow down the issue to a particular package type “ubuntu-bug” immediately followed by the package name to collect the particular logs and start the bug reporting process, e.g. “ubuntu-bug libinput-bin”
As a tip, it can sometimes be difficult to know the exact name of the package on your system. For example, as above I may know the issue is with “libinput”, but I may not know the particular package is named “libinput-bin”. For this, a nice tool to use is “apt search <keyword>” for a list of packages fitting that description, even providing information about which packages are/aren’t installed currently.
Closing Thoughts
Reporting bugs can be a daunting task, but it is crucial to the health and longevity of every open source project. Following this, admittedly long, guide to bug reporting hopefully will take some of the mystique away from how and when to file a bug report, and how to make sure that your issue has the most success at being addressed timely and effectively.
Good luck and happy bug hunting!
