[2]The astute among you might wonder what "tty" stands for. It's "teletype." Yes, UNIX is that old.

Submitting a Problem Report

You could argue that this should have been included in Chapter 2 on "Getting More Help." "Problem Report" (PR) sounds impressive, doesn't it? Submitting a PR requires a certain minimum level of information, however, that you wouldn't have until after reading this chapter.

Problem Report System

FreeBSD uses GNATS, a popular bug−tracking database, to track problem reports. The main FreeBSD GNATS database is available under http://www.FreeBSD.org/support.html. For a problem report to be entered into GNATS, it must be submitted in an appropriate format in one of two ways.

First, you can submit your PR on the Web. This might mean a lot of cutting and pasting, but it's certainly possible. The PR form can be found online at http://www.FreeBSD.org/send−pr.html.

If you have a FreeBSD system on the Net, however, you'll find that the simpler way to do this is with send−pr(1). This generates a template for you to fill out with the proper information, and formats the message specifically for use in GNATS. Patches, suggestions, and bug reports submitted via send−pr are recorded permanently.

What's in a PR?

The Problem Report process isn't for problems like "my network card doesn't work." You need to troubleshoot your own problems, with the help of a mailing list or list archive, if appropriate. Send−pr is for patches and debugging information.

A good PR contains enough information to fix the problem, and hopefully even a suggested solution. If you have time to spare, go take a look through some of the open PRs; you might find it illuminating. As I write this, there are 1,918 open PRs. Many contain good, solid debugging information. Others are, to put it kindly, less useful.

The FreeBSD FAQ contains a joke by Dag−Erling C. Sm˜rgrav: "How many−current users does it take to change a light bulb?" Part of the answer is: "Three to submit PRs about it, one of which is misfiled under doc and consists only of"it's dark.'' Remember this when filing a PR; include debugging output, or better still a patch to fix the problem. Before you open a PR, you need to carefully evaluate what sort of problem you have. If the problem amounts to "it's dark," you need to dig a little more.

Using Send−pr

The send−pr command brings up a text template in whatever editor you have in $EDITOR. Once you've completed the template, send−pr mails it to GNATS for you. It's assumed that your system has basic email functionality. If that isn't the case for you, use the Web interface (http://www.FreeBSD.org/send−pr.html) to submit your PR. Here's a sample of the template:

...............................................................................................

To: FreeBSD−gnats−[e-mail] From: Michael Lucas <mwlucas> Reply−To: Michael Lucas <mwlucas> Cc:

X−send−pr−version: 3.113 X−GNATS−Notify:

471

>Submitter−Id: current−users >Originator: Michael Lucas

>Organization: <organization of PR author (multiple lines)> >Confidential: no <FreeBSD PRs are public data>

>Synopsis: <synopsis of the problem (one line)>

>Severity: <[ non−critical | serious | critical ] (one line)> >Priority: <[ low | medium | high ] (one line)>

>Category: <choose from the list of categories above (one line)>

>Class: <[ sw−bug | doc−bug | change−request | update | maintainer−update ] (one line)>

>Release: FreeBSD 5.0−CURRENT i386 >Environment:

System: FreeBSD pedicular.blackhelicopters.org 5.0−CURRENT FreeBSD 5.0−CURRENT #5: Wed Apr 24 07:27:19 EDT 2002

[e-mail]:/shared/usr/currentobj/usr/src/sys/BLEEDING i386

<machine, os, target, libraries (multiple lines)> >Description:

<precise description of the problem (multiple lines)> >How−To−Repeat:

<code/input/activities to reproduce the problem (multiple lines)>

>Fix:

<how to correct or work around the problem, if known (multiple lines)>

...............................................................................................

Filling Out the Form

No matter which method you use, the problem lies in filling out the form. Let's go over it one line at a time.

To, Subject,	These lines can be left alone. GNATS will take care of this for you.
Submitter−Id
From	Make sure that the From line contains a valid email address; this is where
	GNATS or a developer will try to contact you.
Originator	This is your name, generally pulled from your system environment. While some
	folks use handles on the Internet, this is a good place to put your real name. It's
	difficult to treat a serious problem with the attention it deserves if your name
	shows up as "Doctor Web."
Organization	You can either fill in your organization or leave it blank.
Confidential	This defaults to "no". GNATS is a public database.If you're putting confidential
	information in a PR, you're doing something wrong. (If you believe that you have
	discovered a bug with security implications, you can contact
	security−[e-mail]. Don't do this just because the debugging
	information includes your root password, however.)
Synopsis	This line is probably the most critical. Give a brief, one−line description of the
	problem, because developers frequently use this to decide which PRs to take a
	look at. A synopsis like "My system sucks!" will get closed with a terse comment
	about useless PRs, while something like "kernel panic under heavy CPU load,
	dump debug attached" has a better chance of attracting skilled attention. If you
	have a patch to fix the problem, put the word "PATCH" in the synopsis, which
	will almost guarantee a reasonably quick response.

