Every now and then we get the same complaints about bug reports again: Either it is a complaint by the user who feels her/his report doesn’t get enough attention from the developers or it is the developers who complain that there are too many bad and useless reports making them spending too much precious coding time on triaging bug reports.
Disclaimer: I am not a developer but do bug triaging, documentation writing and application testing.
I think personally that bug reports are an important feedback from the users, provided those reports are indeed useful to the developers. But what is actually a good bug report? I will restrict my explanations to KDE and its Bugzilla bug tracker, but this applies of course to all bug reports.
1. It should be about the most recent version available
I know that not everybody is updating their computer regularly, some people only do security updates which is probably well enough for their use case, but they should also be aware that Free Software is fast-paced and most developers are already working on newer versions and may even be some versions ahead. In general, bug fixes are not backported to previous version by the developers, simply due to lack of time and manpower.
If you use an older version you can still report it to your distribution if they provide support for it, though. Some distributions even do backports, but also rarely to older versions as most do not have enough resources either.
Don’t forget to specify the exact versions of the product and of KDE (available in the Help menu of all GUI applications).
2. It has to be reproducible
A one-time bug is not reproducible, so it is impossible to fix as the developers need to be able to reproduce it to test and search the location in the code where the problem lies. It is also very important to give a short step-by-step guide how to reproduce the bug.
3. The subject and comment must be in English, easily understandable, and searchable
If you can’t report a bug in English, please don’t. The KDE community is international and the working language is English as it is the one most people in the community understand.
We often get reports with subjects like “Doesn’t work” or ” Your application sucks, fix it!”. This is of course not very clear and highly subjective. For a bug report to be useful it must be well described so it can be searched in the database and so it is actually understandable by the developers.
The Subject should be a short sentence summing up the important points of the bug, for example “Product X crashes when clicking on Icon Y”.
You can and should give more details in the following comment, but keep it short and with a clear structure.
4. The report should be unique
Some bugs will hit many people so it is not unlikely that many people will report it. This leads often to duplicate bug reports which need to be eliminated and collected into one unique report. Knowing that more than half of the reports we get are duplicates this will of course cause quite some triaging work.
When reporting a bug a well written subject line will allow to find duplicates in Bugzilla quite easily. It is even easier if it is a crash as usually Dr. Konqi will suggest duplicates by querying the database. In doubt, don’t submit the report but ask in IRC, search the forum or the mailing list of the project if somebody has already seen it.
Bugzilla provides a very good advanced search query one can get used to quite easily.
5. If it is a crash, it should come with a valid backtrace
But what is a valid backtrace? Most distributions will strip the applications files of their debugging symbols to gain space, especially if they ship a CD and/or DVD of their versions. Those debugging symbols can be obtained separately and have file name endings like -dbg (Debian and Debian-based distros), -debuginfo (OpenSUSE) or -debug (Mandriva) for example. You will find more information and more distributions listed in this KDE Techbase summary.
Dr. Konqi will rate the backtrace quality with stars as you can see here:
A duplicate of Bug 282875
As a general rule: do not submit crash reports that do not have 3 stars as something is missing. If you don’t have debugging symbols installed, Dr. Konqi will warn you and provides the opportunity to install them directly from within Dr. Konqi.
Of course, a backtrace should ideally always be posted in the comment and not as an attachment, so it will be searchable in the database. Hint: the important thread is the one that has [KCrashHeader] after the thread header, so you can most of the time strip the other threads.
6. Be available to give feedback if needed
By submitting a bug report you get in touch with the KDE bugsquad and developers. Make sure you will be around to give feedback and you should also be available for testing if needed. If you are not willing to contribute in that way, please do not submit reports as it will be causing more work for other people to test.
7. Be patient and polite
It is not always possible for the bugsquad and/or the developers to get back to you immediately. We get an average of 50 to 100 reports a day, of which most will be either duplicates or invalid, so there is quite some stuff to get through in a day.
Don’t forget that this is Free Software and almost all KDE people work on their projects as volunteers in their free time. So shouting at people working as volunteers is totally counterproductive as they will probably prefer to do something else instead.
Make sure you stay on topic and be polite and helpful in the same manner as you would expect others to behave towards you, this is more likely to make people work on solving the problem.
Another point to consider is that your use-case is not necessarily the unique one, there are often many ways to do things in an application and you know that KDE is highly configurable for the users. Don’t expect to be the one who does use an application in “the standard way” and be ready to accept a workaround.
If you want to help, you can of course also give a hand in triaging to clean up the database. We welcome all volunteers who want to contribute to make KDE even better! Feel free to come to the #kde-bugs channel on IRC and have a look at the links given below.
UPDATE: Just to put this in perspective of the work ahead I asked Ben Cooksley, one of our sysadmins, to give me some numbers:
With the sheer number of reports in KDE’s bugzilla and not enough people to triage, a valid report can well get drowned: as of today, October 20th 2011 the database has
- 278,805 total bugs
- 1,173,947 comments
- 64,469 attachments
- 234,403 are CLOSED/RESOLVED/VERIFIED
- 56,301 bugs were resolved as DUPLICATE
- 20,250 were resolved as INVALID.
- 40,571 open with the status ASSIGNED/ NEW/ REOPENED/ UNCONFIRMED
- 3,830 are in NEEDSINFO status
- 26,174 are UNCONFIRMED and need triaging
Thanks to Ben Cooksley, Martin Grässlin and Will Stephenson for suggestions and spotting typos 🙂
How to Report Bugs Effectively by Simon Tatham
Bug Writing Guidelines in Bugzilla
Quick Introduction to Bugzilla in KDE’s Techbase wiki
Guide to Bug Triaging by Dario Andrès in KDE Techbase