Jump to: navigation, search

Difference between revisions of "BugFilingRecommendations"

m (Filing Useful Bug Reports)
(Filing Useful Bug Reports)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Filing Useful Bug Reports =
 
= Filing Useful Bug Reports =
Writing a ''good'' bug reports is hard. Writing a coherent, ''reproducible'' bug report is even harder. Especially when involved in complex cloud projects like OpentStack where you may have to care about everything from Kernel to user space. 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!
+
Writing a ''good'' bug reports is hard. Writing a coherent, ''reproducible'' bug report is even harder. Especially when involved in complex cloud projects like OpenStack where you may have to care about everything from Kernel to user space. 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!
  
 
* '''Summary'''. A concise summary — is it a bug? an RFE? a tracker-bug?  a personal TODO item?
 
* '''Summary'''. A concise summary — is it a bug? an RFE? a tracker-bug?  a personal TODO item?
* '''Description'''. A clear description of the issue and its ''[[symptoms in chronological orderhttp://www.catb.org/~esr/faqs/smart-questions.html#chronology|symptoms in chronological order]].
+
* '''Description'''. A clear description of the issue and its [http://www.catb.org/~esr/faqs/smart-questions.html#chronology symptoms in chronological order].
* '''Version details'''. e.g. Havana? IceHouse?, hypervisor details; API versions, anything else that’s relevant!
+
* '''Version details'''. e.g. Mitaka? Kilo?, hypervisor details; API versions, anything else that’s relevant!
 
* '''Crystal clear details to reproduce the bug'''. Bonus points for a reproducer script.
 
* '''Crystal clear details to reproduce the bug'''. Bonus points for a reproducer script.
 
* '''Test environment details'''. (This is crucial.)
 
* '''Test environment details'''. (This is crucial.)
Line 34: Line 34:
 
== Further reading ==  
 
== Further reading ==  
 
Resources from other related communities
 
Resources from other related communities
* [[Notes from Sean Dague after doing a lot bug triaging during Juno release cyclehttp://lists.openstack.org/pipermail/openstack-dev/2014-September/046517.html|Notes from Sean Dague after doing a lot bug triaging during Juno release cycle]]  
+
* [http://lists.openstack.org/pipermail/openstack-dev/2016-November/106797.html  A note to contributors - bug triage ftw! (Matt Riedemann)]
* [[Bug writing guidelines from Mozillahttps://landfill.bugzilla.org/bugzilla-4.2-branch/page.cgi?id=bug-writing.html|Bug writing guidelines from Mozilla]]  
+
* [http://lists.openstack.org/pipermail/openstack-dev/2014-September/046517.html Notes from Sean Dague after doing a lot bug triaging during Juno release cycle]  
* [[Fedora project bug filing guidelineshttp://fedoraproject.org/wiki/How_to_file_a_bug_report|Fedora project bug filing guidelines]]
+
* [https://landfill.bugzilla.org/bugzilla-4.2-branch/page.cgi?id=bug-writing.html Bug writing guidelines from Mozilla]
 +
* [http://fedoraproject.org/wiki/How_to_file_a_bug_report Fedora project bug filing guidelines]

Latest revision as of 13:33, 6 April 2018

Filing Useful Bug Reports

Writing a good bug reports is hard. Writing a coherent, reproducible bug report is even harder. Especially when involved in complex cloud projects like OpenStack where you may have to care about everything from Kernel to user space. 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!

  • Summary. A concise summary — is it a bug? an RFE? a tracker-bug? a personal TODO item?
  • Description. A clear description of the issue and its symptoms in chronological order.
  • Version details. e.g. Mitaka? Kilo?, hypervisor details; API versions, anything else that’s relevant!
  • Crystal clear details to reproduce the bug. Bonus points for a reproducer script.
  • Test environment details. (This is crucial.)
    • Most of "cloud” software testing is dearly dependent on test environment. Clearer the details, fewer the round-trips between developers, test engineers, packagers, triagers, etc.
    • Note down if any special hardware is needed for testing, e.g. an exotic NAS, etc.
    • If you altered anything — config files, especially code located in /usr/lib/pythonx.x/site-packages/, or any other dependent lower-layer project configurations (e.g. libvirt’s config file), please say so.
  • Actual results. Post the exact, unedited details of what happens when the bug in question is triggered.
  • Expected results. Describe what is the desired behavior.
  • Additional investigative details (where appropriate).
    • If you’ve done a lot of digging into an issue, writing a detailed summary (even better: a blog post) while its fresh in memory is very useful. Along with addition info like – configuration settings, caveats, relevant log fragment, stderr of a script, or a command being executed, adding trace details — all of which would be useful for archival purposes (and years later, the context would come in very handy)

Why?

Some obvious reasons why

  • Useful for new test engineers who do not have all the context of a bug.
  • Useful for documentation writers to help them write correct errata text/release notes.
  • Useful for non-technical folks reading the bugs/RFEs. Clear information saves a heck of a lot of time.
  • Useful for folks like product and program managers who’re always not in the trenches.
  • 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 needless round-trips of NEEDINFO between various parties.
  • Useful for new users referring to these bugs in a different context.


Overall, a very fine bug reading experience.

You get the drift!

Further reading

Resources from other related communities