[Expat-checkins] htdocs/dev index.html,1.3,1.4 trackers.html,1.2,1.3
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Thu Jun 13 13:42:03 2002
Update of /cvsroot/expat/htdocs/dev
In directory usw-pr-cvs1:/tmp/cvs-serv18678
Modified Files:
index.html trackers.html
Log Message:
Add some information about tracker usage, including both recommendations and
just useful information that is not always well known, but should be.
Index: index.html
===================================================================
RCS file: /cvsroot/expat/htdocs/dev/index.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- index.html 13 Jun 2002 18:34:14 -0000 1.3
+++ index.html 13 Jun 2002 20:41:24 -0000 1.4
@@ -24,11 +24,9 @@
<p />
<li> <a href="cvs.html">CVS instructions</a> for developers and
occasional contributors. </li>
- <!--
<p />
<li> <a href="trackers.html">Guidelines</a> for using the
SourceForge bug & patch trackers. </li>
- -->
</ul>
</td>
Index: trackers.html
===================================================================
RCS file: /cvsroot/expat/htdocs/dev/trackers.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- trackers.html 5 Jun 2002 04:01:10 -0000 1.2
+++ trackers.html 13 Jun 2002 20:41:24 -0000 1.3
@@ -16,9 +16,239 @@
<td class="content">
<p>This document describes the use of the SourceForge bug & patch
-trackers by the Expat maintainers.</p>
+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>
-<p>Or rather, it will once I find time to write it up.</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://sourceforge.net/mail/?group_id=10127"
+ >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://sourceforge.net/mail/?group_id=10127"
+ >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 & 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> <strong>Who is "Nobody"?</strong> </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://sourceforge.net/mail/?group_id=10127"
+ >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>