                        Contributing to FreeBSD

  Jordan Hubbard

   $FreeBSD: doc/en_US.ISO8859-1/articles/contributing/article.sgml,v
   1.512 2012/02/07 22:08:33 wblock Exp $

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   IEEE, POSIX, and 802 are registered trademarks of Institute of
   Electrical and Electronics Engineers, Inc. in the United States.

   Many of the designations used by manufacturers and sellers to
   distinguish their products are claimed as trademarks. Where those
   designations appear in this document, and the FreeBSD Project was
   aware of the trademark claim, the designations have been followed
   by the "(TM)" or the "(R)" symbol.

   This article describes the different ways in which an individual
   or organization may contribute to the FreeBSD Project.

     --------------------------------------------------------------

   So you want to contribute to FreeBSD? That is great! FreeBSD
   relies on the contributions of its user base to survive. Your
   contributions are not only appreciated, they are vital to
   FreeBSD's continued growth.

   Contrary to what some people might have you believe, you do not
   need to be a hot-shot programmer or a close personal friend of the
   FreeBSD core team to have your contributions accepted. A large and
   growing number of international contributors, of greatly varying
   ages and areas of technical expertise, develop FreeBSD. There is
   always more work to be done than there are people available to do
   it, and more help is always appreciated.

   The FreeBSD project is responsible for an entire operating system
   environment, rather than just a kernel or a few scattered
   utilities. As such, our TODO lists span a very wide range of
   tasks: from documentation, beta testing and presentation, to the
   system installer and highly specialized types of kernel
   development. People of any skill level, in almost any area, can
   almost certainly help the project.

   Commercial entities engaged in FreeBSD-related enterprises are
   also encouraged to contact us. Do you need a special extension to
   make your product work? You will find us receptive to your
   requests, given that they are not too outlandish. Are you working
   on a value-added product? Please let us know! We may be able to
   work cooperatively on some aspect of it. The free software world
   is challenging many existing assumptions about how software is
   developed, sold, and maintained, and we urge you to at least give
   it a second look.

     --------------------------------------------------------------

