<html>
  <head>
    <title>SourceForge Tracker Usage</title>
    <link rel="STYLESHEET" href="../style.css" type="text/css" />
  </head>
  <body marginwidth="0" marginheight="0">
    <table cellspacing="0" cellpadding="0" width="100%">
      <tr>
        <td class="corner"><a href="../"><img src="../expat.png"
                                              border="0"/></a></td>
        <td class="banner"><h2>SourceForge Tracker Usage</h2></td>
      </tr>
      <tr>
        <td class="navbar">
        </td>
        <td class="content">

<p>This document describes the use of the SourceForge bug &amp; patch
trackers by the Expat maintainers.  These guidelines are substantially
based on the <a href="http://www.python.org/dev/devfaq.html#a1"
>guidelines used for Python</a>.</p>

<h3>Tracker Item Priority</h3>

<p>The priority field is simple enough; the higher the priority a
report is, the more important it is that the report needs to be
handled.  Note that it is the priority of the report relative to other
reports; it does not mean action needs to be taken on the software;
it may be that a report takes a high priority because the bug it
describes is very damaging for someone.  Review may, however,
determine that the bug is in someone else's code.</p>

<p>So, how should priority be assigned?  SourceForge assigns all new
reports a priority of "5", which is considered "normal".  The follow
list shows the meanings of each priority level as used by the Expat
project.</p>

<ol>
  <li value="9"> Needs to be solved <em>immediately</em>.  We
  shouldn't need this since we're volunteers, but it's Ok to use this
  if it's assigned to yourself and you have some external reason to
  deal with it immediately. </li>

  <li value="8"> Needs to be dealt with sooner rather than later, and
  is before priority "7" reports. </li>

  <li value="7"> Needs to be handled before release.  No release can
  be made so long as any report with priority "7" or higher is in any
  of the trackers we use. </li>

  <li value="6"> More important than most reports, but won't cause a
  release to be held up. </li>

  <li value="5"> Most reports.  This is how reports are created by
  default. </li>

  <li value="4"> Reports with priority "4" and lower typically wait a
  long time to be closed, or they're closed fairly quickly because
  they're really easy to close. </li>
</ol>

<h3>The Status and Resolution Fields</h3>

<p>In general, the Resolution and Status fields should be close to
self-explanatory, and the "Assigned to:" field should be the person
responsible for taking the next step in the patch process.  Both
fields are expected to change value over the life of a patch; the
normal workflow is detailed below.</p>

<p>When you've got the time and the ability, feel free to move any
patch that catches your eye along, whether or not it's been assigned
to you.  And if you're assigned to a patch but aren't going to take
reasonably quick action (for whatever reason), please assign it to
someone else or unassign it ASAP: at those times you can't actively
help, actively get out of the way.</p>

<p>If you're an expert in some area and know that a patch in that area
is both needed and non-controversial, just commit your changes
directly -- no need then to get the patch mechanism involved in
it.</p>

<p>The actual patch status is given by the pair of fields called
"Status" and "Resolution":</p>

