<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type"
 content="text/html; charset=ISO-8859-1">
  <title>Basic IssueTracker rules</title>
</head>
<body>
<div class="app">
<h1>Basic Bugzilla rules</h1>
<h3>Why you should read this</h3>
<p> Imagine how many people later on will read your issue (means the
issue which you submitted, or which you participated in) </p>
<ul>
  <li> community members who performe triage on defects</li>
  <li> developers who finally fix the defect </li>
  <li> sometimes developers who need to do preliminary work</li>
  <li> QA engineer(s) who needs to verify the fix</li>
  <li> everybody who has the same problem and tries to understand
whether </li>
  <ul>
    <li> <span style="font-style: italic;">your</span> defect also
describes <span style="font-style: italic;">his/her</span> problem.</li>
    <li> or whether your issue is one they like to vote for</li>
  </ul>
  <li> possibly a user experience team member evaluating a feature
request</li>
  <li> possibly a release team member evaluating whether the defect is
important enough to be included in some maintenance update such as
1.1.1.</li>
</ul>
You see, there are a lot of&nbsp; people who may read what you wrote.
Thus, the majority of the rules below focuses on making <span
 style="font-style: italic;">reading</span> easier: Though they
sometimes take you some little time to follow, they often save others a
<span style="font-style: italic;">lot</span> of time later on.
<p> So please, not only when you submit new issues, but also when you
add comments to existing issues, try to help others by obeying these
simple rules.<br/>
Since not obeying them makes defect handling more difficult (sometimes <span
 style="font-style: italic;">much</span> more difficult), people may
tend to not deal with your issues until they are in a shape to
reasonably do so. </p>
<h3>The rules</h3>
<p> For those of you who like it short and simple: </p>
<ul>
  <li style="font-weight: bold;"> <a href="#one_per_issue">One problem - One issue</a></li>
  <li style="font-weight: bold;"> <a href="#summary">Provide a meaningful summary</a></li>
  <li style="font-weight: bold;"> <a href="#reproducibility">Provide step-by-step descriptions</a></li>
  <li style="font-weight: bold;"> <a href="#bugdoc">Provide sample documents, if possible</a></li>
  <li style="font-weight: bold;"> <a href="#attachments">Use Attachments where possible</a></li>
  <li style="font-weight: bold;"> <a href="#complete">Put all relevant information into the issue</a></li>

</ul>
<h4><a name="one_per_issue"></a>One problem - One issue</h4>
<p> When you report a problem, please submit <span
 style="text-decoration: underline;">one issue per problem</span>.
There are various reasons for this, amongst them: </p>
<ul>
  <li> The more crowded an issue is, the more likely is it that some
problems may get lost over time.</li>
  <li> Different problems are most likely to be handled by different
