<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Issue Writing Guidelines</title>
</head>
<body>
<div class="app">
<h2>Issue Writing Guidelines</h2>
<h4>Consider the rules<br>
</h4>
<p>We strongly encourage you to read the <a href="basic_rules.html">Basic
Bugzilla rules</a> - for those who work with Bugzilla on a
day-by-day base, they have proven to <span style="font-style: italic;">immensely</span>
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.<br>
</p>
<p>Thus, if you're new to OpenOffice's Bugzilla, please <a
 href="basic_rules.html"> read the rules</a>. 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.</p>
<p>And, please don't be offended if we ask you to follow <a
 href="basic_rules.html"> some rules</a>: 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. </p>
<h4>How to Write a Useful Issue Report</h4>
<blockquote>
  <p>Useful issue reports are ones that get issues fixed. A useful
issue report normally has two qualities:</p>
</blockquote>
<ol>
  <li> <b>Reproducible.</b> 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. </li>
  <br>
  <li> <b>Specific.</b> 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.) </li>
</ol>
<blockquote> 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: </blockquote>
<blockquote> <b>Bad:</b> "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." <br>
  <br>
  <b>Good:</b> "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.
  <p>When I removed the chart from the document I was able to load it
without any trouble." </p>
</blockquote>
<h4>How to enter a useful Issue Report into Bugzilla</h4>
<blockquote> 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 <a href="project_issues.html" target="_blank">"Bugs
and Issues"</a> 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.
  <p> Go to the <a href="https://bz.apache.org/ooo/query.cgi"
 target="_blank">Bugzilla Query Page</a> 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.)
  </p>
  <p>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.)<br>
  <br>
If you've discovered a new issue using a current build, report it in
IssueTracker: </p>
  <ol>
    <li> If you're not already logged in, please enter your username
&amp; password in the appropriate fields at the top of this page (or any
other page on this site)</li>
    <li> From your Bugzilla main page, choose "Enter a new issue".</li>
    <li> Select the product that you've found an issue in.</li>
  </ol>
  <p>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 Bugzilla using the links in the
"My Tools" box on the left side of your screen)</p>
</blockquote>
<h4>Now, fill out the form. Here's what it all means:</h4>
<blockquote> <i>Where did you find the issue? </i></blockquote>
<blockquote> <b>Product: In which product did you find the issue?</b><br>
You just filled this out on the last page. </blockquote>
<blockquote> <b>Version: In which product version did you find the
issue?</b><br>
If applicable. </blockquote>
<blockquote> <b>Component: In which component does the issue exist?</b><br>
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.) </blockquote>
<blockquote> <b><a
 href="https://issues.apache.org/ooo/page.cgi?id=fields.html#rep_platform">
Platform</a>:&nbsp;On which hardware platform did you find this issue? </b>(e.g.,
Sun, PC)<br>
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. </blockquote>
<blockquote> <b>OS: On which Operating System (OS) did you find this
issue?</b> (e.g. Linux, Windows NT)<br>
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. </blockquote>
<blockquote> <br>
  <i>How important is the issue? </i></blockquote>
<blockquote> <b><a
 href="https://issues.apache.org/ooo/page.cgi?id=fields.html#cf_bug_type">
Issue Type</a>: Is this a defect, enhancement, feature-request, task or
patch?</b><br>
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.) </blockquote>
<blockquote> <b><a
 href="https://issues.apache.org/ooo/page.cgi?id=fields.html#priority">
Priority</a>: How much does the problem affect the product's <em>overall</em>
usefullness?</b><br>
Developers use this field as <em>one</em> measure how to priorize
their work.<br>
This item defaults to '3'. 1 is the highest (rarely used), 5 the lowest
priority.<br>
Please read the <a
 href="https://issues.apache.org/ooo/page.cgi?id=fields.html#priority">definition
of issue priorities</a> carefully before attempting to use P2 or even
P1.</blockquote>
<blockquote> <br>
  <i>Who will be following up on the issue?</i> </blockquote>
<blockquote> <b><a
 href="https://issues.apache.org/ooo/page.cgi?id=fields.html#assigned_to">
Assigned To</a>: Which engineer should be responsible for fixing this
issue?</b><br>
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.) </blockquote>
<blockquote> <b>Cc: Who else should receive e-mail updates on changes
to this issue?</b><br>
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. </blockquote>
<blockquote> <br>
  <i>What else can you tell the engineer about the issue? </i></blockquote>
<blockquote> <b>URL: On what URL did you discover this issue?</b><br>
If you encountered the issue on a particular URL, please provide it
(or, them) here. </blockquote>
<blockquote> <b>Summary:</b> <b>How would you describe the issue, in
approximately 60 or fewer characters?</b><br>
A good summary should <u>quickly and uniquely identify an issue report</u>.
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.<br>
  <br>
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. </blockquote>
<blockquote> <br>
  <b>Description: What else can you tell the engineer about this issue?</b><br>
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.<br>
For crashing issues it might help to have additional information in
case you're able to provide that:</blockquote>
<blockquote><br>
  <b><a href="https://issues.apache.org/ooo/page.cgi?id=fields.html#target_milestone">
Target Milestone</a>:</b> Think of it as a deadline; targets are "not
determined" or "next build"--for most issues, stipulate "not
determined."
  <ul>
  </ul>
  <p><strong>Attachments.</strong><em> </em>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: </p>
  <blockquote> Create a new attachment (proposed patch, testcase, etc.)</blockquote>
  <p> <strong>Note</strong>: You cannot add OpenOffice files
natively. They must be added as "binary" files. This is a temporary
problem. </p>
  <p> 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.
  </p>
  <p>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 Bugzilla database.<br>
  </p>
  <hr>
  <p>(These Bug Writing Guidelines were originally written for Mozilla
by <a href="mailto:eli@prometheus-music.com"> <b>Eli Goldberg</b></a>.
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 are welcome. In this case just
post your suggestions to the <a
 href="mailto:qa@openoffice.apache.org?subject=Bugzilla">dev@qa</a>
mailing list.) </p>
</blockquote>
</div>
</body>
</html>