Reporting Bugs

We all want to fix bugs fast and well; however, fixing bugs takes time and effort, which are in short supply among volunteers. To ensure that a bug is dealt with as speedily and efficiently as possible, please follow the instructions below.

First, make sure it's a bug. If Tracer does not behave the way you expect, look in the documentation and mailing list archives for evidence that it should behave the way you expect. You should also search in the bug tracker to see if anyone has already reported this bug. Just to be sure, check that you are running the latest version of Tracer - maybe the bug has already been found and fixed.

Once you've established that it's a bug, and that we don't know about it already, the most important thing you can do is come up with a simple description and reproduction recipe. For example, if the bug, as you initially found it, involves five files over ten commits, try to make it happen with just one file and one commit. The simpler the reproduction recipe, the more likely a developer is to successfully reproduce the bug and fix it.

When you write up the reproduction recipe, don't just write a prose description of what you did to make the bug happen. Instead, give a literal transcript of the exact series of commands you ran, and their output. Use cut-and-paste to do this. If there are files involved, be sure to include the names of the files, and even their content if you think it might be relevant. 

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, Python version, and other relevant infrastructure.
  
• The release of Tracer, or the Git repository and commit from which you are running Tracer.
  
• Any private modifications you made to your version of Tracer.
  
• 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 Tracer 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 — see the developer guidelines.

Post all of this information to the mailing list, or if you have already been there and been asked to file an issue, then go to the bug 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.