2 How to Contribute

2.1 Bug Reports and General Commentary

An idea or suggestion of general technical interest should be mailed to the FreeBSD technical discussions mailing list. Likewise, people with an interest in such things (and a tolerance for a high volume of mail!) may subscribe to the FreeBSD technical discussions mailing list. See The FreeBSD Handbook for more information about this and other mailing lists.

If you find a bug or are submitting a specific change, please report it using the send-pr(1) program or its WEB-based equivalent. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. Consider compressing patches and using uuencode(1) if they exceed 20KB.

After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem by sending mail to <FreeBSD-gnats-submit@FreeBSD.org>. Use the number as the message subject, e.g. "Re: kern/3377". Additional information for any bug report should be submitted this way.

If you do not receive confirmation in a timely fashion (3 days to a week, depending on your email connection) or are, for some reason, unable to use the send-pr(1) command, then you may ask someone to file it for you by sending mail to the FreeBSD problem reports mailing list.

See also this article on how to write good problem reports.

2.2 Changes to the Documentation

Changes to the documentation are overseen by the FreeBSD documentation project mailing list. Please look at the FreeBSD Documentation Project Primer for complete instructions. Send submissions and changes (even small ones are welcome!) using send-pr(1) as described in Bug Reports and General Commentary.

2.3 Changes to Existing Source Code

An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as “FreeBSD-CURRENT” which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT.

Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the FreeBSD announcements mailing list and the FreeBSD-CURRENT mailing list lists, where discussions on the current state of the system take place.

Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the diff(1) command.

The preferred diff(1) format for submitting patches is the unified output format generated by diff -u. However, for patches that substantially change a region of code, a context output format diff generated by diff -c may be more readable and thus preferable.

For example:

% diff -c oldfile newfile

or

% diff -c -r olddir newdir

would generate such a set of context diffs for the given source file or directory hierarchy.

Likewise,

% diff -u oldfile newfile

or

% diff -u -r olddir newdir

would do the same, except in the unified diff format.

See the manual page for diff(1) for more details.

Once you have a set of diffs (which you may test with the patch(1) command), you should submit them for inclusion with FreeBSD. Use the send-pr(1) program as described in Bug Reports and General Commentary. Do not just send the diffs to the FreeBSD technical discussions mailing list or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report.

If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a tar file and run the uuencode(1) program on it. Archives created with shar(1) are also welcome.

If your change is of a potentially sensitive nature, e.g. you are unsure of copyright issues governing its further distribution or you are simply not ready to release it without a tighter review first, then you should send it to FreeBSD core team directly rather than submitting it with send-pr(1). The FreeBSD core team reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary.

Please refer to intro(9) and style(9) for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code.

2.4 New Code or Major Value-Added Packages

In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as uuencoded tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you.

When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are:

1. The BSD copyright. This copyright is most preferred due to its “no strings attached” nature and general attractiveness to commercial enterprises. Far from discouraging such commercial use, the FreeBSD Project actively encourages such participation by commercial interests who might eventually be inclined to invest something of their own into FreeBSD.

2. The GNU General Public License, or “GPL”. This license is not quite as popular with us due to the amount of extra effort demanded of anyone using the code for commercial purposes, but given the sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc) it would be silly to refuse additional contributions under this license. Code under the GPL also goes into a different part of the tree, that being /sys/gnu or /usr/src/gnu, and is therefore easily identifiable to anyone for whom the GPL presents a problem.

Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be considered. Contributions for which particularly restrictive commercial copyrights apply are generally rejected, though the authors are always encouraged to make such changes available through their own channels.

To place a “BSD-style” copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the %% with the appropriate information:

Copyright (c) %%proper_years_here%%
        %%your_name_here%%, %%your_state%%  %%your_zip%%.  
    All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer as
   the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

        $Id$

For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright.

2.5 Money, Hardware or Internet Access

We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves.