Effective issue reports assist in the process of refining projects and reaching the ultimate goal of completion. This document is designed to provide a brief tutorial in writing effective issue reports.How to write a useful issue report
A useful issue report normally has two qualities:
For example: you're testing is a web browser. You crash at foo.com, and want to write up an issue report:
Inappropriate: "My browser crashed. I think I was on foo.com. My computer uses Windows. I think that this is a really bad problem and you should fix it now. By the way, your icons really suck. Nobody will use your software if you keep those ugly icons. Oh, and my grandmother's home page doesn't look right, either, it's all messed up. Good luck."
More appropriate: "I crashed each time when I went to foo.com, using the 10.28.99 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced this problem using the 10.28.99 Linux build.
It again crashed each time upon drawing the Foo banner at the top of the page. I broke apart the page, and discovered that the following image link will crash the application reproducibly, unless you remove the "border=0" attribute:
<IMG SRC="http://foo.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News">"How to Enter your useful issue report into Issue Tracker:
Before you enter your issue, use the Issue Tracker query page to determine whether the defect you've discovered is a known issue, and has already been reported. (If your issue is the 37th duplicate of a known issue, you're more likely to annoy the engineer. Annoyed engineers fix fewer issues.)
Next, be sure that you've reproduced your issue using a recent build. (Engineers tend to be most interested in problems afflicting the code base that they're actively working on, rather than those in a code base that's hundreds of issue fixes obsolete.)
If you've discovered a new issue using a current build, report it in the Issue Tracker:
Now, fill out the form. Here's what it all means:
Where did you find the issue? Component: In which product did you find the issue?
Data for this field was entered on the previous screen.Version: In which product version did you find the issue?
Enter, if applicable.Subcomponent: In which subcomponent does the issue exist?
The Issue Tracker requires that you select a component to enter an issue. If they all look meaningless, click Component, which links to descriptions of each component, to help you make the best choice.Platform: On which hardware platform did you find this issue?
E.g., Macintosh, SGI, Sun, PC. If you know the issue happens on all hardware platforms, choose "All." Otherwise, select the platform that you found the issue on, or "Other" if your platform isn't listed.OS: On which Operating System (OS) did you find this issue?
E.g., Linux, Windows NT, Mac OS 8.5. If you know the issue happens on all operating systems, choose "All." Otherwise, select the OS that you found the issue on, or "Other" if your OS isn't listed.
How important is the issue?Issue Type: Is this a defect, enhancement, feature-request, or task?
This item defaults to "defect". (To determine the most appropriate type of issue,
Who will be following up on the issue?
Assigned To: Which engineer should be responsible for fixing this issue?
The Issue Tracker will automatically assign the issue to a default member upon submitting an issue report; the text box exists to allow you to manually assign it to a different member. To see the list of default members for each subcomponent, click Subcomponent.
NOTE: the assigned to field can be configured as either a drop down box or a text box in which you can manually type the name of the user to be assigned. As a drop down box, the usernames listed have direct roles in the project.
Cc: Who else should receive e-mail updates on changes to this issue?
List the username of other individuals who should receive an e-mail update upon every change to the issue report. You can enter as many user ids as needed; user ids must be separated by commas, with no spaces between the addresses.
What else can you tell the engineer about the issue?
URL: On what URL did you discover this issue?
If you encountered the issue on a particular URL, please provide it (or, them) here. If you've isolated the issue to a specific HTML snippet, please also provide a URL for that, too.Summary: How would you describe the issue, in approximately 60 or fewer characters?
A good summary should quickly and uniquely identify an issue report. Otherwise, developers cannot meaningfully query by issue summary, and will often fail to pay attention to your issue report when reviewing a 10 page issue list.
A summary of "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C" is a useful title. "Software fails" or "install problem" would be examples of a bad title.Description: What else can you tell the engineer about this issue?
Please provide as detailed of a problem diagnosis in this field as possible.
Where applicable, using the following issue report template will help ensure that all relevant information comes through:Overview Description: More detailed expansion of summary.
Drag-selecting any page crashes Mac builds in NSGetFactorySteps to Reproduce: The minimal set of steps necessary to trigger the issue. Include any special setup steps.
1) View any web page. (I used the default sample page, resource:/res/samples/test0.html) 2) Drag-select the page. (Specifically, while holding down the mouse button, drag the mouse pointer downwards from any point in the browser's content region to the bottom of the browser's content region.)Actual Results: What the application did after performing the above steps.
The application crashed. Stack crawl appended below from MacsIssue.Expected Results: What the application should have done, were the issue not present.
The window should scroll downwards. Scrolled content should be selected. (Or, at least, the application should not crash.)Build Date & Platform: Date and platform of the build that you first encountered the issue in.
11/2/99 build on Mac OS (Checked Viewer & Apprunner)Additional Builds and Platforms:
Whether or not the issue takes place on other platforms or browsers.
- Occurs On Seamonkey (11/2/99 build on Windows NT 4.0) - Doesn't Occur On Seamonkey (11/4/99 build on Red Hat Linux; feature not supported) Internet Explorer 5.0 (RTM build on Windows NT 4.0) Netscape Communicator 4.5 (RTM build on Mac OS)
Any other distinguishing information. For crashing issues:
*** MACSISSUE STACK CRAWL OF CRASH (Mac OS) Calling chain using A6/R1 links Back chain ISA Caller 00000000 PPC 0BA85E74 03AEFD80 PPC 0B742248 03AEFD30 PPC 0B50FDDC NSGetFactory+027FC PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0
After double-checking your entries for any possible errors, press the Submit button, and your issue report will now be in the Issue Tracker database.