SourceForge Tracker Usage
This document describes the use of the SourceForge bug & patch trackers by the Expat maintainers. These guidelines are substantially based on the guidelines used for Python.
Tracker Item Priority
The priority field is simple enough; the higher the priority a report is, the more important it is that the report needs to be handled. Note that it is the priority of the report relative to other reports; it does not mean action needs to be taken on the software; it may be that a report takes a high priority because the bug it describes is very damaging for someone. Review may, however, determine that the bug is in someone else's code.
So, how should priority be assigned? SourceForge assigns all new reports a priority of "5", which is considered "normal". The follow list shows the meanings of each priority level as used by the Expat project.
- Needs to be solved immediately. We shouldn't need this since we're volunteers, but it's Ok to use this if it's assigned to yourself and you have some external reason to deal with it immediately.
- Needs to be dealt with sooner rather than later, and is before priority "7" reports.
- Needs to be handled before release. No release can be made so long as any report with priority "7" or higher is in any of the trackers we use.
- More important than most reports, but won't cause a release to be held up.
- Most reports. This is how reports are created by default.
- Reports with priority "4" and lower typically wait a long time to be closed, or they're closed fairly quickly because they're really easy to close.
The Status and Resolution Fields
In general, the Resolution and Status fields should be close to self-explanatory, and the "Assigned to:" field should be the person responsible for taking the next step in the patch process. Both fields are expected to change value over the life of a patch; the normal workflow is detailed below.
When you've got the time and the ability, feel free to move any patch that catches your eye along, whether or not it's been assigned to you. And if you're assigned to a patch but aren't going to take reasonably quick action (for whatever reason), please assign it to someone else or unassign it ASAP: at those times you can't actively help, actively get out of the way.
If you're an expert in some area and know that a patch in that area is both needed and non-controversial, just commit your changes directly -- no need then to get the patch mechanism involved in it.
The actual patch status is given by the pair of fields called "Status" and "Resolution":
| Status | Resolution | Meaning | |
|---|---|---|---|
| Open | None | The initial state of all patches.
The patch is under consideration, but has not been reviewed yet, or is under review but not yet Accepted or Rejected. The Resolution will normally change to Accepted or Rejected next. The person submitting the report should (if they have permission) assign it to the person they most want to review it, else the patch will be assigned based on the judgement of the reviewer. Discussion of major patches is carried out on the expat-discuss mailing list. For simple patches, the SourceForge comment mechanism should be sufficient. For the reviewer: If you're certain the patch should be applied, change the Resolution to Accepted and assign it back to the submitter for checkin if they are a developer on the project (if they aren't, the reviewer should commit it and change Resolution to Accepted and Status to Closed). If you're certain the patch should never be accepted, change the Resolution to Rejected, Status to Closed, and write an explanation in the comment box. If you have specific complaints that would cause you to change your mind if addressed, explain them clearly in a comment, leave the status Open, and reassign back to the submitter (again, if they're a developer on the project). If you're uncertain, leave the status Open, explain your uncertainies in a comment, and reassign the patch to someone you believe can address your remaining questions; or leave the status Open and bring it up on expat-discuss. | |
| Open | Accepted | The patch has been accepted, but it hasn't been applied
yet.
The Status will normally change to Closed next. The person changing the Resolution to Accepted should, at the same time, assign the patch to whoever they believe is most likely to be able & willing to apply it (the submitter if possible). | |
| Closed | Accepted | The patch has been accepted and applied.
The previous Resolution was Accepted or None (if the reviewer checked it in). | |
| Closed | Rejected | The patch has been reviewed and rejected.
There are generally no transitions out of this state: the patch is dead. | |
| Open | Out of date | Previous Resolution was Accepted or Postponed, but the patch
no longer works.
Please enter a comment when changing the Resolution to "Out of date", to record the nature of the problem and the previous state. Also assign it back to the submitter, as they need to upload a new version. | |
| Open | Postponed | The previous Resolution was None or Accepted, but for some
reason (e.g., pending release) the patch should not be reviewed
or applied until further notice.
The Resolution will normally change to None or Accepted next, which should be done as soon after the relevant event (release, etc.) as possible. Checking for Postponed reports should be part of the release process. Please enter a comment when changing the Resolution to Postponed, to record the reason, the previous Resolution, and the conditions under which the patch should revert to Resolution None or Accepted. | |
| Deleted | Any | Bit bucket.
Use only if it's OK for the patch and its SourceForge history to disappear. As of 13-June-2002, SourceForge does not actually throw away Deleted patches, but that may change. |
SourceForge Tracker Quirks
The SourceForge trackers, though quite nice to work with for moderate sized projects, do have some quirks and limitations. Most of the funcional limitations are unlikely to affect small projects like Expat, but the quirky behavior... well, we should be aware of it.
- Who is "Nobody"?
- That depends on who initially submitted the report.
The most important thing to know is that SourceForge asks reporters who are not logged in to provide an email address, but does not require it. There is no way to determine whether "Nobody" provided one.
There are at least two common instances of "Nobody". The simple interpretation of "Nobody" (and probably the most common case) is that the reporter did not log into SourceForge and did not provide an email address. Sometimes a name or email address will be included in the initial report or a followup; it is not always the reporters intention to remain anonymous. If an email address is available this way, it is a good idea to send an email to the provided address when following up to a report, allowing the reporter to learn of the response and provide additional feedback or information.
The second common case is that the report was filed by someone without a SourceForge login or who wanted to remain anonymous for some reason, but provided an email address to SourceForge so that they would be automatically notified of any followup activity. In this case, requests for additional information in followup comments can actually get results, sometimes including an email address if the anonymous filing was not designed to protect anonymity but simply to avoid going through the SourceForge login screen.
It's good to know that when filing a report while not logged in, clicking on the "Please log in!" link beneath the large text box will take you to a login page that will return you to your submission form. Contents of the submission form will be lost, unfortunately, but that link can save a bit of navigating if you remember it soon enough.
SourceForge also provides a feature allowing authenticated users to "monitor" a tracker report. Clicking on the "Monitor" button will cause SourceForge to send the user an email on each change to the report in much the way it sends an email to the current assignee or the address configured in the tracker admin for new or modified items. (For Expat, this would be the expat-bugs list.) Users who are monitoring a report are often knowledgable enough to answer questions about whatever the problem is.
So, the "Nobody" listed as the submitter doesn't tell us much, except that we might not get to know who the submitter is.
