Documentation< Previous | Contents | Next >
What to Put in the Bug Report
Instructions to Reproduce the Problem To be able to reproduce the issue, the developers need to know what you are using, where you got it from, and how you installed it.
You should provide precise, step-by-step instructions describing how to reproduce the problem. If you need to use some data to reproduce the problem, attach the corresponding file to the bug report. Try to come up with the minimal set of instructions needed to reproduce the bug.
Give Some Context and Set Your Expectations Explain what you were trying to do and how you expected the program to behave.
In some cases, the bug is only triggered because you were using the program in a way that it was not designed to operate by the developers. By explaining what you were trying to achieve, you will allow the developers to clearly see when this is the case.
In some other cases, the behavior that you describe as a bug might actually be the normal behavior. Be explicit about what you expected the program to do. This will clarify the situation for the developers. They may either improve the behavior or improve the documentation, but at least they know that the behavior of their program is confusing some users!
Be Specific Include the versions numbers of the software that you use, possibly with the version numbers of their dependencies. When you refer to something that you downloaded, include its complete URL.
When you get an error message, quote it exactly as you saw it. If possible, include a copy of your screen output or a screenshot. Include a copy of any relevant log file, ensuring that you remove any sensitive data first.
Mention Possible Fixes or Workarounds Before filing the bug report, you probably tried to re- solve the problem. Explain what you tried and what results you received. Be very clear about what is a fact and what was just a hypothesis on your part.
If you did an Internet search and found some explanations about a similar problem, you can men- tion them, in particular when you found other similar bug reports in the Debian bug tracker or in the upstream bug tracker.
If you found a way of achieving the desired result without triggering the bug, please document that as well. This will help other users who are hit by the same issue.
Long Bug Reports Are Fine A two-line bug report is insufficient; providing all the information needed usually requires several paragraphs (or sometimes pages) of text.
Supply all the information you can. Try to stick to what is relevant, but if you are uncertain, too much is better than too little.
If your bug report is really long, take some time to structure the content and provide a short summary at the start.