Author: cmpilato
Date: Fri May 13 14:57:04 2011
New Revision: 1102775
URL: http://svn.apache.org/viewvc?rev=1102775&view=rev
Log:
* site/publish/docs/community-guide/issues.part.html
(milestones): New section describing how we interpret issue
milestones in our tracker.
(issue-triage): Minor tweaks to the process of triaging issues.
Modified:
subversion/site/publish/docs/community-guide/issues.part.html
Modified: subversion/site/publish/docs/community-guide/issues.part.html
URL:
http://svn.apache.org/viewvc/subversion/site/publish/docs/community-guide/issues.part.html?rev=1102775&r1=1102774&r2=1102775&view=diff
==============================================================================
--- subversion/site/publish/docs/community-guide/issues.part.html (original)
+++ subversion/site/publish/docs/community-guide/issues.part.html Fri May 13
14:57:04 2011
@@ -198,6 +198,128 @@ make the bug much more likely to get fix
</div> <!-- bugs-where -->
+<div class="h2" id="milestones">
+<h2>Milestone Management
+ <a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#milestones"
+ title="Link to this section">¶</a>
+</h2>
+
+<p>Issue tracker milestones are an important aspect of how the
+Subversion developers organize their efforts and communicate with each
+other and with the Subversion user base. With the exception of some
+milestones used primarily when doing high-level
+<a href="issue-triage">issue triage</a>, the project's issue tracker
+milestones tend to be named to reflect release version numbers and
+variations thereof. Milestones are used for slightly different
+purposes depending on the state of the issue, so it's important to
+understand those distinctions.</p>
+
+<div class="h3" id="milestones-open">
+<h3>Milestones for open issues
+ <a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#milestones-open"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>For open issues (those whose status is <tt>UNCONFIRMED</tt>,
+<tt>NEW</tt>, <tt>STARTED</tt> or <tt>REOPENED</tt>), the milestone
+indicates the Subversion release for which the developers are
+targeting the resolution of that issue. In the general case, we use
+milestones of the form <tt><em>VERSION</em>-consider</tt> to indicate
+that the resolution of an issue is being considered as something we'd
+like to release in <em>VERSION</em>. For example, a feature we think
+we can and should add to Subversion 1.9 will get
+a <tt>1.9-consider</tt> milestone. For obvious reasons, the accuracy
+of these release targets gets increasingly worse the farther into the
+future you look and, as such, users are encouraged to <em>not</em>
+treat them as binding promises from the developer community.</p>
+
+<p>At any given time, there is work toward "the next big release"
+happening in the community. As that release begins to take shape, the
+developers will get a better feel for which issues are "must-haves"
+for the release (also known as "release blockers"), which ones are
+"nice-to-haves", and which ones should be deferred to a future release
+altogether. Issue milestones are the mechanism used to carry the
+results of those decisions. An issue that is deemed to be a release
+blocker will be moved from the <tt><em>VERSION</em>-consider</tt>
+milestone to the <tt><em>VERSION</em></tt> milestone;
+"nice-to-haves" will be left with
+the <tt><em>VERSION</em>-consider</tt> milestone; and issues deferred
+from the release will be re-milestoned either
+with <tt><em>ANOTHERVERSION</em>-consider</tt>
+or <tt>unscheduled</tt>, depending on whether we have a clear guess as
+to when the issue will be addressed.</p>
+
+<p>Continuing the previous example, as development on Subversion
+1.9.0-to-be progresses, developers will be evaluating that feature we
+planned for the release. If we believe that Subversion 1.9 should not
+be released without that feature, we'll change its milestone
+from <tt>1.9-consider</tt> to <tt>1.9.0</tt>; if we hope to release
+with that feature but don't want to commit to it, we'll leave the
+milestone as <tt>1.9-consider</tt>; and if we know good and well we
+aren't going to get around to implementing the feature in the 1.9.x
+release series, we'll re-milestone the issue to something else
+(<tt>1.10-consider</tt>, perhaps).</p>
+
+<p>The accuracy of the <tt><em>VERSION</em></tt> milestone is very
+important, as developers tend to use those issues to focus their
+efforts in the final days of a major release cycle.</p>
+
+</div> <!-- milestones-open -->
+
+<div class="h3" id="milestones-fixed">
+<h3>Milestones for fixed issues
+ <a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#milestones-fixed"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>For fixed issues (those whose status is <tt>RESOLVED</tt> and the
+resolution is <tt>FIXED</tt>), the issue milestone takes on a new
+utility: tracking the Subvesion release version which first carries
+the resolution of that issue. Regardless of the targeted release
+version for a given issue, once it is resolved its milestone should
+reflect the exact version number of the release which will first carry
+that resolution.</p>
+
+</div> <!-- milestones-fixed -->
+
+<div class="h3" id="milestones-closed">
+<h3>Milestones for other closed issues
+ <a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#milestones-closed"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>For other closed issues (those which aren't "open" and weren't
+really "fixed"), the issue milestone tends to mean pretty much
+nothing. There's little point in trying to maintain that tracker
+field when the issue itself is being effectively ignored because it's
+a duplicate, or because it's an invalid or inaccurate report.</p>
+
+</div> <!-- milestones-closed -->
+
+<div class="h3" id="milestones-transitioning">
+<h3>Transitioning between states
+ <a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#milestones-transitioning"
+ title="Link to this section">¶</a>
+</h3>
+
+<p>Care must be taken when transitioning an issue between these
+states. An open issue that's been resolved needs to have its
+milestone adjusted to reflect the Subversion release which will first
+reflect that change. A resolved issue that gets backported to a
+previous release stream needs to have its milestone adjusted to point
+that previous release's version number. Finally, a resolved issue
+that gets <tt>REOPENED</tt> needs to have its milestone reevaluated in
+terms of whether the issue is a release blocker
+(<tt><em>VERSION</em></tt>) or not
+(<tt><em>VERSION</em>-consider</tt>). In such situations, it can be
+helpful to consult the issue's change history to see what milestone
+was used before the issue was resolved as fixed.</p>
+
+</div> <!-- milestones-transitioning -->
+
+</div> <!-- milestones -->
+
+
<div class="h2" id="issue-triage">
<h2>Issue triage
<a class="sectionlink" href="<!--#echo var="GUIDE_ISSUES_PAGE"
-->#issue-triage"
@@ -233,6 +355,8 @@ release, so urgent issues would go there
# did not follow the <a
href="http://subversion.tigris.org/issue-tracker.html#buddy-system";>"buddy
system"</a> for filing.
close_as_invalid(i)
elif issue_already_fixed(i):
+ version = fixed_in_release(i)
+ move_to_milestone(i, version)
close_as_fixed(i)
elif issue_unreproducible(i):
close_as_worksforme(i)
@@ -252,12 +376,12 @@ release, so urgent issues would go there
if issue_is_not_important_enough_to_block_any_particular_release(i):
move_to_milestone(i, "nonblocking")
elif issue_resolution_would_require_incompatible_changes(i):
- move_to_milestone(i, "2.0")
+ move_to_milestone(i, "2.0.0")
elif issue_hurts_people_somewhat(i):
- move_to_milestone(i, "1.6") # or whatever
+ move_to_milestone(i, "1.6-consider") # or whatever
elif issue_hurts_people_a_lot(i):
move_to_milestone(i, "1.5-consider")
- elif issue_hurts_and_hurts_and_won't_stop_hurting(i):
+ elif issue_hurts_and_hurts_and_should_block_the_release(i):
move_to_milestone(i, "1.5")
</pre>
