<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous
FreeBSD Entities//EN"> %freebsd;
<!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//EN"> %newsgroups;
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors;
<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> %mailing-lists;
<!ENTITY % not.published "IGNORE">
]>

<article>
  <articleinfo>
    <title>Contributing to FreeBSD</title>

    <pubdate>$FreeBSD$</pubdate>

    <abstract>
      <para>This article describes the different ways in which an
        individual or organization may contribute to the FreeBSD
        Project.</para>
    </abstract>

    <authorgroup>
      <author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>
  </articleinfo>

  <indexterm><primary>contributing</primary></indexterm>

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

  <para>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.</para>

  <para>The FreeBSD project is responsible for an entire operating
    system environment, rather than just a kernel or a few scattered
    utilities.  As such, our <filename>TODO</filename> 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.</para>

  <para>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.</para>

  <sect1 id="contrib-what">
    <title>What Is Needed</title>
    
    <para>The following list of tasks and sub-projects represents
      something of an amalgam of various <filename>TODO</filename>
      lists and user requests.</para>

    <sect2 id="non-programmer-tasks">
      <title>Ongoing Non-Programmer Tasks</title>

      <para>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.</para>

      <orderedlist>
	<listitem>
	  <para>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).</para>
	</listitem>

	<listitem>
	  <para>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 <ulink
	    url="../../books/fdp-primer/translations.html">Translations
	    FAQ</ulink> in the FreeBSD Documentation Project Primer.
	    You are not committing yourself to translating every
	    single FreeBSD document by doing this &mdash; 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.</para>
	</listitem>

	<listitem>
	  <para>Read the freebsd-questions mailing list and &ng.misc;
	    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.</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2 id="ongoing-programmer-tasks">
      <title>Ongoing Programmer Tasks</title> 
        <para>Most of the tasks listed here require a considerable
	investment of time, an in-depth knowledge of the FreeBSD
	kernel, or both.  However, there are also many useful tasks
	which are suitable for <quote>weekend hackers</quote>.</para>

      <orderedlist>
	<listitem>
	  <para>If you run FreeBSD-current and have a good Internet
	    connection, there is a machine <hostid
	    role="fqdn">current.FreeBSD.org</hostid> which builds a
	    full release once a day&mdash;every now and again, try to
	    install the latest release from it and report any failures
	    in the process.</para>
	</listitem>

	<listitem>
	  <para>Read the freebsd-bugs 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.</para>
	</listitem>

	<listitem>
	  <para>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.</para>
	</listitem>

	<listitem>
	  <para>Move contributed software to
	    <filename>src/contrib</filename> in the source
	    tree.</para>
	</listitem>

	<listitem>
	  <para>Make sure code in <filename>src/contrib</filename> is
	    up to date.</para>
	</listitem>

	<listitem>
	  <para>Build the source tree (or just part of it) with extra
	    warnings enabled and clean up the warnings.</para>
	</listitem>

	<listitem>
	  <para>Fix warnings for ports which do deprecated things like
	    using <function>gets()</function> or including
	    <filename>malloc.h</filename>.</para>
	</listitem>

	<listitem>
	  <para>If you have contributed any ports, send your patches
	    back to the original author (this will make your life
	    easier when they bring out the next version)</para>
	</listitem>

	<listitem>
	  <para>Get copies of formal standards like POSIX.  You can
	    get some links about these standards at the <ulink
	    url="http://www.FreeBSD.org/projects/c99/index.html">FreeBSD
	    C99 & Posix Standards Conformance Project</ulink> 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.</para>
	</listitem>

	<listitem>
	  <para>Suggest further tasks for this list!</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2>
      <title>Work through the PR Database</title>

      <indexterm><primary>problem reports database</primary></indexterm>

      <para>The <ulink
	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD
	PR list</ulink> 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.</para>

      <para>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&mdash;they might already have a
	patch ready to be tested, or further ideas that you can
	discuss with them.</para>
    </sect2>
  </sect1>

  <sect1 id="contrib-how">
    <title>How to Contribute</title>

    <para>Contributions to the system generally fall into one or more
      of the following 5 categories:</para>

    <sect2 id="contrib-general">
      <title>Bug Reports and General Commentary</title>

      <para>An idea or suggestion of <emphasis>general</emphasis>
	technical interest should be mailed to the &a.hackers;.
	Likewise, people with an interest in such things (and a
	tolerance for a <emphasis>high</emphasis> volume of mail!) may
	subscribe to the hackers mailing list by sending mail to
	&a.majordomo;.  See <ulink
	url="../../books/handbook/eresources.html#ERESOURCES-MAIL">The
	FreeBSD Handbook</ulink> for more information about this and
	other mailing lists.</para>

      <para>If you find a bug or are submitting a specific change,
	please report it using the &man.send-pr.1; program or its
	<ulink url="../../../../send-pr.html">WEB-based
	equivalent</ulink>.  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 <literal>[PATCH]</literal> in the synopsis of
	the report.  When including patches, <emphasis>do
	not</emphasis> use cut-and-paste because cut-and-paste turns
	tabs into spaces and makes them unusable.  Consider
	compressing patches and using &man.uuencode.1; if they exceed
	20KB.  Upload very large submissions to <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp.FreeBSD.org:/pub/FreeBSD/incoming/</ulink>.</para>

      <para>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 <email>bug-followup@FreeBSD.org</email>.  Use
	the number as the message subject, e.g.  <literal>"Re:
	kern/3377"</literal>.  Additional information for any bug
	report should be submitted this way.</para>

      <para>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 &man.send-pr.1; command,
	then you may ask someone to file it for you by sending mail to
	the &a.bugs;.</para>

      <para>See also <ulink
  	URL="../../articles/problem-reports/article.html">this
  	article</ulink> on how to write good problem reports.</para>
    </sect2>

    <sect2>
      <title>Changes to the Documentation</title>

      <indexterm><primary>documentation submissions</primary></indexterm>

      <para>Changes to the documentation are overseen by the &a.doc;.
	Please look at the <ulink
	url="../../books/fdp-primer/index.html">FreeBSD Documentation
	Project Primer</ulink> for complete instructions.  Send
	submissions and changes (even small ones are welcome!) using
	<command>send-pr</command> as described in <link
	linkend="contrib-general">Bug Reports and General
	Commentary</link>.</para>
    </sect2>

    <sect2>
      <title>Changes to Existing Source Code</title>

      <indexterm><primary>FreeBSD-current</primary></indexterm>

      <para>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 <quote>FreeBSD-current</quote> which is made
	available in a variety of ways for the convenience of
	developers working actively on the system. See <ulink url="
	../../books/handbook/current-stable.html">The FreeBSD
	Handbook</ulink> for more information about getting and using
	FreeBSD-current.</para>

      <para>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 &a.announce; and the
	&a.current; lists, where discussions on the current state of
	the system take place.</para>

      <para>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 &man.diff.1;
	command, with the <quote>context diff</quote> form
	being preferred.  For example:</para>

      <indexterm>
        <primary><command>diff</command></primary>
      </indexterm>
      <para>
	<screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>

	or

	<screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>

	would generate such a set of context diffs for the given
	source file or directory hierarchy.  See the man page for
	&man.diff.1; for more details.</para>

      <para>Once you have a set of diffs (which you may test with the
	&man.patch.1; command), you should submit them for inclusion
	with FreeBSD.  Use the &man.send-pr.1; program as described in
	<link linkend="contrib-general">Bug Reports and General
	Commentary</link>.  <emphasis>Do not</emphasis> just send the
	diffs to the &a.hackers; 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
	<literal>[PATCH]</literal> in the synopsis of the
	report.</para>

      <indexterm>
        <primary><command>uuencode</command></primary>
      </indexterm>

      <para>If you feel it appropriate (e.g. you have added, deleted,
	or renamed files), bundle your changes into a
	<command>tar</command> file and run the &man.uuencode.1;
	program on it.  Shar archives are also welcome.</para>

      <para>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 &a.core;
	directly rather than submitting it with &man.send-pr.1;.  The
	core mailing list reaches a much smaller group of people who
	do much of the day-to-day work on FreeBSD.  Note that this
	group is also <emphasis>very busy</emphasis> and so you should
	only send mail to them where it is truly necessary.</para>

      <para>Please refer to &man.intro.9; and &man.style.9; style for
	some information on coding style. We would appreciate it if
	you were at least aware of this information before submitting
	code.</para>
    </sect2>

    <sect2>
      <title>New Code or Major Value-Added Packages</title>

      <para>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.</para>

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

      <orderedlist>
  <indexterm><primary>BSD copyright</primary></indexterm>
	<listitem>
	  <para>The BSD copyright.  This copyright is most preferred
	    due to its <quote>no strings attached</quote> 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.</para>
	</listitem>

  <indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm>
  <indexterm><primary>GNU General Public License</primary></indexterm>
	<listitem>
	  <para>The GNU General Public License, or <quote>GPL</quote>.
	    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
	    <filename>/sys/gnu</filename> or
	    <filename>/usr/src/gnu</filename>, and is therefore easily
	    identifiable to anyone for whom the GPL presents a
	    problem.</para>
	</listitem>
      </orderedlist>

      <para>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.</para>

      <para>To place a <quote>BSD-style</quote> 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 <literal>%%</literal> with the appropriate
	information.</para>

      <programlisting>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.

        &#36;Id&#36;</programlisting>

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

    <sect2>
      <title>Money, Hardware or Internet Access</title>

      <para>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.</para>

      <sect3>
	<title><anchor id="donations">Donating Funds</title>

	<para>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.</para>

	<para>Donations may be sent in check form to:
	  <address>
	    The FreeBSD Foundation
	    <street>7321 Brockway Dr.</street>
	    <city>Boulder</city>, <state>CO</state> <postcode>80303</postcode>
	    <country>USA</country>
	  </address>
	</para>

	<para>The FreeBSD Foundation is now able to accept donations
	  through the web with PayPal.  To place a donation, please
	  visit the Foundation <ulink
	  url="http://www.freebsdfoundation.org">web
	  site</ulink>.</para>

	<para>More information about the FreeBSD Foundation can be
	  found in <ulink
	  url="http://people.freebsd.org/~jdp/foundation/announcement.html">The
	  FreeBSD Foundation -- an Introduction</ulink>.  To contact
	  the Foundation by email, write to
	  <email>bod@FreeBSDFoundation.org</email>.</para>
      </sect3>

      <sect3>
	<title>Donating Hardware</title>
  <indexterm><primary>donations</primary></indexterm>

	<para>Donations of hardware in any of the 3 following
	  categories are also gladly accepted by the FreeBSD
	  Project:</para>

	<itemizedlist>
	  <listitem>
	    <para>General purpose hardware such as disk drives, memory
	      or complete systems should be sent to the FreeBSD,
	      Inc. address listed in the <emphasis>donating
	      funds</emphasis> section.</para>
	  </listitem>

	  <listitem>
	    <para>Hardware for which ongoing compliance testing is
	      desired.  We are currently trying to put together a
	      testing lab of all components that FreeBSD supports so
	      that proper regression testing can be done with each new
	      release.  We are still lacking many important pieces
	      (network cards, motherboards, etc) and if you would like
	      to make such a donation, please contact &a.dg; for
	      information on which items are still required.</para>
	  </listitem>

	  <listitem>
	    <para>Hardware currently unsupported by FreeBSD for which
	      you would like to see such support added.  Please
	      contact the &a.core; before sending such items as we
	      will need to find a developer willing to take on the
	      task before we can accept delivery of new
	      hardware.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Donating Internet Access</title>

	<para>We can always use new mirror sites for FTP, WWW or
	  <command>cvsup</command>.  If you would like to be such a
	  mirror, please contact the &a.hubs; for more
	  information.</para>
      </sect3>
    </sect2>
  </sect1>

</article>

<!-- 
     Local Variables:
     mode: sgml
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     End:
-->
