content/bugs/issues.html

<!DOCTYPE html>
<html><head>
<title>Got Issues? (Last updated 2002-06-03)</title>
<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
</head>
<body>

  
    <h2>Got Issues?</h2>

      
<p><i>Last updated 2002-06-03</i></p>
<br>
    
    
<h4>Why &quot;Issues&quot; And Not &quot;Bugs&quot;?</h4>
    
    <p>Not all 'issues' are DEFECTS, which are more commonly known as
    &quot;bugs.&quot; Some issues will be <i>FEATURE Requests</i> or
    <i>ENHANCEMENT Requests</i>, <i>PATCH submissions</i>, or even
    <i>TASKS</i>.  For this reason, we feel the term &quot;issue&quot; is a
    more appropriate one than &quot;bug&quot;. People often say 'bug' when
    they should really be referring to an issue. Enter the tasks you're
    planning to work on as enhancement requests and will help you track
    them and allow others to see what you plan to work on. If people can
    see your flight plan, they can avoid duplicating your work and can
    possibly help out or offer feedback
    </p>
<br>
    <h4>What Is IssueZilla?</h4>

    <p>IssueZilla, a proprietary tool, is based on Mozilla's open-source <a
    href="http://www.mozilla.org/bugs/">Bugzilla</a>, but has been
    generalized by <a href="http://www.collab.net">CollabNet</a> to handle all kinds of issues, not just code-based
    issues. On OpenOffice.org, the supported issue-types now include:
    DEFECT, ENHANCEMENT, FEATURE, TASK and PATCH. We can add issue types in
    the future as necessary, and these can be reported against specific
    components of a project, for example 'documentation', 'code', 'ui',
    'definition'. OpenOffice.org's projects are 'api', 'chart', 'database
    access', 'drawing', 'formula editor', 'presentation', 'spreadsheet',
    'word processor' and 'xml' to name just a few. Take a look at the
    projects/products list to see all of them.
    </p>

    <p>Reported issues will be assigned to an appropriate issue owner.</p>
<br>
    <h4>What do you have an issue with?</h4>

    <p>Do you want to report an issue with a milestone build or with a copy
    of OpenOffice.org that you compiled yourself? IssueZilla is the place
    to submit issue reports for software distributed by
    OpenOffice.org. This page gives an overview of how IssueZilla works.
    Read the <a
    href="//bugs/bug_writing_guidelines.html">issue
    writing guidelines</a> as well, for tips on how to write useful issue
    reports.
    </p>
