How to report bugs effectively

First, make sure it’s a bug. If SIP Communicator does not behave the way you expect, look in the users documentation and mailing list archives for evidence that it should behave the way you expect. Of course, if it’s a common-sense thing, like SIP Communicator just destroyed your data and caused smoke to pour out of your monitor, then you can trust your judgement. But if you’re not sure, go ahead and ask on the users mailing list first, or ask in IRC.

Once you’ve established that it’s a bug, the most important thing you can do is come up with a simple description and reproduction recipe. The simpler the reproduction recipe, the more likely a developer is to successfully reproduce the bug and fix it.

Quick sanity check: you *are* running the most recent version of SIP Communicator, right? :-) Possibly the bug has already been fixed; you should test your reproduction recipe against the most recent SIP Communicator development tree.

In addition to the reproduction recipe, we’ll also need a complete description of the environment in which you reproduced the bug. That means:

• Your operating system
• The release and/or revision of SIP Communicator
• The compiler and JVM you built and run SIP Communicator with
• Any private modifications you made to your SIP Communicator
• SIP Communicator logs or console output
• Ethereal / tcpdump binary capture traces
• Anything else that could possibly be relevant. Err on the side of too much information, rather than too little.

Once you have all this, you’re ready to write the report. Start out with a clear description of what the bug is. That is, say how you expected SIP Communicator to behave, and contrast that with how it actually behaved. While the bug may seem obvious to you, it may not be so obvious to someone else, so it’s best to avoid a guessing game. Follow that with the environment description, and the reproduction recipe. If you also want to include speculation as to the cause, and even a patch to fix the bug, that’s great — read instructions on sending patches.

Post all of this information to the dev mailing list, or if you have already been there and been asked to file an issue, then go to the Issue Tracker and follow the instructions there.

Thanks. We know it’s a lot of work to file an effective bug report, but a good report can save hours of a developer’s time, and make the bug much more likely to get fixed.

This document has been strongly influenced by Subversion’s “Reporting bugs” section