April 1, 2002

How to find and report software bugs

Author: Peter Galli

- By Telsa Gwynn -
Anyone can file a bug on anything: The difficult part is
knowing how to write the report and where to send it. For some reason, people
are wary about entering trivial bugs or typos in things users can see (dialogue
boxes and docs for example) if they know there are worse bugs to
fix. But they are easy to fix: People just have to know they exist.Bug-reporting is a learning curve, and it does take time at first,
but then it gets faster and faster until it's routine. You get to pick
things up about what might be relevant, and how to search different
bug-trackers effectively, and where developers think an obvious
place to put FAQs and bug report hints are.

I think the biggest thing is to stop every time you notice
something odd and look at it there and then. If I meet a bug
in a new program and think "I'll just finish this and then
go back to that bug," I tend not to be able to find it again.

Take notes: whether on paper, on the computer, or into a
tape-recorder. Don't do it on the computer if it's an X or kernel
hang or crash: unless you have auto-save on in your editor you'll
lose your notes. A separate machine is okay though. If there's
an error message, copy it precisely. If it's horrendously long
and you have a digital camera, take a photo and stick the pic on
the Web. (I've seen kernel oopses treated like this.)

If your screensaver or apm is going to kick in before you can copy half
a screen of X crash errors, read the numbers into a tape recorder
slowly and then play it back and type it in at your leisure. If it's
something at the console and isn't a crash, use "script" to
capture exactly what you typed and what spewed out. Script is
brilliant for saving stack traces from gdb if you don't have
cut and paste handy, too.

Particularly, write down exactly what you did. "How to reproduce" is
often the most important bit, especially if some kind maintainer makes
a patch and you apply it and try to test the fix and think, "Now, how
did I get it to do that again?"

Then, figuring out what exactly broke is the next big one, and that
can be a pig. Because UNIX is so full of lots of little programs
calling different ones to do different bits, what you start is not
always what's actually breaking: Sometimes it's a library the
program is using and sometimes it's even more arcane. A really
good (or bad, depending on your point of view) example was the
time I wrote a quick rot13 script using the "tr" command. The
script broke in peculiar ways. The culprit was not exactly obvious.
Earlier, I had changed my locale to en_GB. Changing your locale that
way changes the sort order (LC_COLLATE). And the way I had used tr
relied on the sort order being "C" rather than "en_GB". Uurgh. I was
fairly proud that I figured that out before Alan did.

It's worth checking the FAQ, /usr/(share/)doc/packagename/README, and
already-open bugs against the package. I wrote a very long screed
"docs wrong" for one app a while back, checked bugzilla before
it, and someone else had already done it for me. So I just added
some extra to that one.

And file the bug. Add something about "what more information do you
need?" because it's very possible there is more: I have become
used to attaching XF86Configs, the output of lspci -vv, my .gtkrc
and so on. Developers differ here: RH's bugzilla tends to be full
of "Please run this command and attach the results," but some other
people give responses of, "Do you have the foo module and was
poo compiled with -- plop?" which is not always something I can answer.

The other thing to remember is that developers are human, too.
Slagging off the package and the character of the person who wrote
it with copious ad hominem attacks is not going to get your bug
looked at first. Sadly, there are the occasional folk who treat
bug-trackers as a way to flame people. This isn't fun and it's
not fair on the people going through the bugs, who are not necessarily
going to be the person who wrote it in the first place. Saying "I am
going to use this any more" isn't a good idea either: Why fix it if
the reporter is not going to test the fix?

Of course, it works both ways. Developer responses of, "Don't do
that, then," "This is not a bug," or just silence are not at
all encouraging. And blaming users for, "You used the wrong
compiler," when the user just shoved a CD in is not fair. There
are some apps I won't file bugs on these days because I'm scared
of the response I'll get from certain people.

Wow, I bet I put everyone off now. If you're not sure where
bugs go, I have a partial
list of bug-trackers
I use on my Web site: I'm thinking of turning it into
something more complete. If I didn't put people off, I suppose the advice is to
find a package you like -- or that you want to learn about, because
it's often people who haven't subconsciously learned workarounds
who find the real howlers. And then just read the man page, try
it with different versions of options, feed it obvious stuff by
extrapolation of, "Well, if this works, then this should ... oops."

Click Here!