coar 98/09/28 07:49:47
Modified: . bugdb-policies.html
Log:
Add descriptions of the various editing fields and how to use them.
Revision Changes Path
1.3 +186 -6 apache-devsite/bugdb-policies.html
Index: bugdb-policies.html
===================================================================
RCS file: /export/home/cvs/apache-devsite/bugdb-policies.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- bugdb-policies.html 1998/08/07 09:16:49 1.2
+++ bugdb-policies.html 1998/09/28 14:49:46 1.3
@@ -7,7 +7,7 @@
<STYLE TYPE="text/css">
<!--
TD { font-size: smaller }
- -->
+ // -->
</STYLE>
</HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active)
-->
@@ -30,6 +30,8 @@
</LI>
<LI><A HREF="#guidelines">General Guidelines</A>
</LI>
+ <LI><A HREF="#fields">PR Fields</A>
+ </LI>
<LI><A HREF="#states">PR States</A>
<MENU>
<LI><A HREF="#open">open</A>
@@ -103,6 +105,184 @@
</LI>
</UL>
<HR>
+ <H2><A NAME="fields">PR Fields</A></H2>
+ <P>
+ The PR editing form has a number of different fields on it. Some are
+ pull-down lists, some are free-form text boxes, and some are buttons or
+ checkboxes. Here's a description of what they are and how to use
+ them.
+ </P>
+ <P>
+ <STRONG>When filling in free-form text boxes, use the Enter or Return
+ key to insert hard newlines in order to keep the line-length short!
+ Try to keep the horizintal scrollbar inactive.</STRONG>
+ </P>
+ <DL COMPACT>
+ <DT><SAMP>DO NOT send mail about this change</SAMP>
+ </DT>
+ <DD>
+ <P>
+ Just as you might expect, this controls whether the update to the
+ bugdb will also result in a mail message. This should ordinarily be
+ left 'off'; only check this box if you are making cosmetic changes
+ that don't need attention (such as changing the 'release' field).
+ </P>
+ </DD>
+ <DT><SAMP>Editor (you)</SAMP>
+ </DT>
+ <DD>
+ <P>
+ This field should initially contain your username or email address.
+ Don't change it. If it's blank, put in your username (if you have
+ an account on Taz) or your email address. Whatever value you
+ enter must match your access name to the bugdb.
+ </P>
+ </DD>
+ <DT><SAMP>New synopsis</SAMP>
+ </DT>
+ <DD>
+ <P>
+ The synopsis is a one-line abstract of the PR. <STRONG>Only change
+ this field if the original synopsis is incorrect or unclear.</STRONG>
+ </P>
+ </DD>
+ <DT><SAMP>Originator</SAMP>
+ </DT>
+ <DD>
+ <P>
+ This field contains the email address of the PR's submitter. This
+ ordinarily doesn't need to be changed unless you're correcting
+ an invalid <SAMP>pending</SAMP>-category entry.
+ </P>
+ </DD>
+ <DT><SAMP>Class</SAMP>
+ </DT>
+ <DD>
+ <P>
+ This pull-down list identifies the class of problem being described by
+ the PR. The canonical value is <SAMP>sw-bug</SAMP>; the next most
+ common is <SAMP>change-request</SAMP>. When editing a PR, verify that
+ the value actually applies to the report, and change it if necessary.
+ </P>
+ </DD>
+ <DT><SAMP>Release</SAMP>
+ </DT>
+ <DD>
+ <P>
+ In almost all cases, this should simply contain the Apache release
+ version, without any embellishments. "1.3.2", "1.1.3", "1.3b6-dev"
+ are all acceptable. The only time more text is really appropriate
+ in this field is if the PR refers to one of the non-Apache projects,
+ such as <SAMP>mod_jserv</SAMP>. When editing a PR, try to shorten
+ this field if possible, since it widens the PR summary display
+ unnecessarily.
+ </P>
+ </DD>
+ <DT><SAMP>Severity</SAMP>
+ </DT>
+ <DD>
+ <P>
+ Possible values for this are "critical," "serious," and "non-critical."
+ Make a judgment call about whether the current setting is truly
+ appropriate before changing the value. A PR that has been in "feedback"
+ state for several weeks, for instance, is definitely a candidate
+ for downgrade from "critical." If it were <EM>truly</EM> critical,
+ the submitter would have responded.
+ </P>
+ </DD>
+ <DT><SAMP>New state</SAMP>
+ </DT>
+ <DD>
+ <P>
+ If you are modifying the state of a PR, this is where you do it.
+ See the <A HREF="#states">next section</A> for information about
+ possible values and state transitions. Note that if you change the
+ state of a PR, you <STRONG>must</STRONG> add an explanation in the
+ next field.
+ </P>
+ </DD>
+ <DT><SAMP>If state changed, give the reason here. To add a comment
+ to the case, enter text here without changing the state</SAMP>
+ </DT>
+ <DD>
+ <P>
+ Any time the state of a PR is changed, the alteration must be accompanied
+ by an explanation. This is a free-form text box, so you can word things
+ however you like. It's recommended that you start with a blank line
+ and end with a newline, as well as inserting hard newlines to keep each
+ line of text short. This will make the resulting mail message much
easier
+ to read.
+ </P>
+ <P>
+ If you merely want to annotate a PR without changing its state, just
+ enter the annotation text in this field. It will be recorded as a
+ comment rather than as a state change.
+ </P>
+ </DD>
+ <DT><SAMP>New category</SAMP>
+ </DT>
+ <DD>
+ <P>
+ This pull-down list identifies the portion of Apache to which the
+ PR applies. Almost all of the standard modules and operating
+ systems are listed here, but other values include
+ </P>
+ <UL>
+ <LI><SAMP>apache-api</SAMP> (PR deals with actual programing issues)
+ </LI>
+ <LI><SAMP>config</SAMP> (problem with config directives or setup)
+ </LI>
+ <LI><SAMP>documentation</SAMP>
+ </LI>
+ <LI><SAMP>general</SAMP> (anything that can't be better categorised)
+ </LI>
+ <LI><SAMP>other</SAMP> (a catch-all similar to <SAMP>general</SAMP>)
+ </LI>
+ <LI><SAMP>pending</SAMP> (PRs that were incorrectly submitted)
+ </LI>
+ <LI><SAMP>protocol</SAMP> (actual HTTP or network issues)
+ </LI>
+ <LI><SAMP>suexec</SAMP>
+ </LI>
+ <LI><SAMP>test</SAMP>
+ </LI>
+ </UL>
+ <P>
+ Use your best judgment to set this field. <STRONG>Bear in mind that
+ changing this value will change the <SAMP>Subject</SAMP> line string
+ needed to attach email replies (see the
+ <A HREF="#outofband">Out-of-Band</A> section).</STRONG>
+ </P>
+ </DD>
+ <DT><SAMP>New responsible person</SAMP>
+ </DT>
+ <DD>
+ <P>
+ This field should almost always contain <SAMP>apache</SAMP>. If the
+ field contains anything else, mail about the PR will not be sent to the
+ <SAMP>apache-bugdb</SAMP> mailing list but only to the submitter and
+ the named 'responsible person' address. Change this field to
+ <SAMP>apache</SAMP> when moving a <SAMP>pending</SAMP> PR back into
+ the mainstream database.
+ </P>
+ <P>
+ You <EM>may</EM> change this field to your own account or email
+ address if you intend to work on it and close it personally. This
+ is a signal to other developers to essentially treat the PR as
+ 'hands off' -- but it does have the drawback of reduced mail
+ notification as described above.
+ </P>
+ </DD>
+ <DT><SAMP>If responsible person changed, give the reason here</SAMP>
+ </DT>
+ <DD>
+ <P>
+ If you change the person responsible, you must give an explanation
+ of why.
+ </P>
+ </DD>
+ </DL>
+ <HR>
<H2><A NAME="states">PR States</A>
</H2>
<P>
@@ -167,7 +347,7 @@
<TH>closed</TH>
</TR>
<TR VALIGN=TOP>
- <TH VALIGN=CENTER>open</TH>
+ <TH VALIGN=MIDDLE>open</TH>
<TD><!-- open-open -->
</TD>
<TD><!-- open-analyzed -->
@@ -191,7 +371,7 @@
</TD>
</TR>
<TR VALIGN=TOP>
- <TH VALIGN=CENTER>analyzed</TH>
+ <TH VALIGN=MIDDLE>analyzed</TH>
<TD><!-- analyzed-open -->
It turns out that the analysis was incorrect and the cause really isn't
known after all.
@@ -218,7 +398,7 @@
</TD>
</TR>
<TR VALIGN=TOP>
- <TH VALIGN=CENTER>feedback</TH>
+ <TH VALIGN=MIDDLE>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
@@ -248,7 +428,7 @@
</TD>
</TR>
<TR VALIGN=TOP>
- <TH VALIGN=CENTER>suspended</TH>
+ <TH VALIGN=MIDDLE>suspended</TH>
<TD><!-- suspended-open -->
<MENU>
<LI>The time has come for the issue described by the PR to be
considered
@@ -285,7 +465,7 @@
</TD>
</TR>
<TR VALIGN=TOP>
- <TH VALIGN=CENTER>closed</TH>
+ <TH VALIGN=MIDDLE>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
