Filing bug reports is the most common way for users to contribute. Even if it’s not too difficult, I’ll give you some advice to improve the quality of your reports. After all, when you go out of your way to report a bug, it is in the hope to see it fixed… so let’s see how we can make this more likely.
1. Try to reproduce the bug
If you can’t reproduce the bug, it’s next to impossible to find the root cause and thus to fix it. In that case, I would suggest you to wait until you experienced the bug multiple times. Maybe you’ll be able to find something that triggers it (or that makes it more likely to encounter it). If the application has a debug/verbose mode, it might be a good idea to enable it until you experience the bug a second time. The generated log might be helpful for the developer to understand what happens exactly.
So don’t file bug reports straight away unless you can reproduce it. The exception to the rule is when the application gives some useful information like a core-dump, a back-trace or an error message.
Obviously if the bug happens during an upgrade, it’s difficult to reproduce it (unless you have multiple computers) but you should still report it. Be sure to include all the relevant information (versions of packages before and after the upgrade, logs of the upgrade, etc.).
2. Do your best to identify the faulty package
When you report a bug to Debian, you must assign it to a package. While there are pseudo-packages useful for problems which are not directly attributable to a real package, in most of the cases you should report a bug against the specific package that seems to be the cause of the problem you encountered.
In turn this often requires you to attribute the problem to a file (for example the executable of the application that triggers the bug). Once you have a filename you can use dpkg -S to identify the corresponding package.
$ dpkg -S /usr/bin/hamster-time-tracker hamster-applet: /usr/bin/hamster-time-tracker
Note that reportbug accepts a filename as parameter and will do the above conversion for you.
If you only know the name of the application (but not the filename of the associated executable), you can use dpkg -S with a pattern to let it return all possible matches:
$ dpkg -S hamster hamster-applet: /usr/share/applications/hamster-applet.desktop hamster-applet: /usr/share/gnome/help/hamster-applet/es/statistics.page […] hamster-applet: /usr/bin/hamster-time-tracker […]
Or you can also verify in the list of installed packages:
$ dpkg -l "*hamster*" Desired=Unknown/Install/Remove/Purge/Hold | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) ||/ Name Version Description +++-===============-===============-============================================== ii hamster-applet 2.32.1-1 time tracking applet for GNOME
3. Verify that the bug is not already reported and/or fixed
If there’s a newer version of the software available, it’s a good idea to try to reproduce the problem with this version too. Because the developers tend to care only about the latest version, they will want to reproduce it with this version, and they will be annoyed if the problem that you reported is already fixed. That’s why bug reports of users of testing/unstable tend to be more useful than bug reports of stable users.
In any case, you want to verify that the bug has not yet been reported: filing a duplicate bug is useless and only generates more work for the developers to merge both bugs together. On the opposite, it’s highly appreciated to add supplementary information to an existing bug report, even a simple confirmation that the bug still exists on a newer version is useful.
Note that reportbug will automatically show you the list of open bugs before allowing you to submit a new one.
4. Use reportbug
While the Debian bug tracking system allows anyone to submit a new bug with a simple mail, you should really use a dedicated program like reportbug (or reportbug-ng) because it will automatically include lots of useful information in the generated report (version of dependencies, current architecture, etc.) and will assist you in all the steps.
5. Describe the problem so that the developer can reproduce it
Ideally your report should include everything required so that the developer can reproduce the problem on his system. If a given document triggers the bug, attach it.
Describe the steps required to reproduce the bug in great details just like you would explain it to your grand-ma. Explain how you expected the program to react and what happened instead.
You can learn much more on how to draft a good bug report in this article: How to report bugs effectively. It’s a bit long but well worth it if you intend to report bugs and thus interact with developers.
6. Be kind and willing to help
When you draft a bug report, keep in mind that you’re writing to a volunteer free software developer and not to a customer service. You should be respectful and follow the usual rules of courtesy. Developers’ attention is scarce and should not be wasted.
Be willing to help, if the developer starts investigating your problem, he might need your help to get supplementary information (in particular if he can’t reproduce it) and you should be ready to provide it. Thus it’s important to keep whatever you need to reproduce the problem.
In some cases, the Debian maintainer might be overworked and you can offer your help to forward the bug to the upstream bug tracker, it’s always appreciated. If you’re reasonably confident that the problem is not Debian-specific, you can do it straight away and set the forwarded field to the URL of the upstream bug report (for example with bts forwarded <bug> <url>).
7. Use the correct severity
The Debian bug tracking system lets you set the initial severity of the bug report (in decreasing severity: critical, grave, serious, important, normal, minor, wishlist). Pick the correct severity according to the official definitions but don’t misread them.
In particular, don’t over-inflate the severity: for instance if you lost some data due to a misuse of the software, it’s not “critical” (i.e. “rm -rf *” doesn’t warrant a critical bug against rm). If you use only a tiny part of a software, and that part doesn’t work, the package might be unusable for you but it’s not unusable for everybody, so it doesn’t warrant the “grave” severity. The “important” severity is often a good choice in those cases.
Do not under-estimate the severity either, if a problem is important enough that it must be fixed before the next stable release (for example a regression compared to the previous release), pick a release-critical severity (i.e. at least “serious”). The maintainer and the release manager can always lower the severity if they do not agree with your initial judgment.
And now, happy bug-reporting! You can refer to this article with this shorter URL: https://raphaelhertzog.com/go/bugreporting/
Follow me on Identi.ca, Twitter and Facebook. Or subscribe to this blog by RSS or by email.
Thanks for these tips!
Let’s review them to see if I’ve done a correct job for my bugreport #608575 (the one and only Debian bugreport I’ve ever done).
1. Try to reproduce the bug
Very easy because for me it’s 100 reproductible. I’m OK for this step.
2. Do your best to identify the faulty package
No problem either on this one. I identified the faulty package in the bugreport.
3. Verify that the bug is not already reported and/or fixed
I’ve done that. My bug was not already reported so I created it.
4. Use reportbug
I’ve done that. Nice tool by the way.
5. Describe the problem so that the developer can reproduce it
I described the problem and even included a screenshot.
6. Be kind and willing to help
Well, I received no feedback so it’s difficult to prove my kindness 😉 But I can assure that I’m willing to help.
7. Use the correct severity
I choose “Normal” because it’s the default value and because Rhythmbox is perfectly usable without this plugin function.
Despite these tips the bugreport is still unclassified, more than six months after the bug creation. I suspect the Debian maintaineur is MIA.
Too bad for my first Debian bugreport 🙁
Patrick, indeed the GNOME team is one those teams that is always overworked. I would try to file the bug report in the upstream bug tracker (bugzilla.gnome.org). The maintainer is not really MIA, it’s just that they can’t deal with all the incoming bug reports and thus only the most severe get some attention.
Also, it is important to stay around, answer to developper questions regarding the bug report. A good thing to do is to subscribe to the bug report (NNN-subscribe@bugs.debian.org) to be notified of the ongoing discussion, provide input, test fixes if possible.
I personnaly have a bookmark on http://bugs.debian.org/cgi-bin/pkgreport.cgi?which=submitter&data=me%40provider.com&archive=no&version=&dist=unstable and review the list every quarter or so to ensure the reports are still valid and relevant, and that I can still reproduce. Do not forget that the submitter can close a bug report (per the BTS usage guidelines). I found out that many bugreports tend to become obsolete (for instance, a dependency problem that cannot happen neither in unstable nor in testing anymore because version have moved on).
It would also be nice to have a way to filter on the bugs that are not found in the latest version of the package. So, the user could test whether the bug still occurs, then either update the “found” information or close the bug report.
BTW, I use procmail recipes to automatically subscribe to the bugs I submit and confirm the subscription.
Nice explanation of dos and don’ts. I got a seemingly weird question: What if I can’t get a smoking gun on one package and thus can’t tell which package is the problem?
I.e., since upgrading to Gnome 3 (yummy!) both my Firefox/Iceweasel and Chromium crash sometimes (!) when accessing certain webpages, taking the whole session with them. At other times it just works fine.
In .xsession-errors there are various references to a “fatal IO error 11” or “fatal IO error 104”. The mouse was the only IO device i touched, so i tried another, resulting in the same errors.
Using LXDE with Iceweasel just works. So I kinda suspect the GTK+ 3 dependencies, but with my non-existent experience in debugging I can’t nail down anything anywhere.
Is there anything I can do beside just changing to another DE? (Honestly, I’m not into banging my head against the same wall for hours…)
You can try to ask for help on a user support mailing list, some more experienced users might help you to diagnose it more precisely.
The precise problem is not clear but if the whole session dies, it’s likely that something has gone wrong in the Xorg server. This might be a good target for the bug report…