people (both in engineering, where the problem is fixed, and in QA,
where it's verified). The more problems you put into the issue, the
more difficult is this issue to handle for all involved parties.</li>
</ul>
In particular, if you're going to write sentences like "Besides this, I
noticed that ...." or "There are several problems with....", then
please seriously ask yourself whether you should submit multiple issues
instead of a single one.<br/>
If you don't follow this rule, be prepared for people asking you to
split up your issue.
<h4><a name="summary"></a>Provide a meaningful summary</h4>
<p> A lot of people have to deal with a high number of issues on a
regular basis. Usually, this happens with generating reports about
issues, where the summary of all issues, plus some additional data, is
displayed. Thus, the summary of an issue is of very high importance: If
properly chosen, it allows to<br/>
</p>
<ul>
  <li> easily <span style="text-decoration: underline;">recognize</span>
an issue in a list of dozens of others</li>
  <li> <span style="text-decoration: underline;">find</span> an issue.
Since duplicate issues are draining a lot of work from engaged
community members, we always ask people to look whether the problem,
which they are going to submit as issue, is already known and reported.
Of course this works best if the summaries of the existing issues are
as descriptive as possible.</li>
  <li> <span style="text-decoration: underline;">judge the importance</span>
of an issue. "Spreadsheet problem" is less likely to be handled
appropriately than "Spreadsheet: Data loss when ...." or "Label X in
dialog Y has a wrong offset (2 pixels)"</li>
</ul>
Thus, please avoid summaries like "Big Bug in OpenOffice" or
"Impress problem" - they are of no real help, and force people to waste
time to actually browse to the issue (instead of seeing it in a report)
to see what it is about.<br/>
<h4><a name="reproducibility"></a>Provide step-by-step descriptions</h4>
<p> You, as the submitter of a problem, know exactly what you were
doing when you were hit by the problem. However, most other people
probably don't. For instance, they may have a completely different
workflow for doing the same things you are doing. </p>
<p> Even an phrasing as innocent as "format the text as bold" bears the
potential for a misunderstanding: You can get a bold text by assigning
a style to it, by selecting it and pressing the respective button in
the toolbox, by choosing "<span style="font-family: monospace;">Style|Bold</span>"
from the context menu, by choosing "<span
 style="font-family: monospace;">Format|Character</span>" from the menu
or "<span style="font-family: monospace;">Character</span>" from the
context menu and then doing the change in the dialog. Thus, a problem
description such as "When I try to format the text as bold
OpenOffice.org crashes" is of nearly no use, since it <span
 style="font-style: italic;">forces</span> other people to ask back
what you meant. </p>
<p> This may be a trivial example, and you could argue that other
people can simply try, and then they will eventually encounter the
problem and thus know what you meant. But, there are reasons against
this:<br/>
</p>
<ul>
  <li> Though the problem may seem simple to you, there may be deeper
reasons which prevent others from trying. For instance, it may crash
only if you customized the "<span style="font-family: monospace;">Bold</span>"
icon into a non-standard toolbox. In such a case, people will try for
no avail, without encountering your problem at all, and thus waste time.<br/>
  </li>
  <li> Writing down <span style="font-style: italic;">exactly</span>
what you did costs you some time <span style="font-style: italic;">once</span>,
but <span style="font-style: italic;">every</span> reader (there may
be numerous during the lifetime of an issue!) needs time for guessing
and trying. It's more efficient if you do it, and QA and engineering
can concentrate on fixing the problem, instead of performing triage on it.</li>
  <li> There are a lot of scenarios where the set of possibility is
much larger. Formatting a text as bold may be simple and easy (though
you've already seen that there are at least 5 ways to do so), but other
tasks may require more steps which <span style="font-style: italic;">you</span>
implicitly know, but <span style="font-style: italic;">your reader</span>
doesn't.</li>
</ul>
You may be tempted to consider it stupid to write a description like<br/>
<ul>
  <li> open a new writer document</li>
  <li> enter some arbitrary text</li>
  <li> select the whole text via "<span style="font-family: monospace;">Edit|Select
all</span>"</li>
  <li> from the context menu of the text, chose "<span
 style="font-family: monospace;">Style|Bold</span>"</li>
  <li> =&gt; OpenOffice crashes</li>
</ul>
Indeed there may be cases where this level of detail is
superfluous. But believe us, more often than not, it in the final
consequences saves more time than it takes.
<p> Please always be aware that often enough, the reader of your issue
description does not have the same background, with respect to the
particular task you're doing, that you yourself have. </p>
<h4><a name="bugdoc"></a>Provide sample documents, if possible</h4>
<p> If there is a problem with a particular document, then attach it.
This most often allows people to really easily reproduce your problem
by simply opening the attached document.<br/>
</p>
<p> If the description how to reproduce a defect (see <a
 href="#reproducibility">Provide step-by-step descriptions</a>) exceeds
a certain limit, ask yourself whether you can submit the <span
 style="font-style: italic;">result</span> of the description as sample
document, and attach it to the issue.<br/>
</p>
<p> Oh, and one thing: If there is a problem on page 3 of your
1000-page diploma thesis, then please first try if the problem also
occurs if you strip all pages except the third one. If so, then please
simply attach the stripped version of the document, not all 1000 pages
.... </p>

<h4><a name="attachments"></a>Use attachments where possible</h4>
<p> Don't paste large files into the description. For instance, if
you're asked to provide a stack of a crash, copy this stack into a
file, then <span style="text-decoration: underline;">attach</span>
this file. If you have some Basic macro or Java code which triggers a
problem, copy it into a separate file, and <span
 style="text-decoration: underline;">attach</span> this file. </p>
<p> The reason here is simple: A 3-pager within the description of an
issue makes reading the issue really difficult. Everybody who wants to
get an impression of the issue needs to scan through a lot of
information which, though definitely important, is of only peripheral
interest for them at the moment. </p>

<h4><a name="complete"></a>Put all relevant information into the issue</h4>
<p>Don't use (only) links to refer to the bug descriptions. Links tend to become outdated
over time, so if half a year later, somebody looks at your issue, it has become meaningless.
</p>

<p>If there is some external resource describing your problem - fine, link it! But don't rely
on links as the <em>only</em> mean for bug descriptions - copy the information which is
necessary to reproduce the problem into the issue.</p>

<hr/>
The author of the original document is <a
 href="mailto:fs@openoffice.org">Frank Sch&ouml;nheit</a>. Constructive
<a href="mailto:fs@openoffice.org">feedback is welcome</a>. You may
also consider visiting <a href="mailto:qa@openoffice.apache.org"> the
mailing list</a> dedicated to discussing issue handling.
<hr/>
<div> </div>
</div>
</body>
</html>