Problem Report Handling Guidelines

Bugzilla is an issue management system used by the FreeBSD Project. As accurate tracking of outstanding software defects is important to FreeBSD’s quality, the correct use of the software is essential to the forward progress of the Project.

Access to Bugzilla is available to the entire FreeBSD community. In order to maintain consistency within the database and provide a consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup, handling close requests, and so forth.

It is important to update the state of a PR when certain actions are taken. The state should accurately reflect the current state of work on the PR.

A Problem Report may be in one of the following states:

While handling problem reports, either as a developer who has direct access to the Problem Reports database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs.

The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.

When PRs arrive, they are initially assigned to a generic (placeholder) assignee. These are always prepended with freebsd-. The exact value for this default depends on the category; in most cases, it corresponds to a specific FreeBSD mailing list. Here is the current list, with the most common ones listed first:

Do not be surprised to find that the submitter of the PR has assigned it to the wrong category. If you fix the category, do not forget to fix the assignment as well. (In particular, our submitters seem to have a hard time understanding that just because their problem manifested on an i386 system, that it might be generic to all of FreeBSD, and thus be more appropriate for kern. The converse is also true, of course.)

Certain PRs may be reassigned away from these generic assignees by anyone. There are several types of assignees: specialized mailing lists; mail aliases (used for certain limited-interest items); and individuals.

For assignees which are mailing lists, please use the long form when making the assignment (e.g., freebsd-foo instead of foo); this will avoid duplicate emails sent to the mailing list.

Here is a sample list of such entities; it is probably not complete.

Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.)

For other PRs, please do not reassign them to individuals (other than yourself) unless you are certain that the assignee really wants to track the PR. This will help to avoid the case where no one looks at fixing a particular problem because everyone assumes that the assignee is already working on it.

If a PR has the responsible field set to the username of a FreeBSD developer, it means that the PR has been handed over to that particular person for further work.

Assigned PRs should not be touched by anyone but the assignee or bugmeister. If you have comments, submit a followup. If for some reason you think the PR should change state or be reassigned, send a message to the assignee. If the assignee does not respond within two weeks, unassign the PR and do as you please.

If you find more than one PR that describe the same issue, choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding PR. If several PRs contain non-overlapping useful information, submit all the missing information to one in a followup, including references to the others; then close the other PRs (which are now completely superseded).

A PR is considered stale if it has not been modified in more than six months. Apply the following procedure to deal with stale PRs:

Developers that come across PRs that look like they should have been posted to FreeBSD problem reports mailing list or some other list should close the PR, informing the submitter in a comment why this is not really a PR and where the message should be posted.

The email addresses that Bugzilla listens to for incoming PRs have been published as part of the FreeBSD documentation, have been announced and listed on the web-site. This means that spammers found them.

Whenever you close one of these PRs, please do the following:

Setting the category to junk makes it obvious that there is no useful content within the PR, and helps to reduce the clutter within the main categories.

This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete.