This document defines the rules and policies that govern the handling of Apache problem reports (PRs).
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 always be encouraged to run the latest version, at least to test whether their issues have been addressed.
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.
Some general guidelines for developers working on problem reports:
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.
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.
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).
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.
The synopsis is a one-line abstract of the PR. Only change this field if the original synopsis is incorrect or unclear.
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 pending-category entry.
This pull-down list identifies the class of problem being described by the PR. The canonical value is sw-bug; the next most common is change-request. When editing a PR, verify that the value actually applies to the report, and change it if necessary.
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 mod_jserv. When editing a PR, try to shorten this field if possible, since it widens the PR summary display unnecessarily.
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 truly critical, the submitter would have responded.
If you are modifying the state of a PR, this is where you do it. See the next section for information about possible values and state transitions. Note that if you change the state of a PR, you must add an explanation in the next field.
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.
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.
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
Use your best judgment to set this field. Bear in mind that changing this value will change the Subject line string needed to attach email replies (see the Out-of-Band section).
This field should almost always contain apache. If the field contains anything else, mail about the PR will not be sent to the apache-bugdb mailing list but only to the submitter and the named 'responsible person' address. Change this field to apache when moving a pending PR back into the mainstream database.
You may 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.
If you change the person responsible, you must give an explanation of why.
A problem report can be in any of the following states. The ones in which most PRs should reside are: open, feedback, and closed. 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."
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.
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.
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 date thresholds).
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.
Closed PRs typically require no additional attention. It is possible, though, for reports to be closed incorrectly or prematurely, so they may occasionally migrate out of this state. Closed PRs are the major component of the knowledge base distilled into the FAQ.
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.
| open | analyzed | feedback | suspended | closed | |
|---|---|---|---|---|---|
| open | Either the submitter or a responding developer has determined what the problem cause is. | A question has been posed to the submitter, such as asking for more detail or requesting an experiment. | 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. | 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. | |
| analyzed | It turns out that the analysis was incorrect and the cause really isn't known after all. | The submitter is being asked for more information or experimentation. | The issue described by the PR should be deferred until some later version. | ||
| feedback | 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.) | The response from the submitter has provided the necessary information to determine the cause, if not the solution, of the issue. | Additional information from the submitter allows the determination to be made that the issue should be addressed in some future version. | ||
| suspended | 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 out-of-band email exchanges between the submitter and a developer.) | 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. | |||
| closed | 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. | The PR was closed prematurely, but the issue is now clarified and understood -- though not yet solved. | The PR was closed prematurely, but additional information has been requested from the submitter to investigate further. | After closure, additional information has been supplied to make a case for future consideration of the issue. |
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.
| State | Time Since Last Touched | PR Last Touched By | PR Condition | Available Actions |
|---|---|---|---|---|
| analyzed | >30 days | N/A | N/A | Edit the PR (without changing state unless appropriate) to let submitter know the issue is not forgotten. |
| feedback | 14-30 days | Developer | Last touch was a developer request for information or experimentation | Click on the "Query -- Outstanding Request" button. |
| Last touch was the "Query -- Outstanding request" message | Click on the "Close -- No response" button to close the PR. |
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 <apbugs@apache.org> address with the appropriate Subject: line.
If you mail information to the bugdb in order to attach it to an existing PR, don't 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.
When additional information is sent to the bugdb through email, do not use MIME attachments or forwarding! The bugdb is not MIME-aware, and so the attachments will probably look ugly.
"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 does not change the PR state, so it needs to be changed manually.