coar 98/08/03 07:48:28
Modified: . index.html
Added: . bugdb-policies.html
Log:
Add a rough draft of 'how to edit PRs,' and point to it.
Revision Changes Path
1.24 +6 -2 apache-devsite/index.html
Index: index.html
===================================================================
RCS file: /export/home/cvs/apache-devsite/index.html,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- index.html 1998/06/19 15:26:54 1.23
+++ index.html 1998/08/03 14:48:27 1.24
@@ -25,12 +25,16 @@
<H2>User Feedback</H2>
<UL TYPE="SQUARE">
<LI><A HREF="http://bugs.apache.org/";>User access</A> (submit and query)
- to the Apache Bug Report Database.
+ to the Apache Bug Report Database.
</LI>
<LI><A HREF="http://bugs.apache.org/private/";>Developer access</A>
(submit, query and edit) to the
database of Apache bug reports.
Requires authorisation.
+ <MENU>
+ <LI><A HREF="bugdb-policies.html">Guidelines</A> for editing PRs.
+ </LI>
+ </MENU>
</LI>
<LI>Information about the various Apache
<A HREF="mailing-lists.html">mailing lists</A>.
@@ -62,7 +66,7 @@
</LI>
<LI>Some notes on <A HREF="debugging.html">debugging</A>
<BR>
- (last modified on <!--#flastmod virtual="debugging.html" -->)
+ (last modified on <!--#flastmod virtual="debugging.html" -->)
</LI>
</UL>
1.1 apache-devsite/bugdb-policies.html
Index: bugdb-policies.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd";>
<HTML>
<HEAD>
<TITLE>Apache Bug Database Policies for Developers
</TITLE>
</HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active)
-->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Apache Bug Database Policies for Developers
</H1>
<P>
This document defines the rules and policies that govern the handling
of Apache problem reports (PRs).
</P>
<MENU>
<LI><A HREF="#principles">Underlying Principles</A>
</LI>
<LI><A HREF="#guidelines">General Guidelines</A>
</LI>
<LI><A HREF="#states">PR States</A>
<MENU>
<LI><A HREF="#open">open</A>
</LI>
<LI><A HREF="#analyzed">analyzed</A>
</LI>
<LI><A HREF="#feedback">feedback</A>
</LI>
<LI><A HREF="#suspended">suspended</A>
</LI>
<LI><A HREF="#closed">closed</A>
</LI>
<LI><A HREF="#transitions">PR State Transitions</A>
</LI>
</MENU>
</LI>
<LI><A HREF="#dates">Date Thresholds</A>
</LI>
<LI><A HREF="#outofband">Out-of-Band PR Information</A>
</LI>
</MENU>
<HR>
<H2><A NAME="principles">Underlying Principles</A>
</H2>
<P>
The single most critical resource we have is developer time. Anything
that can be done to reduce the amount of time developer's spend in
dealing with PRs, as opposed to actually developing or fixing problems,
is highly desirable. This means that it is reasonable to push back
on PR submitters to test fixes in their own environments rather than
have developers reproduce the environment locally. If a newer version
of the software has been released, it is reasonable to ask the submitter
to try upgrading -- even if it's not clear whether the relevant areas
of the code were touched. Submitters should almost <EM>always</EM>
be encouraged to run the latest version, at least to test whether
their issues have been addressed.
</P>
<P>
Obviously this is subject to case-by-case exceptions at the discretion
of individual developers, but the principle remains the basis for the
policies that follow.
</P>
<HR>
<H2><A NAME="guidelines">General Guidelines</A></H2>
<P>
Some general guidelines for developers working on problem reports:
</P>
<UL>
<LI><STRONG>Before working on a PR, check to see if anyone else has touched
it recently.</STRONG>
If so, contact the other developer first, since there may be
some out-of-band communication going on in private email and your
jumping in may confuse matters.
</LI>
<LI><STRONG>Don't change the ownership of PRs to yourself unless you intend
to <EM>really</EM> follow through unto closure.</STRONG>
The bugdb sends mail whenever PRs are modified; if the owner is
"<SAMP>apache</SAMP>" the mail will be sent to the
<SAMP><[EMAIL PROTECTED]></SAMP>
mailing list. If the owner is anyone else, mail is sent only to
the submitter and that person -- so change notices <STRONG>won't</STRONG>
be sent to the group.
</LI>
<LI><STRONG>Be sure to update a PR's state when mail from the submitter
gets attached to it.</STRONG>
When the bugdb system attaches mail messages, it doesn't change the
state or make any other changes to a PR. Since mail has been sent,
"feedback" is almost certainly not the correct state, so it
should be changed. See the <A HREF="#transitions">state transitions</A>
section for more information about the correct new state.
</LI>
</UL>
<HR>
<H2><A NAME="states">PR States</A>
</H2>
<P>
A problem report can be in any of the following states. The ones in which
most PRs should reside are: <STRONG>open</STRONG>,
<STRONG>feedback</STRONG>,
and <STRONG>closed</STRONG>. The "open" state implies that a PR needs
developer attention, so one of the main goals is to move PRs into
"feedback,"
"suspended," or "closed."
</P>
<H3><A NAME="open">open</A></H3>
<P>
New PRs start in this state. Being "open" indicates that a solution
is not yet known, or that no-one has looked at the problem yet. It
can also mean that someone was working on it but had to stop.
</P>
<H3><A NAME="analyzed">analyzed</A></H3>
<P>
If a PR is in the "analyzed" state, it means that someone has figured
out the cause of the issue (or thinks he has). A solution may or may
not have been found, but it hasn't been committed to a development stream
yet if it has. This is also the state into which a PR should be put
when requested feedback has been obtained from the submitter.
</P>
<H3><A NAME="feedback">feedback</A></H3>
<P>
The "feedback" state is where a lot of PRs spend their time. It indicates
that the submitter has been asked for more information or to try an
experiment. It will stay in this state until a response is made or the
PR 'times out' (see the section on <A HREF="#dates">date thresholds</A>).
</P>
<H3><A NAME="suspended">suspended</A></H3>
<P>
Simply put, reports that ask for new functionality or other changes that no
developer wants to work on at the moment, or that have been identified as
'non-goals' for the current development streams, get put into "suspended"
state as a means of saving them for later consideration.
</P>
<H3><A NAME="closed">closed</A></H3>
<P>
Closed PRs typically require no additional attention. It is possible,
though, for reports to be closed incorrectly or prematurely, so they
<EM>may</EM> occasionally migrate out of this state. Closed PRs are
the major component of the knowledge base distilled into the FAQ.
</P>
<HR>
<H3><A NAME="transitions">PR State Transitions</A></H3>
<P>
The following table describes the possible state transitions to which PRs
are subject, and explains some of the circumstances that can cause a
particular transition to be made. If you're not sure what the new
state should be for a PR you're handling, consult the table for some
guidelines.
</P>
<TABLE BORDER=1>
<TR VALIGN=BOTTOM ALIGN=CENTER>
<TD></TD>
<TH>open</TH>
<TH>analyzed</TH>
<TH>feedback</TH>
<TH>suspended</TH>
<TH>closed</TH>
</TR>
<TR VALIGN=TOP>
<TH VALIGN=CENTER>open</TH>
<TD><!-- open-open -->
</TD>
<TD><!-- open-analyzed -->
Either the submitter or a responding developer has determined what the
problem cause is.
</TD>
<TD><!-- open-feedback -->
A question has been posed to the submitter, such as asking for more
detail or requesting an experiment.
</TD>
<TD><!-- open-suspended -->
The PR describes a request for a change or functionality that is
reasonable or interesting, but isn't appropriate to the current
version under development, or to the current plans or work effort
available.
</TD>
<TD><!-- open-closed -->
The PR deals with a non-issue, one that has already been solved, or is
already being tracked. Or almost any case in which further attention
is inappropriate.
</TD>
</TR>
<TR VALIGN=TOP>
<TH VALIGN=CENTER>analyzed</TH>
<TD><!-- analyzed-open -->
It turns out that the analysis was incorrect and the cause really isn't
known after all.
</TD>
<TD><!-- analyzed-analyzed -->
</TD>
<TD><!-- analyzed-feedback -->
The submitter is being asked for more information or experimentation.
</TD>
<TD><!-- analyzed-suspended -->
The issue described by the PR should be deferred until some later
version.
</TD>
<TD><!-- analyzed-closed -->
The decision has been made to <STRONG>not</STRONG> address the PR,
possibly because the behaviour is not considered a bug. This usually
follows discussion amongst the developers.
</TD>
</TR>
<TR VALIGN=TOP>
<TH VALIGN=CENTER>feedback</TH>
<TD><!-- feedback-open -->
The requested information has been supplied by the submitter, but
doesn't really explain the behaviour. (It may be more appropriate to
move the PR to "analyzed" instead.)
</TD>
<TD><!-- feedback-analyzed -->
The response from the submitter has provided the necessary information
to determine the cause, if not the solution, of the issue.
</TD>
<TD><!-- feedback-feedback -->
</TD>
<TD><!-- feedback-suspended -->
Additional information from the submitter allows the determination to
be made that the issue should be addressed in some future version.
</TD>
<TD><!-- feedback-closed -->
<MENU>
<LI>Additional information supplied by the submitter has explained the
cause, and the solution is provided in the closure text.
</LI>
<LI>The PR has '<A HREF="#dates">timed out</A>' due to lack of response
from the submitter.
</LI>
</MENU>
</TD>
</TR>
<TR VALIGN=TOP>
<TH VALIGN=CENTER>suspended</TH>
<TD><!-- suspended-open -->
<MENU>
<LI>The time has come for the issue described by the PR to be considered
for inclusion in the project.
</LI>
<LI>The PR describes a genuine bug rather than a change or enhancement.
It may be more appropriate to move the PR to "analyzed" instead.
</LI>
</MENU>
</TD>
<TD><!-- suspended-analyzed -->
<MENU>
<LI>The time has come for the issue described by the PR to be considered
for inclusion in the project.
</LI>
<LI>The issue described by the PR is a genuine bug or problem, and the
circumstances are tolerably well understood.
</LI>
</MENU>
</TD>
<TD><!-- suspended-feedback -->
The PR's issue wasn't clearly understood, and it really is a bug
report. More information from the submitter has been requested.
(This typically follows <A HREF="#outofband">out-of-band email</A>
exchanges between the submitter and a developer.)
</TD>
<TD><!-- suspended-suspended -->
</TD>
<TD><!-- suspended-closed -->
The issue was discussed by the developers, and the decision was made
to not invest in the necessary effort. The PR submitter can, and perhaps
should, be encouraged to develop the solution personally and supply it
to the project for possible inclusion.
</TD>
</TR>
<TR VALIGN=TOP>
<TH VALIGN=CENTER>closed</TH>
<TD><!-- closed-open -->
The report was closed prematurely, probably due to insufficient detail
in the PR or perhaps because the developer didn't understand the
issue as described. It may be more appropriate for the PR to have
been moved to "analyzed" or "feedback" instead.
</TD>
<TD><!-- closed-analyzed -->
The PR was closed prematurely, but the issue is now clarified and
understood -- though not yet solved.
</TD>
<TD><!-- closed-feedback -->
The PR was closed prematurely, but additional information has been
requested from the submitter to investigate further.
</TD>
<TD><!-- closed-suspended -->
After closure, additional information has been supplied to make a case
for
future consideration of the issue.
</TD>
<TD><!-- closed-closed -->
</TD>
</TR>
</TABLE>
<HR>
<H2><A NAME="dates">Date Thresholds</A>
</H2>
<P>
In keeping with the principle of minimising the amount of time spent
on bugdb administrivia, the following thresholds may be used as guidelines
for dealing with PRs that aren't being actively worked.
</P>
<DIV ALIGN=CENTER>
<TABLE BORDER=1>
<TR>
<TH>State</TH>
<TH>Time Since Last Touched</TH>
<TH>PR Last Touched By</TH>
<TH>PR Condition</TH>
<TH>Available Actions</TH>
</TR>
<TR ALIGN=CENTER VALIGN=TOP>
<TD>analyzed</TD>
<TD>>30 days</TD>
<TD>N/A</TD>
<TD>N/A</TD>
<TD ALIGN=LEFT>Edit the PR (without changing state unless appropriate) to
let submitter know the issue is not forgotten.
</TD>
</TR>
<TR ALIGN=CENTER VALIGN=TOP>
<TD ROWSPAN=2>feedback</TD>
<TD ROWSPAN=2>14-30 days</TD>
<TD ROWSPAN=2>Developer</TD>
<TD ALIGN=LEFT>Last touch was a developer request for information or
experimentation
</TD>
<TD ALIGN=LEFT>Click on the "Query -- Outstanding Request" button.</TD>
</TR>
<TR ALIGN=CENTER VALIGN=TOP>
<!-- Col 1 spanned from above -->
<!-- Col 2 spanned from above -->
<!-- Col 3 spanned from above -->
<TD ALIGN=LEFT>Last touch was the "Query -- Outstanding request"
message
</TD>
<TD ALIGN=LEFT>Click on the "Close -- No response" button to close
the PR.
</TD>
</TR>
</TABLE>
</DIV>
<HR>
<H2><A NAME="outofband">Out-of-Band PR Information</A>
</H2>
<P>
In many cases, mail pertaining to the original PR may be exchanged between
the submitter and one or more developers. In this case, the developer(s)
should make sure relevant portions are attached to the PR by forwarding
them to the <SAMP><[EMAIL PROTECTED]></SAMP> address with the
appropriate <SAMP>Subject:</SAMP> line.
</P>
<BLOCKQUOTE>
<STRONG>
If you mail information to the bugdb in order to attach it to an existing
PR, <EM>don't</EM> quote excessively! Remember that anyone reading the
PR will see all attachments in chronological order, and excessive
quoting not only takes up space unnecessarily, but also makes the
report harder to read.
</STRONG>
</BLOCKQUOTE>
<P>
When additional information is sent to the bugdb through email, do
<STRONG>not</STRONG> use MIME attachments or forwarding! The bugdb
is not MIME-aware, and so the attachments will probably look ugly.
</P>
<P>
"Out-of-band" also refers to information that gets attached to
PRs though the email mechanism rather than the Web form. When the
bugdb processes such messages, it <STRONG>does not</STRONG> change the
PR state, so it needs to be changed manually.
</P>
</BODY>
</HTML>
