Issue Writing Guidelines
Why you should read this
Simply put, the more effectively you report an issue, the more likely an engineer will actually fix it. These issue writing guidelines are an attempt at a general tutorial on writing effective issue reports for novice issue writers; not every sentence may precisely apply to your software project.
How to Write a Useful Issue Report
Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:
- Reproducible. If an engineer can't see it or conclusively prove that it exists, the engineer will probably stamp it "WORKSFORME" or "INVALID", and move on to the next issue. Every detail you can provide helps.
- Specific. The quicker the engineer can isolate the issue to a specific problem, the more likely it'll be expediently fixed. (If a programmer or tester has to decipher an issue, they spend more time cursing the submitter than fixing or testing the problem.)
Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up an issue report:
Bad: "My spreadsheet crashed when I tried to open a document. I think it contained a chart. 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 has a problem with the word processor. Nothing works right, either. Good luck."
Good: "I crashed each time when I opened the attached spreadsheet document using the 10.13.00 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux (RedHat 6.2), and reproduced this problem using the 10.13.00 Linux build.When I removed the chart from the document I was able to load it without any trouble."
How to enter a useful Issue Report into IssueZilla
In order to file an Issue, you must be a registered user of OpenOffice.org. Registering is easy: simply click on the "Join" link in the left navbar and follow the instructions. It takes all of a few minutes. If you are a registered user, click on the "My Issues" link in the left navbar or on the "Bugs and Issues" link on the navbar. The latter is a more comprehensive page which provides a explanation of IssueZilla and also has some useful IssueZilla links, such as a query link.Go to the IssueZilla 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 IssueZilla:
-
From your IssueZilla main page, choose "Enter a new issue".
-
Select the product that you've found an issue in.
-
Enter your E-mail address, Password, and press the "Login" button. (If you don't yet have a password, leave the password text box empty, and press the "E-mail me a password" button instead. You'll receive an E-mail message with your password shortly.)
Now, fill out the form. Here's what it all means:
Where did you find the issue?
Product: In which product did you find the issue?
You just filled this out on the last page.
Version: In which product version did you first find the issue?
If applicable.
Component: In which component does the issue exist?
IssueZilla requires that you select a component to enter an issue. (If they all look meaningless, click on the Component link, 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., 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)
If you know the issue happens on all OSs, 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, task or patch?
This item defaults to 'defect'. (To determine the most appropriate type of issue, click on the Issue Type link for a full explanation of each choice.)
Resolution Priority: How urgent is a fix required?
This item defaults to '3'. 1 is the highest, 5 the lowest priority.
Who will be following up on the issue?
Assigned To: Which engineer should be responsible for fixing this issue?
IssueZilla will automatically assign the issue to a default engineer upon submitting an issue report; the text box exists to allow you to manually assign it to a different engineer. (To see the list of default engineers for each component, click on the Component link.)
Cc: Who else should receive e-mail updates on changes to this issue?
List the full e-mail addresses of other individuals who should receive an e-mail update upon every change to the issue report. You can enter as many e-mail addresses as you'd like; e-mail addresses 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.
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 "Abort trying to install on RedHat 7.0, Kernel 2.2.14" 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. A precise step-by-step description is the best way to do it.
For crashing issues it might help to have additional information in case you're able to provide that:
Target Milestone. Think of it as a deadline; targets are "not determined" or "next build"--for most issues, stipulate "not determined."
Attachments. It may be the case you need to add an attachment(s) to an Issue, either the one you file or another one. You can do it; the limit is 10MB, but please keep any attachment small, as there are still some using 56K connections. Attaching a file to an issue is a two-step procedure and is not obvious. You must first submit the issue or locate the issue to which you wish to attach the file. Then, you can add the file as an attachment to that issue. There will be a link in the issue body that reads:
Create a new attachment (proposed patch, testcase, etc.)Hints: Reduce the size of your file as much as possible. And, if you are uploading an HTML document, be sure to compress it first (Zip or tar it), otherwise it may get corrupted when others try to download it.
MIME types: Select the correct mime type for you attachment from the MIME type pulldown panel For OpenOffice.org 2.x documents, choose the corresponding "application/vnd.oasis.opendocument."
You're done! After double-checking your entries for any possible errors, press the "Commit" button, and your issue report will now be in the IssueZilla database.
(These Bug Writing Guidelines were originally written for Mozilla by Eli Goldberg. Thanks to Claudius Gayle, Peter Mock, Chris Pratt, Louis Suarez-Potts, Tom Schutter, Rainer Bielefeld, and Chris Yeh for contributing to this document. Constructive suggestions and feedback are welcome.)
