Difference between revisions of "BugFilingRecommendations"
(→Filing Useful Bug Reports) |
|||
Line 1: | Line 1: | ||
= Filing Useful Bug Reports = | = Filing Useful Bug Reports = | ||
− | Writing good bug reports is hard; useful reports are even harder. We should try our best to be thorough, so there's a consistent experience reading bugs. This document concerns itself with outlining some obvious suggestions while reporting, verifying bugs. Needless to say, further editions/modifications | + | Writing good bug reports is hard; useful reports are even harder. We should try our best to be thorough, so there's a consistent experience reading bugs. This document concerns itself with outlining some obvious suggestions while reporting, verifying bugs. Needless to say, further editions/modifications and specific examples welcome. |
* A concise (brief, but comprehensive) bug summary -- is it a bug, an enhancement, an RFE ? | * A concise (brief, but comprehensive) bug summary -- is it a bug, an enhancement, an RFE ? | ||
Line 19: | Line 19: | ||
Some obvious reasons why | Some obvious reasons why | ||
− | * Useful for new test engineers who | + | * Useful for new test engineers who do not have all the context. |
* Useful for docs folks to help them write correct errata text/release notes. | * Useful for docs folks to help them write correct errata text/release notes. | ||
* Useful for non-technical folks reading the bugs/RFEs. Clear information saves a of a lot of time. | * Useful for non-technical folks reading the bugs/RFEs. Clear information saves a of a lot of time. | ||
* Useful for downstream support organizations. | * Useful for downstream support organizations. | ||
− | * | + | * Should there be a regression years later, having all the info to test/reproduce in the bug, right there makes your day. |
* Reduces round-trip of NEEDINFO between Development and QE. | * Reduces round-trip of NEEDINFO between Development and QE. | ||
*Useful for new users referring to these. | *Useful for new users referring to these. |
Revision as of 10:37, 8 May 2013
Filing Useful Bug Reports
Writing good bug reports is hard; useful reports are even harder. We should try our best to be thorough, so there's a consistent experience reading bugs. This document concerns itself with outlining some obvious suggestions while reporting, verifying bugs. Needless to say, further editions/modifications and specific examples welcome.
- A concise (brief, but comprehensive) bug summary -- is it a bug, an enhancement, an RFE ?
- Ensure you can reproduce the bug.
- Clear instructions to reproduce the bug. Bonus points for a reproducer script.
- Version details (e.g. Grizzly? Havana ? ; Hypervisor versions - qemu/kvm/libvirt )
- Test environment details
- Most of "cloud" testing is dependent on test environment, clearer the details, lesser the round-trips between Development and QE
- Any special hardware, e.g. an exotic NAS, etc.
- Verification procedure
- Include test setup details, configuration details, other relevant context.
- If there's a fix available, and someone is verifying it, adding some verification evidence would be useful (instead of just posting a comment saying - "verified". Of course, this can be debated based on the complexity of bugs).
- Relevant log fragment, stdout of a script, or a command being executed.
- Additional info (where appropriate):
- If you've done a lot of investigation into the issue, adding a trace of that would be useful for later archival purposes. Configuration settings, caveats, reproducer scripts, etc.
Why?
Some obvious reasons why
- Useful for new test engineers who do not have all the context.
- Useful for docs folks to help them write correct errata text/release notes.
- Useful for non-technical folks reading the bugs/RFEs. Clear information saves a of a lot of time.
- Useful for downstream support organizations.
- Should there be a regression years later, having all the info to test/reproduce in the bug, right there makes your day.
- Reduces round-trip of NEEDINFO between Development and QE.
- Useful for new users referring to these.
- Overall, a very fine bug reading experience.
You get the drift!
Further reading
Resources from other related communities
- Bug writing guidelines from Mozilla -- https://landfill.bugzilla.org/bugzilla-4.2-branch/page.cgi?id=bug-writing.html
- Fedora project bug filing guidelines -- http://fedoraproject.org/wiki/How_to_file_a_bug_report