Reporting Bugs
Introducing Bugs
XXX Need a good definition of a bug.
Bugs are a largely accepted part of the software development process.
Almost every moderate or larger program has bugs - a "debugged" program
merely has the most common ones removed.
There are some software development processes that claim to produce
"zero bugs" -- usually this means zero bugs discovered over the lifetime
of the product.
If you use enough software, you will eventually discover a bug. With
free software, you can modify the code yourself, find and fix the bug,
and send the fix to the developers. If you're not able to do this, you
might want to alert the developers to the bug.
In this page, we'll discuss how to report bugs. If you're a developer,
you might want to condense this information, and put it in your
package, so that when users report bugs to you, the bug reports
are as useful as possible.
Why Good Bug Reports Are Important
Developers don't like fixing bugs as much as they like adding
features. Fixing bugs is stressful, frustrating, and depressing.
If writing software is the party, debugging is the hangover (and
for some developers, documentation is the cleaning up!).
What makes bugs difficult to find is that you don't know what was done
incorrectly to cause the bug. The major weapon that developers have
to find bugs is information. The more information they have about
the bug, the easier it is to study it in isolation, and trace it to
the source.
If you send them a bug report that is vague, inconsistent or
low on details, they're likely to judge it as difficult to find,
and less likely to fix it, unless it has serious consequences.
This isn't because the developer is lazy, it's just that they have
to weigh the benefit of spending hours searching for a hard to find
bug (that they might not find), or spending hours improving on things
that they know they can make progress on.
What Is A Bug Report?
Put simply, a bug report is a statement of all the facts known
about a problem. It is usually a piece of email. Some software systems
have automatic tools to help you compose the email and send it to
the right place (for example, the bash shell includes a program called
bashbug). Other software asks you to use a web interface to
report the bug. The instructions on bug reporting should be put
in the documentation for the software, usually in the README file,
or perhaps on the associated web page for the software.
The Contents Of A Bug Report
You should make sure you answer all of these questions. Don't
try to guess what the bug is and "save time" by leaving out
what you think it "irrelevant" information. You'll usually
just get a request for the missing information anyway.
What's The Problem?
- Are you reporting a bug, requesting a feature, or suggesting an
improvement?
- What software are you using?
- What version of the software are you using?
- What is the symptom of the bug? (Include exact error messages if
possible).
- What exactly is wrong? (if the output is incorrect, how is it
incorrect - what should it be instead?)
- Apart from the immediate symptom, are there any extra effects?
On What System?
- What is your operating system?
- What version of the operating system are you using?
- What hardware is it running on? (Particularly important if the
software is a device driver of some sort).
- What alternatives are you using, if there are any? (e.g. Graphical
interface, or text interface?).
- Did you do anything unusual when building it (if not, say so)?
- If your program was already compiled, say so, and where you got it from.
(Sometimes this is obvious - e.g. if you are reporting a bug with
a packaged system. It doesn't hurt to say so anyway, because you never
know who the mail might get forwarded to).
What Were You Doing At The Time?
- What action were you performing at the time? (compiling?
word-processing? spell-checking? drawing with the square brush?)
- What options were you using at the time? (include a copy of
relevant configuration files)
- Can you do it again and again?
- Has anyone else repeated it (or have you tried it under different
circumstances and it did work?).
- If you have a particular test case, include it. Try to use
something they have a chance of repeating.
Other Information
- How can you be contacted for more information? (a valid email
address is usually enough).
- Give a concise description of the bug (usually the "Subject" of the
email report).
Bug reporting checklist:
- What program and version has the bug.
- Symptoms of bug.
- Instructions on how to reproduce the bug.
- Architecture (chip, operating system, relevant hardware).
- How executable was created (compiler, libraries, build
tool, download site).
- Correct return address.
- Relevant log files or input data.
- Any other information that might be helpful.
