Skip to content

start:

Issue Writing Guidelines

$Date: 2007/02/23 11:26:39 $

Consider the rules

We strongly encourage you to read the Basic IssueTracker rules - for those who work with IssueTracker on a day-by-day base, they have proven to immensely reduce their work. It's really easy for you to report issues in a way which cost all others a lot of time, but if you invest a little more effort in the beginning, you save others a lot thereof afterwards.

Thus, if you're new to OpenOffice.org's IssueTracker, please read the rules. And, of course, please follow them :-), to make our all work easier, so we can concentrate on improving the product, instead of wasting time with bad issue reports.

And, please don't be offended if we ask you to follow some rules: Simply put, the more effectively you report an issue, the more likely an engineer will actually fix it, and this is what we all are interested in.

How to Write a Useful Issue Report

Useful issue reports are ones that get issues fixed. A useful issue report normally has two qualities:

  1. 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.

  2. 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 spreadsheet application. You crash at when you open the file foo.sxc, 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 IssueTracker

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 IssueTracker and also has some useful IssueTracker links, such as a query link.

Go to the IssueTracker 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 IssueTracker:

  1. If you're not already logged in, please enter your username & password in the appropriate filds at the top of this page (or any other page on this site)
  2. From your IssueTracker main page, choose "Enter a new issue".
  3. Select the product that you've found an issue in.

regarding 2., there is a link "File Issue" as well, accessible from the "My Pages"-tab (When logging in you're automatically directed to "My Pages", you can then access IssueTracker using the links in the "My Tools" box on the left side of your screen)

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 find the issue?
If applicable.
Component: In which component does the issue exist?
IssueTracker 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.)
Priority: How much does the problem affect the product's overall usefullness?
Developers use this field as one measure how to priorize their work.
This item defaults to '3'. 1 is the highest (rarely used), 5 the lowest priority.
Please read the definition of issue priorities carefully before attempting to use P2 or even P1.

Who will be following up on the issue?
Assigned To: Which engineer should be responsible for fixing this issue?
IssueTracker 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 most people use 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.)

Note: You cannot add OpenOffice.org files natively. They must be added as "binary" files. This is a temporary problem.

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 gets corrupted when others try to download it.

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 IssueTracker 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, and Chris Yeh for contributing to this document. Constructive suggestions and feedback is welcome. In this case just post your suggestions to the dev@qa mailing list.)