<br>
    <h4>Anatomy Of An Issue</h4>

    <p>Issues are composed of many fields. Some of them are described here.
    </p>

    <blockquote>
    <dl>
      <dt><b>Project</b></dt>

      <dd>
	OpenOffice.org is composed of different projects. Carefully
	read the <a
	href="/projects/">project
	descriptions</a> if you're unsure of which project to attribute
	your issue to (visit the projects themselves for fuller descriptions). The project you choose determines which person
	IssueZilla assigns the issue to.
      </dd>

      <dt><b>Status Whiteboard</b></dt>

      <dd>
	The Status Whiteboard is used for writing short notes about the
	issue.
      </dd>

      <dt><b>Keywords</b></dt>

      <dd>
	This field is used to store various keywords.
      </dd>

      <dt>
	<b>Special 'helpwanted' keyword and TASK issue-type</b>
      </dt>

      <dd>
	Developers can post <tt>helpwanted</tt> notices, and IssueZilla can
	help match-make other developers and apprentices who wish to help
	out with a TASK. Developers should Write <tt>helpwanted</tt> in the
	Keywords field of an issues, perhaps changing the issue-type of the
	defect or enhancement to 'TASK'. Others searching for things to do
	will find it and even accept the issue or TASK. People interested
	in getting involved can search IssueZilla for issues and
	ENHANCEMENTs marked <tt>helpwanted</tt>. Maybe one of them will
	have the expertise and resources to help you with your problem.
      </dd>

      <dd>
	Developers can use the TASK issue-type for project-work they'd like
	to delegate. For instance, if your code has a issue on some
	platform which you don't have access to, or with some language you
	don't know, try adding this keyword. A developer can of course
	change an uncompleted TASK back to DEFECT, ENHANCEMENT or FEATURE
	(whatever the issue was before it became a TASK again). This could
	happen, for instance, when the initial issue owner decides nobody
	is willing to help out with a task.
      </dd>

      <dd>
	Or, as with any developer, you're probably swamped with
	issues. Some of these issues will be lower priority than
	others. Try marking issues that you realize you won't be able to
	any time soon as <tt>helpwanted</tt>. Someone else with different
	priorities may see this and help you out.
      </dd>

      <dd>
	When marking issues <tt>helpwanted</tt>, be sure to add a comment
	carefully explaining what work needs to be done, and how to do it,
	if you know. The better you can explain the problem and its
	solution, the more likely it is that someone can provide a useful
	solution.
      </dd>

      <dt><b>Dependency</b></dt>

      <dd>
	If an issue can't be fixed until another issue is fixed, that's a
	dependency. For any issue, you can list the issues it depends on and
	issues that depend on it. IssueZilla can display a dependency graphs
	which shows which the issues it depends on and are dependent
	dependent on it. 
      </dd>

      <dt><b>Attachment</b></dt>

      <dd>
	Adding an attachment to an issue can be very useful. Test cases and
	screen shots can help pinpoint the issue and help the developer
	reproduce it.
      </dd>

      <dt><b>Special patch-file 'Attachment' and PATCH issue-type</b></dt>

      <dd>
	If you've already fixed a defect or done an enhancement, you should
	report an issue of type PATCH, and attach the patch-file to the
	issue. This is the preferred way to keep track of patches since it
	makes it easier for others to find and test. To make a patch, you
	need to generate a diff file containing the differences between the
	file with your changes and the original file in the repository. To
	generate a patch file enumerating changes for all files in the
	current directory try:
	<pre style="margin-left: 0.78in; margin-right: 0.39in; margin-bottom: 0.2in">cvs diff -u &gt; mypatch.diff</pre>
	To apply a patch, go to the proper directory and do:
	<pre style="margin-left: 0.78in; margin-right: 0.39in; margin-bottom: 0.2in">patch &lt; issuepatch.diff</pre>
      </dd>
    </dl>
    </blockquote>

    <h4>Life Cycle Of An Issue</h4>

    <p>What happens to an issue when it is first reported depends on who
    reported it. New IssueZilla accounts by default create issues which are
    <tt>UNCONFIRMED</tt>.
    Currently, on IssueZilla, the quality assurance is done by
    a list of users subscribed to a &quot;virtual user&quot;
    issues@&lt;project&gt;.openoffice.org.
    <p>
    You then use your regular IssueZilla account to
    login, then view, then further &quot;workflow&quot; the issue.
    <br>
    <P><A NAME="emailreply"></A>
    With default settings for your account you will be notified of 
    any change made to the issue. Please do not reply via email to
    notification messages. The proper way to comment is to login and use the
    web based frontend. By sending mail to
    issues-subscribe@&lt;project&gt;.openoffice.org, you can be notified of
    all changes in bugs of this project.
    </p>

    <p>If you are a registered OpenOffice.org user, you
    can create <tt>UNCONFIRMED</tt> issues.
    When an issue is confirmed and becomes <tt>NEW</tt>, the
    developer will probably look at the issue and either accept it or give
    it to someone else. If the issue remains new and inactive for more than
    a week, IssueZilla nags the issue's owner with email until action is
    taken. Whenever an issue is reassigned or has its component changed,
    its status is set back to <tt>NEW</tt>. The <tt>NEW</tt> status means
    that the issue is newly added to a particular developer's plate, not
    that the issue is newly reported. Think of &quot;NEW&quot; as an
    important e-mail you need to answer, except, you answer in IssueZilla,
    and you can use the tool to better track its progress than e-mail.
    </p>

    <p>Those to whom additional permissions have been given have the
    ability to change all the fields of an issue (by default, you can only
    change a few). Whenever you change a field in an issue its a good idea
    to add additional comments to explain what you are doing and why. Make
    a note whenever you do things like change the component, reassign the
    issue, create an attachment, add a dependency or add someone to the CC
    list. Whenever someone makes a change to the issue or adds a comment,
    they are added to the CC list and the owner, reporter and the CC list
    are sent an email showing the changes to the issue report.
    </p>

    <p>When a issue is fixed it's marked <tt>RESOLVED</tt> and given one of
    the following resolutions.
    </p>

    <blockquote>
    <dl>
      <dt><b>FIXED</b></dt>

      <dd>
	A fix for this issue has been checked into the tree and tested by
	the person marking it <tt>FIXED</tt>. 
      </dd>

      <dt><b>INVALID</b></dt>

      <dd>
	The problem described is not a issue, or not a issue in
	OpenOffice.org. 
      </dd>

      <dt><b>WONTFIX</b></dt>

      <dd>
	The problem described is a issue which will never be fixed.
      </dd>

      <dt><b>LATER</b></dt>

      <dd>
	The problem described is a issue which will not be fixed in this
	version of the product.
      </dd>

      <dt><b>REMIND</b></dt>

      <dd>
	The problem described is a issue which will probably not be fixed
	in this version of the product, but might still be.
      </dd>

      <dt><b>DUPLICATE</b></dt>

      <dd>
	The problem is a duplicate of an existing issue. Marking a issue
	duplicate requires the issue number of the duplicating issue and
	will add a comment with the issue number into the description field
	of the issue it is a duplicate of.
      </dd>

      <dt><b>WORKSFORME</b></dt>

      <dd>
	All attempts at reproducing this issue were futile. If more
	information appears later, please re-assign the issue, for now,
	file it.
      </dd>

      <dt><b>MOVED</b></dt>

      <dd>
	The issue was specific to a particular OpenOffice.org-based
	distribution and didn't affect OpenOffice.org code. One such
	scenario are defects reported against Sun's product version of
	OpenOffice.org. The issue was moved to the bug database of the
	distributor of the affected OpenOffice.org derivative.
      </dd>
  </dl>
  </blockquote>

    <p>
      QA looks at resolved issues and to make sure the appropriate action
      has been taken. If they agreee, the issue is marked
      <tt>VERIFIED</tt>.  Issues remain in this state until the product
      ships, at which time the issue is marked <tt>CLOSED</tt>. issues may
      come back to life by becoming <tt>REOPENED</tt>.
    </p>
    <p>Be careful when changing the status of someone else's issues.
      Instead of making the change yourself, its usually best to make a
      note of your proposed change as a comment and to let the issue's
      owner review this and make the change themselves. For instance, if
      you think one issue is a duplicate of another, make a note of it in
      the <i>Additional Comments</i> section. 
    </p>
    <p>If you make a lot of useful comments to someone's issues they may
      come to trust your judgement and ask you to go ahead and make the
      changes yourself, but unless they do, its best to be cautious and
      only make comments. 
    </p>
    
</body>
</html>