Writing bug reports

by Tim Wood on May 15, 2007

Now that OmniFocus is sticking its toes out the door, this seems like a good time to remind everyone about best practices on reporting problems. Crash reports are especially important and should receive extra care.

  • Please report every single crash you hit, even if you don't know how to reproduce it yet. Include any details of what you were doing leading up to the crash. We can then correlate reports from different users to narrow down the cause, even if no one person can reliably reproduce the problem.

  • If you are comfortable doing so, include your document as a starting point (for OmniFocus, this is in ~/Library/Application Support/OmniFocus). If you have qualms about sending your data, skipping this is OK. Another option is to export your file to a backup and then trim down that copy to include only the portions necessary to reproduce the problem.

  • List the exact steps to reproduce the problem, starting from the file you included or from an empty document. It is hard to be too specific: for example, you might be tempted to say “I deleted the second task of the project 'Foo'”, but this doesn't make it clear whether you used the delete key, a main menu item, a context menu, invoked an AppleScript, or picked up the task and dragged it to the trash. In some cases, the distinction matters. When in doubt, describe the physical actions you used (“press key X”, “clicked button Y”).

  • If the proper behavior isn't obvious (“don't crash”), tell us what you expected to happen. Maybe you have a perspective on a design question we haven't considered or that we should reconsider.

With crash reports in particular, it is important to include reproducible steps. Sometimes this isn't possible, and that's fine – please report the crash anyway with whatever details you have. With a large enough pool of people, someone will be able to figure out how to reproduce it.

Crash reports are CC'd directly to the entire OmniFocus engineering team. If you include reproducible steps, we'll typically stop whatever else we're working to fix it immediately.