<html>
  <head>
    <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 IssueTracker?</h4>
    <p>IssueTracker, 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? IssueTracker is the place to submit 
      issue reports for software distributed by OpenOffice.org. This page gives an 
      overview of how IssueTracker works. Read the <a href="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="http://projects.openoffice.org/">
            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 IssueTracker 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 IssueTracker 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 IssueTracker 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. IssueTracker 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 IssueTracker accounts by default create issues which are <tt>UNCONFIRMED</tt>
    . Currently, on IssueTracker, 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 IssueTracker 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, IssueTracker 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 IssueTracker, 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>