Good Bug Reports - fordsfords/fordsfords.github.io GitHub Wiki

Writing a good bug report will get your problem addressed more quickly than writing a poor one. Here are some guidelines to help you.

1. Start with a SHORT summary of what the software is doing that is bad. Should be one or two sentences. If it's more than 3, you're probably putting the wrong information in it. Emphasize externally-visible symptoms, not descriptions of what's going on under the hood.

1.1. The summary should *NOT* give reproduction details. Yes, that should be in the bug report, but not right off the bat. I can't tell you how many times I've had to scroll page after page just to find the line, "and then this bad things happens." PUT THAT AT THE VERY TOP!

1.2. Don't give a diagnosis of *why* it is doing it. The worst kind of bug report says, "change this line from X to Y." Tell what the bad behavior is. Again, you can include diagnosis at the bottom of the bug report; "I think this line should be Y." But don't have that in the summary.

2. Give some environmental information. Who is having the problem? What's the software version? Platform type? Deployment architecture/topology? Give components names so that they can be talked about.

3. Give some behavioral information. Is it happening repeatedly? Or only once? If repeatedly, how frequently? Can it be triggered on demand? Can it be reproduced in a controlled environment? Or does it only happen "in the wild"?

4. Now give gory details. Reproduction steps if possible. Attach log files, of full length if practical. I.e. don't just give the 5 lines that you think are relevant. Also core files, if available. Also configuration files ... of *all* involved components, not just the one that failed.