1 What Is Needed

   The following list of tasks and sub-projects represents something
   of an amalgam of various TODO lists and user requests.

     --------------------------------------------------------------

  1.1 Ongoing Non-Programmer Tasks

   Many people who are involved in FreeBSD are not programmers. The
   Project includes documentation writers, Web designers, and support
   people. All that these people need to contribute is an investment
   of time and a willingness to learn.

    1. Read through the FAQ and Handbook periodically. If anything is
       badly explained, out of date or even just completely wrong,
       let us know. Even better, send us a fix (SGML is not difficult
       to learn, but there is no objection to ASCII submissions).

    2. Help translate FreeBSD documentation into your native
       language. If documentation already exists for your language,
       you can help translate additional documents or verify that the
       translations are up-to-date. First take a look at the
       Translations FAQ in the FreeBSD Documentation Project Primer.
       You are not committing yourself to translating every single
       FreeBSD document by doing this -- as a volunteer, you can do
       as much or as little translation as you desire. Once someone
       begins translating, others almost always join the effort. If
       you only have the time or energy to translate one part of the
       documentation, please translate the installation instructions.

    3. Read the FreeBSD general questions mailing list and the
       comp.unix.bsd.freebsd.misc newsgroup occasionally (or even
       regularly). It can be very satisfying to share your expertise
       and help people solve their problems; sometimes you may even
       learn something new yourself! These forums can also be a
       source of ideas for things to work on.

     --------------------------------------------------------------

  1.2 Ongoing Programmer Tasks

   Most of the tasks listed here require either a considerable
   investment of time, or an in-depth knowledge of the FreeBSD
   kernel, or both. However, there are also many useful tasks which
   are suitable for "weekend hackers".

    1. If you run FreeBSD-CURRENT and have a good Internet
       connection, there is a machine current.FreeBSD.org which
       builds a full release once a day--every now and again, try to
       install the latest release from it and report any failures in
       the process.

    2. Read the FreeBSD problem reports mailing list. There might be
       a problem you can comment constructively on or with patches
       you can test. Or you could even try to fix one of the problems
       yourself.

    3. If you know of any bug fixes which have been successfully
       applied to -CURRENT but have not been merged into -STABLE
       after a decent interval (normally a couple of weeks), send the
       committer a polite reminder.

    4. Move contributed software to src/contrib in the source tree.

    5. Make sure code in src/contrib is up to date.

    6. Build the source tree (or just part of it) with extra warnings
       enabled and clean up the warnings.

    7. Fix warnings for ports which do deprecated things like using
       gets() or including malloc.h.

    8. If you have contributed any ports and you had to make
       FreeBSD-specific changes, send your patches back to the
       original authors (this will make your life easier when they
       bring out the next version).

    9. Get copies of formal standards like POSIX(R). You can get some
       links about these standards at the FreeBSD C99 & POSIX
       Standards Conformance Project web site. Compare FreeBSD's
       behavior to that required by the standard. If the behavior
       differs, particularly in subtle or obscure corners of the
       specification, send in a PR about it. If you are able, figure
       out how to fix it and include a patch in the PR. If you think
       the standard is wrong, ask the standards body to consider the
       question.

   10. Suggest further tasks for this list!

     --------------------------------------------------------------

  1.3 Work through the PR Database

   The FreeBSD PR list shows all the current active problem reports
   and requests for enhancement that have been submitted by FreeBSD
   users. The PR database includes both programmer and non-programmer
   tasks. Look through the open PRs, and see if anything there takes
   your interest. Some of these might be very simple tasks that just
   need an extra pair of eyes to look over them and confirm that the
   fix in the PR is a good one. Others might be much more complex, or
   might not even have a fix included at all.

   Start with the PRs that have not been assigned to anyone else. If
   a PR is assigned to someone else, but it looks like something you
   can handle, email the person it is assigned to and ask if you can
   work on it--they might already have a patch ready to be tested, or
   further ideas that you can discuss with them.

     --------------------------------------------------------------

  1.4 Pick one of the items from the "Ideas" page

   The FreeBSD list of projects and ideas for volunteers is also
   available for people willing to contribute to the FreeBSD project.
   The list is being regularly updated and contains items for both
   programmers and non-programmers with information about each
   project.

     --------------------------------------------------------------

2 How to Contribute

   Contributions to the system generally fall into one or more of the
   following 5 categories:

     --------------------------------------------------------------

  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. When patches are a lot larger than 20KB,
   consider compressing them (eg. with gzip(1) or bzip2(1)) and using
   uuencode(1) to include their compressed form in your problem
   report.

   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
   <bug-followup@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.

     --------------------------------------------------------------

    2.5.1 Donating Funds

   The FreeBSD Foundation is a non-profit, tax-exempt foundation
   established to further the goals of the FreeBSD Project. As a
   501(c)3 entity, the Foundation is generally exempt from US federal
   income tax as well as Colorado State income tax. Donations to a
   tax-exempt entity are often deductible from taxable federal
   income.

   Donations may be sent in check form to:

       The FreeBSD Foundation
       7321 Brockway Dr.
       Boulder,
       CO 80303
       USA
     

   The FreeBSD Foundation is now able to accept donations through the
   web with PayPal. To place a donation, please visit the Foundation
   web site.

   More information about the FreeBSD Foundation can be found in The
   FreeBSD Foundation -- an Introduction. To contact the Foundation
   by email, write to <bod@FreeBSDFoundation.org>.

     --------------------------------------------------------------

    2.5.2 Donating Hardware

   The FreeBSD Project happily accepts donations of hardware that it
   can find good use for. If you are interested in donating hardware,
   please contact the Donations Liaison Office.

     --------------------------------------------------------------

    2.5.3 Donating Internet Access

   We can always use new mirror sites for FTP, WWW or cvsup. If you
   would like to be such a mirror, please see the Mirroring FreeBSD
   article for more information.

     --------------------------------------------------------------
