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:
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.
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:
“Security –
Gateway Authentication” for any issues with logging in either
through single factor (userID and password) or through second factor
(one-time-password token).
“Security –
Gateway Authorization” for any issues with accessing the
Gateway application's pages or with accessing sensitive, shared
information such as juvenile pointers.
“Service ****”
There are several services of the Gateway that perform pointer
submission functions, searching, and record retrieval. If you
believe your discovered bug relates to one of these services, make
that appropriate selection.
“Session
Management” for any issues with interruption in your flow of
work. For example, if you are unexpectedly prompted to log in when
you thought you had already successfully logged in, this selection
may be right for you. Another example would be if you lose your
place within the Gateway, lose results, or lose form settings.
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:
"Can't
install" - Why can't you install? What happens when you try to
install?
"Severe
Performance Problems" - ...and they occur when you do what?
"back button does
not work" - Ever? At all?
Good
bug titles:
"1.0
upgrade installation fails if Mozilla M18 package present" -
Explains problem and the context.
"RPM 4 installer
crashes if launched on Red Hat 6.2 (RPM 3) system" - Explains
what happens, and the context.
Content of this site remains the property of its poster.