472

Severity	This field gives you three choices; pick a reasonable one. If you get a reputation
	for listing minor bugs as "critical," you'll find yourself ignored fairly quickly. (This
	all works on the honor system, and reputation counts for more than you might
	think.)
Priority	The Priority field is a bit of a misnomer. This issue might be high priority for you,
	but developers tend to ignore this field. Still, you get the option to set it. A good
	synopsis line will get a better response than a priority of "high," but entering a
	priority of high here might relieve your stress.
Category	This field has several options, many of which are obsolete or pointless. For
	example, if you have a problem with a piece of contributed code, filing a PR in
	the GNU category will probably get you a response of "talk to the authors." For
	kernel panics, use the "kern" category.
Class	This field contains a general description of your PR. The choices are mostly
	self−explanatory. If you can crash a program or the system, it's an "sw−bug."
Release	Your system type is automatically entered in the Release field. If you're filling
	out a PR on a different system than the one exhibiting the problem, you'll want
	to correct this.
System	Lastly, put the output of uname −a in the System field. You can add additional
	information to this field to describe other relevant parts of your environment. For
	example, if the machine is a heavily loaded news server, mention that. If you
	have a snippet of a configuration file that reproduces the panic, put it here.
Description	The Description field is a free−form, plain−text section for you to go into detail
	about the issue. Don't rant or rave; just describe what happens. Include any
	error messages, if you have them. This is where you put your debugger output.
	If you don't have debugger output for a kernel panic, do not send a PR. Also
	include your kernel configuration and the contents of /var/run/dmesg.boot.

How−To−Repeat In this field use either a snippet of code, a series of instructions, or a text description of how to reproduce the problem. For some PRs, this can be very short—"read FreeBSD−questions for a week and see how often this is asked" is a perfectly legitimate How−To−Repeat for doc changes. More technical problems require more information.

Fix	The most important part of the PR goes under Fix. If you have a patch that fixes
	the problem, put it here. If you have a workaround, put it here. Any− thing
	you've discovered about how to solve the problem goes here. Sometimes the
	most unusual fix or condition provides the vital clue for the solution.[3]

A good PR always has something in the Fix field. Your solution might not be the one implemented, but it demonstrates that you've put some thought into the matter. The incredible support FreeBSD offers through the mailing lists and Web sites sometimes obscures the fact that when you're up against the wall, the ultimate responsibility for solving problems rests on you.

[3]If you're using the Web interface, do not cut and paste patches into the Fix field. The Web submission form transforms all tabs into spaces, and destroys patch formatting.

When you save and exit your editor, send−pr will ask if you want to submit the problem report. If you think that your PR includes enough information to fix the problem, say "yes". Your system will mail it in.

No matter which method you use to submit a PR, you'll receive a confirmation email. The subject includes the PR number, usually something like "kern/22459", and your synopsis. Any mail sent to

473

FreeBSD−gnats−submit@ FreeBSD.org with that subject line will be attached to that PR. You can submit patches and responses from any computer with a working mail system.

Similarly, any response sent to your patch will be tracked with the PR. You can check the status of your PR at http://www.FreeBSD.org/cgi/query−pr.cgi.

Note Now that your suggestion is in the FreeBSD system, it'll be tracked forever. That is not a guarantee that your suggestion will be taken, or that your problem will be solved; it'll simply be recorded, publicly, forever.

PR Results

A properly filled−out PR will generally be quickly snatched up and closed. As of this date, I've submitted 59 PRs. Most have been solved or committed, and closed. The odd ones out were trivial goofs on documentation that lives under /usr/src/contrib, an area where the Project specifically disavows responsibility for minor fixes. If I can get over 90 percent of my PRs successfully closed, anyone can.

If you happen to hit an area of the system that nobody is particularly familiar with, your PR might languish for some time. If it seems that your PR has been forgotten, drop a friendly note to the appropriate mailing list with your PR number and a brief explanation of what it is and why it's important. Since FreeBSD is a volunteer effort, it's quite possible that something happened to the person who would normally handle your type of PR. While many FreeBSD developers are professional programmers, for many of them this is still a hobby that must take a backseat to sick kids or the big deadline. If nothing else, you can contact one of the commercial support companies listed on the FreeBSD Web site.

A surprising number of difficult PRs are closed quickly, given the proper information. Just remember that the FreeBSD folks are doing this out of love for their work, not because they have to. They want to produce quality code, which is a stronger motivation than a paycheck. If you can help them produce a quality product, they'll be delighted to work with you.

Congratulations! You're now as prepared for a crash as any non−kernel developer can be. Proper preparation can make your life easier, and preparing for the worst is one of the best ways to sleep uninterrupted at night.

474