Jump to: navigation, search

BugFilingRecommendations

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).
  • If you altered anything ( config files, especially code located in /usr/lib/pythonx.x/site-packages/, anything else), *please* say so.
  • 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, relevant log fragment, stdout of a script, or a command being executed. 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