Bug_Reporting_Guidelines Log in to Edit
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 "Create Ticket"
- Enter a summary
- Fill out the details. This is what you should include:
Summary:
How would you describe the bug, in approximately 60 or fewer characters?
Detailed Description:
The details of your problem report, including:
Overview
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.
Actual Results
Describe what the application did after performing the above steps.
Expected Results
What the application should have done, or you think it should have done, were the bug not present.
Configuration
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).
Crash Reports
For crashes, attach crash reports (diagnostic reports) related to your problems. You can find those in Console.app.
Logs
Attach console logs related to your problems. You can find those in Console.app.
Samples
For hangs (beach-balls), attach a sample taken while BibDesk is unresponsive. To create a sample, open Activity Monitor.app, select BibDesk and choose View > Sample Process, or hit Inspect/double-click and click the Sample button. After the sample has been taken, you will be able to save it.
Additional Information
Any other useful information.