| <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 & 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> |