<table>
  <thead>
  <tr><th>Status</th>
      <th>Resolution</th>
      <th>Meaning</th></tr>
  </thead>
  <tbody>
  <tr><td>Open</td>
      <td>None</td>
      <td>The initial state of all patches.

          <p>The patch is under consideration, but has not been
          reviewed yet, or is under review but not yet Accepted or
          Rejected.</p>

          <p>The Resolution will normally change to Accepted or
          Rejected next.</p>

          <p>The person submitting the report should (if they have
          permission) assign it to the person they most want to review
          it, else the patch will be assigned based on the judgement
          of the reviewer.</p>

          <p>Discussion of major patches is carried out on the <a
            href="http://mail.libexpat.org/mailman-21/listinfo/expat-discuss/"
          >expat-discuss</a> mailing list.  For simple patches, the
          SourceForge comment mechanism should be sufficient.</p>

          <p>For the reviewer:  If you're certain the patch should be
          applied, change the Resolution to Accepted and assign it
          back to the submitter for checkin if they are a developer on
          the project (if they aren't, the reviewer should commit it
          and change Resolution to Accepted and Status to Closed).  If
          you're certain the patch should never be
          accepted, change the Resolution to Rejected, Status to
          Closed, and write an explanation in the comment box.  If you
          have specific complaints that would cause you to change your
          mind if addressed, explain them clearly in a comment, leave
          the status Open, and reassign back to the submitter (again,
          if they're a developer on the project).  If you're
          uncertain, leave the status Open, explain your uncertainies
          in a comment, and reassign the patch to someone you believe
          can address your remaining questions; or leave the status
          Open and bring it up on <a
            href="http://mail.libexpat.org/mailman-21/listinfo/expat-discuss/"
          >expat-discuss</a>.</p></td></tr>

  <tr><td>Open</td>
      <td>Accepted</td>
      <td>The patch has been accepted, but it hasn't been applied
      yet.
      <p>The Status will normally change to Closed next.</p>
      <p>The person changing the Resolution to Accepted should, at the
      same time, assign the patch to whoever they believe is most
      likely to be able and willing to apply it (the submitter if
      possible).</p></td></tr>

  <tr><td>Closed</td>
      <td>Accepted</td>
      <td>The patch has been accepted and applied.
      <p>The previous Resolution was Accepted or None (if the
      reviewer checked it in).</p></td></tr>

  <tr><td>Closed</td>
      <td>Rejected</td>
      <td>The patch has been reviewed and rejected.
      <p>There are generally no transitions out of this state: the
      patch is dead.</p></td></tr>

  <tr><td>Open</td>
      <td>Out of date</td>
      <td>Previous Resolution was Accepted or Postponed, but the patch
      no longer works.
      <p>Please enter a comment when changing the Resolution to "Out
      of date", to record the nature of the problem and the previous
      state.</p>
      <p>Also assign it back to the submitter, as they need to upload
      a new version.</p></td></tr>

  <tr><td>Open</td>
      <td>Postponed</td>
      <td>The previous Resolution was None or Accepted, but for some
      reason (e.g., pending release) the patch should not be reviewed
      or applied until further notice.
      <p>The Resolution will normally change to None or Accepted next,
      which should be done as soon after the relevant event (release,
      etc.) as possible.  Checking for Postponed reports should be
      part of the release process.</p>
      <p>Please enter a comment when changing the Resolution to
      Postponed, to record the reason, the previous Resolution, and
      the conditions under which the patch should revert to Resolution
      None or Accepted.</p></td></tr>

  <tr><td>Deleted</td>
      <td>Any</td>
      <td>Bit bucket.
      <p>Use only if it's OK for the patch and its SourceForge history
      to disappear.  As of 13-June-2002, SourceForge does not actually
      throw away Deleted patches, but that may change.</p></td></tr>
  </tbody>
</table>

<h3>SourceForge Tracker Quirks</h3>

<p>The SourceForge trackers, though quite nice to work with for
moderate sized projects, do have some quirks and limitations.  Most of
the funcional limitations are unlikely to affect small projects like
Expat, but the quirky behavior... well, we should be aware of it.</p>

<dl>
  <dt> Who is "Nobody"? </dt>
  <dd> That depends on who initially submitted the report.

       <p>The most important thing to know is that SourceForge asks
       reporters who are not logged in to provide an email address,
       but does not require it.  There is no way to determine whether
       "Nobody" provided one.</p>

       <p>There are at least two common instances of "Nobody".  The
       simple interpretation of "Nobody" (and probably the most common
       case) is that the reporter did not log into SourceForge and did
       not provide an email address.  Sometimes a name or email
       address will be included in the initial report or a followup;
       it is not always the reporters intention to remain anonymous.
       If an email address is available this way, it is a good idea to
       send an email to the provided address when following up to a
       report, allowing the reporter to learn of the response and
       provide additional feedback or information.</p>

       <p>The second common case is that the report was filed by
       someone without a SourceForge login or who wanted to remain
       anonymous for some reason, but provided an email address to
       SourceForge so that they would be automatically notified of any
       followup activity.  In this case, requests for additional
       information in followup comments can actually get results,
       sometimes including an email address if the anonymous filing
       was not designed to protect anonymity but simply to avoid going
       through the SourceForge login screen.</p>

       <blockquote>
         <em>
         It's good to know that when filing a report while not logged
         in, clicking on the "Please log in!" link beneath the large
         text box will take you to a login page that will return you
         to your submission form.  Contents of the submission form
         will be lost, unfortunately, but that link can save a bit of
         navigating if you remember it soon enough.
         </em>
       </blockquote>

      <p>SourceForge also provides a feature allowing authenticated
      users to "monitor" a tracker report.  Clicking on the "Monitor"
      button will cause SourceForge to send the user an email on each
      change to the report in much the way it sends an email to the
      current assignee or the address configured in the tracker admin
      for new or modified items.  (For Expat, this would be the <a
      href="http://mail.libexpat.org/mailman-21/listinfo/expat-bugs/"
      >expat-bugs</a> list.)  Users who are monitoring a report are
      often knowledgable enough to answer questions about whatever the
      problem is.</p>

      <p>So, the "Nobody" listed as the submitter doesn't tell us
      much, except that we might not get to know who the submitter
      is.</p>

  </dd>
</dl>

        </td>
      </tr>
      <tr>
        <td class="corner">
          <a href="http://sourceforge.net/"> 
            <img src="http://cvs.sourceforge.net/sourceforge_whitebg.gif"
                 width="136" height="79" border="0" alt="SourceForge
                 Logo" />
          </a>
        </td>
      </tr>
    </table>
  </body>
</html>