Bug Reporting Guidelines
How to Write a Useful Bug Report
The more effectively you report a bug, the more likely an engineer will actually fix it. Useful bug reports are ones that get bugs fixed. A useful bug report normally has two qualities:
- Reproducible. If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it "WORKSFORME" or "INVALID", and move on to the next bug. Every detail you can provide helps.
- Specific. The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed. (If a programmer or tester has to decypher a bug, they spend more time cursing the submitter than fixing or testing the problem.)
These guidelines explain how to write such reports. Generally, follow these principles:
- Be precise
- Be clear - explain it so others can reproduce the bug
- One bug per report
- No bug is too trivial to report - small bugs may hide big bugs
- Clearly separate fact from speculation
Reporting a New Bug
If you have reproduced the bug and no-one else appears to have reported it, then:
- Go to the bug tracker
- Choose "Submit New"
- Enter a summary
- Fill out the details. This is what you should include:
How would you describe the bug, in approximately 60 or fewer characters?
The details of your problem report, including:
More detailed restatement of summary.
Steps to Reproduce
Minimized, easy-to-follow steps that will trigger the bug. Include any special setup steps. It may help to number the steps. It should allow us to reproduce the bug.
Describe what the application did after performing the above steps.
What the application should have done, or you think it should have done, were the bug not present.
Include the version of BibDesk (from the About window), your version of Mac OSX, and the architecture and type of your computer. If you can, also include a regression range (which versions of BibDesk had the problem, and which didn't).
For crashes, attach crash reports related to your problems. You can find those in Console.app.
Attach console logs related to your problems. You can find those in Console.app.
For hangs (beach-balls), attach a sample taken while BibDesk is unresponsive. To create a sample, open Activity Monitor.app, select BibDesk and hit Inspect (or double-click), click the Sample button (lower-right). After the sample has been taken, you will be able to save it.
Any other useful information.