httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c...@hyperreal.org
Subject cvs commit: apache-devsite bugdb-policies.html index.html
Date Mon, 03 Aug 1998 14:48:28 GMT
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>&lt;apache-bugdb@apache.org&gt;</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>&gt;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>&lt;apbugs@apache.org&gt;</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>
  
  
  

Mime
View raw message