                            Contributing to FreeBSD

  Jordan Hubbard

   Contributed by  
   Revision: 43126

   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.

   Last modified on 2013-11-07 by gabor.
   Abstract

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

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

   Table of Contents

   1. What Is Needed

   2. How to Contribute

   Index

   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 (Docbook 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.

 % diff -u oldfile newfile

   or

 % diff -u -r -N olddir newdir

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

   See diff(1) for more information.

   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, such as if you are
   unsure of copyright issues governing its further distribution then you
   should send it to Core Team <core@FreeBSD.org> directly rather than
   submitting it with send-pr(1). The Core Team <core@FreeBSD.org> 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.

         $FreeBSD$

   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
       P.O. Box 20247,
       Boulder,
       CO 80308
       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.

Index

  B

   BSD copyright, New Code or Major Value-Added Packages

  C

   contributing, Contributing to FreeBSD

  D

   diff, Changes to Existing Source Code

   documentation submissions, Changes to the Documentation

   donations, Donating Hardware

  F

   FreeBSD-CURRENT, Changes to Existing Source Code

  G

   GNU General Public License, New Code or Major Value-Added Packages

   GPL (see GNU General Public License)

  P

   problem reports database, Work through the PR Database

  U

   uuencode, Changes to Existing Source Code
