Why You Should Read This

Simply put, the more effectively you report a bug, the better able an engineer will be in actually addressing it.
These guidelines are a general tutorial to teach novice and intermediate bug reporters how to compose effective bug reports. Not every sentence may precisely apply to your software project. If you have questions, please contact:
jim.lookabaugh@wisconsin.gov
donna.lewein@wisconsin.gov
dave.winslow@wisconsin.gov

How to Write a Useful Bug Report

Useful bug reports are ones that get bugs fixed. A useful bug report normally has two qualities:
  1. Reproducible. If an engineer can't see the bug herself to prove that it exists, she'll probably stamp your bug report "WORKSFORME" or "INVALID" and move on to the next bug. Every detail you can provide helps.
  2. Specific. The quicker the engineer can isolate the bug to a specific area, the more likely she'll expediently fix it. (If a programmer has a bug report that is difficult to decipher, they may spend inordinately more time defining the issue than solving the problem.)



Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up a bug report:
BAD: "My browser crashed. I think I was on www.foo.com."
GOOD: "I crashed each time I went to www.foo.com, using the 2002-02-25 build of my Internet Explorer web browser on a Windows 2000 system. I also rebooted into Linux, and reproduced this problem using the 2002-02-24 Linux build. It again crashed each time upon drawing the Foo banner at the top of the page."

How to Complete the Form:

Next, be sure to reproduce your bug using only a supported web browser (see http://www.wijiscommons.org/gateway/browser_requirements.php).
Now, fill out the form. Here's what it all means:
Provide your name as Reporter and provide your agency name. Include the date you discovered the bug – not necessarily the date you are filling out this form.
Where did you find the bug?
Version: In which product version did you find the bug?
(Please skip this field; it is reserved for future use.)
Component: In which component does the bug exist?
Most bugs may be categorized as “App – WIJIS WebApp”. However, if you believe the bug can be more accurately categorized as one of the following, please make that selection:
Platform: On which computer hardware platform were you running your web browser when you discovered this bug? (e.g. PC, Mac.)
This item defaults to 'PC'. If you know the bug happens on all platforms, choose 'All'. Otherwise, select the computer hardware platform that you found the bug on, or "Other" if your hardware isn't listed.
OS: On which Operating System (OS) were you running your web browser when you discovered this bug? (e.g. Linux, Windows [any], Mac OS [any].)
This item defaults to 'Windows'. If you know the bug happens on all OSs, choose 'All'. Otherwise, select the OS that you found the bug on, or "Other" if your OS isn't listed.
How important is the bug?
Severity: How damaging is the bug?
This item defaults to 'normal'. If you believe a different severity is justified in your own opinion, please make the appropriate selection.
Who will be following up on the bug?
WIJIS will automatically assign the bug to a default engineer upon receipt and entry of a bug report.
Cc: Who else should receive e-mail updates on changes to this bug?
You may optionally select the e-mail addresses of other individuals who you request ought to receive an e-mail update for this bug report. Your request may or may not be honored. You can select as many e-mail addresses as you'd like.
What else can you tell the engineer about the bug?
URL:
Copy the URL from your browser's address bar for the page on which you discovered the bug.
Summary: How would you describe the bug, in approximately 60 or fewer characters?
A good summary should quickly and uniquely identify a bug report. Otherwise, an engineer cannot meaningfully identify your bug by its summary and may miss your bug report when skimming through a 10 page bug list.

"Software fails" or "install problem" would be examples of a summary too generic to be useful.


Description:
Please provide a detailed problem report in this field. Your bug's recipients will most likely expect the following information:
Overview Description: More detailed expansion of summary.
Steps to Reproduce: Minimized, easy-to-follow steps that will reliably trigger the bug. Include any special set up steps.
Actual Results: What the application did after performing the above steps.
Expected Results: What the application should have done, were the bug not present.
Browser Build and Platform: Build and platform of the browser that you first encountered the bug in. The build number can often be found in your browser's help menu / about.
Additional Builds and Platforms: Whether or not the bug takes place on other browser platforms. For example,
- Also Occurs On        
Mozilla (2002-03-15 build on Windows NT 4.0) 

- Doesn't Occur On        
Mozilla (2002-03-15 build on Red Hat Linux; feature not supported)        
Internet Explorer 5.0 (shipping build on Windows NT 4.0)        
Netscape Communicator 4.5 (shipping build on Mac OS 9.0)
Additional Information: Any other helpful information. For bugs that cause crashes/errors, please copy and paste any “stack trace” information that the Gateway may display for you on its page.
You're done!

After double-checking your entries for any possible errors, save your report and email to donna.lewein@wisconsin.gov. Your bug report will then be reviewed by Donna or another WIJIS team member before entry into WIJIS' bug report system.

More Information on Writing Good Bugs

1. General Tips for a Useful Bug Report
Use an explicit structure, so your bug reports are easy to skim. Bug report users often need immediate access to specific sections of your bug.
Avoid cuteness if it costs clarity.
One bug per report. Completely different people typically fix, verify, and prioritize different bugs. If you mix a handful of bugs into a single report, the right people probably won't discover your bugs in a timely fashion, or at all. Certain bugs are also more important than others. It's impossible to prioritize a bug report when it contains four different issues, all of differing importance.
No bug is too trivial to report. Unless you're reading the source code, you can't see actual software bugs -- you'll see their visible manifestations, such as a web page with strange characters spread throughout. Severe software problems can manifest themselves in superficially trivial ways. Please file those reports anyway! They are helpful.
2. How and Why to Write Good Bug Summaries
Capture attention by providing a compelling summary. Just like a New York Times headline guides readers towards a relevant article from dozens of choices, will your bug summary suggest that your bug report is worth reading from dozens of choices?
Conversely, a vague bug summary like ”install problem” forces anyone reviewing installation bugs to devote time opening up your bug to determine whether it is truly imperative.
Your bug will often be searched by its summary. Descriptive bug summaries are naturally keyword-rich, and easier to find.
Ask yourself, "Would someone understand my bug from just this summary?" If so, you've written a fine summary.
Don't write titles like these:
  1. "Can't install" - Why can't you install? What happens when you try to install?
  2. "Severe Performance Problems" - ...and they occur when you do what?
  3. "back button does not work" - Ever? At all?
Good bug titles:
  1. "1.0 upgrade installation fails if Mozilla M18 package present" - Explains problem and the context.
  2. "RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3) system" - Explains what happens, and the context.