Also in Big Scary Daemons:
The best source for improvements to any BSD is the users themselves. While you'll see developers lobbing patches back and forth on the mailing lists, these are generally people who can write to the CVS tree and are openly discussing the benefits of various approaches. Once the most correct method is more-or-less agreed upon, one of these people commits the patch. The mailing lists aren't so much the place to submit patches as the place to discuss patches.
Every BSD project actively seeks out user contributions, and has a system to accept and track them. Patches, even excellent patches, are likely to vanish into the archives if sent directly to the list. By sending your work through proper channels you have a vastly improved chance of committers accepting your work, and eventually becoming a committer yourself. OpenBSD, NetBSD, and FreeBSD all use GNATS and either
sendbug. They're all fairly similar; I'll use FreeBSD as an example.
GNATS is a popular bug-tracking database package. FreeBSD's copy is available on the Web. GNATS tracks "problem reports," or PRs. A PR is simply an e-mail message that follows a specified format.
send-pr program formats mail specifically for entry into GNATS. It provides a template for a problem report, and instructions on how to fill it out. Patches and suggestions submitted via
send-pr are recorded permanently.
This 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. It's 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
freebsd-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 either debugging output or a diff.
Before you open a PR, you need to carefully evaluate what sort of problem you have. If it's dark, you need to dig a little more.
send-pr command is really quite simple. It brings up a text template in
$EDITOR. Once you've completed the template,
send-pr mails it to GNATS for you. That's it.
Sending mail can be a problem on some systems. Perhaps you're on a dial-up connection, and must relay mail through a central server. Your BSD system might not be configured to send e-mail. In those cases, you can use the web interface to submit your PR.
The web interface contains all the fields in the
send-pr command. There's only one problem: It destroys formatting in patches. You can get around this by following up on your own PR on a machine with a mail client.
No matter which method you use, the problem lies in filling out the form. Let's go over it.
Submitter-Id lines can be left alone.
Make sure that the "From" line contains a valid e-mail address; this is where GNATS and/or a committer will try to contact you.
Originator line is your name, generally pulled from your 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".
Similarly, you can either fill in your "organization" or leave it blank.
The Confidential field is generally set to "no". GNATS is a public database. If you're putting confidential information in a PR, you're doing something wrong.
The Synopsis line is probably the most critical. Give a brief, one-line description of the problem. 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 NFS load, ddb 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. This almost guarantees immediate response.
The Severity field gives you three choices. Pick one. Try to be reasonable; if you get a reputation as listing minor bugs as "critical," you'll find yourself ignored fairly quickly.
The Priority field is a bit of a misnomer. This issue might be high priority for you; 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 it might relieve your stress.
The Category field has several options. Several are obsolete or pointless. If you have a problem with a piece of GNU-contributed code, for example, filing a PR in the GNU category will probably get you a response of "talk to the GNU people." The most useful categories are
ports. Check the
send-pr man page for details on what each is for.
The Class field is for a general description of your PR. The choices are mostly self-explanatory. If you can crash a program or the system, it's a
sw-bug. If the documentation is wrong, it's a
doc-bug. If you don't like how something works, it's a change request. An update is an improvement. The
maintainer-update means it's an improvement to a piece of code you already have responsibility for.
Your system type is automatically filled in 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.
Lastly, the System field contains the output of
uname -a. 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 configuration file that demonstrates a bug, put it here.
The Description field is a freeform, plain-text section for you to go into detail about the issue. Don't rant or rave; just describe what happens. Include debugger output and/or error messages, if you have them.
In "How-To-Repeat" 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.
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. Anything you've discovered about how to solve the problem goes here.
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.
If your fix is a diff, use a "context diff" like so:
diff -c yourfile originalfile > patch
This preserves enough context so that it will be applied correctly, and preserves formatting such as spaces and tabs. Do not cut-and-paste patches; this replaces tabs with white space.
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 e-mail. The subject includes the PR number, usually something like "docs/22459" and your synopsis. Any mail sent to firstname.lastname@example.org with that subject line will be attached to that PR. You can submit your patch from a 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 here.
Now that your suggestion is in the FreeBSD system, it will be tracked forever. That's no guarantee that your suggestion will be taken, or that your problem will be solved.
A properly-filled-out PR will generally be quickly snatched up and closed. I've submitted 10 PRs. Nine have been committed and closed. The 10th was a trivial goof on a man page that lives under
/usr/src/contrib, an area where the project specifically disavows responsibility for minor fixes. If I can get 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. Give 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-quality programmers, for many of them this is still a hobby that must take a backseat to sick kids or the big deadline.
If your PR covers a critical bug, chances are that a polite mailing list message will attract whatever attention is needed to fix it. And if it's not critical, it can wait until the proper developer gets back from vacation.
In some cases, you might find that no current FreeBSD committer has in-depth expertise in the part of the system that affects you. If someone submits enough solid patches for that subsystem, it's not unknown for that person to be offered a commit bit and stewardship of that code.
This might seem like a lot of work to get a patch in. Most FreeBSD committers are former users who proved themselves through copious and accurate use of
Finally, your PR will be closed. Perhaps your problem will be solved. Or, more interestingly, perhaps your suggestion will spark a debate on
freebsd-hackers and result in a more resilient and featureful FreeBSD. In either event, a proper problem report will make it possible for the FreeBSD team to provide you with a better operating system.
Michael W. Lucas
Read more Big Scary Daemons columns.
Discuss this article in the Operating Systems Forum.
Return to the BSD DevCenter.
Copyright © 2009 O'Reilly Media, Inc.