htdocs/dev/trackers.html - third_party/expat - Git at Google

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