path: root/en_US.ISO8859-1/articles/contributing/article.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml,v 1.467 2001/08/10 22:58:11 chern Exp $
-->

<chapter id="contrib">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>
  </chapterinfo>

  <title>Contributing to FreeBSD</title>
  
  <indexterm><primary>contributing</primary></indexterm>
  <para>So you want to contribute something to FreeBSD? That is great! We can
    always use the help, and FreeBSD is one of those systems that
    <emphasis>relies</emphasis> on the contributions of its user base in order
    to survive.  Your contributions are not only appreciated, they are vital
    to FreeBSD's continued growth!</para>
      
  <para>Contrary to what some people might also have you believe, you do not
    need to be a hot-shot programmer or a close personal friend of the FreeBSD
    core team in order to have your contributions accepted.  The FreeBSD
    Project's development is done by a large and growing number of
    international contributors whose ages and areas of technical expertise
    vary greatly, and there is always more work to be done than there are
    people available to do it.</para>
      
  <para>Since the FreeBSD project is responsible for an entire operating
    system environment (and its installation) rather than just a kernel or a
    few scattered utilities, our <filename>TODO</filename> list also spans a
    very wide range of tasks, from documentation, beta testing and
    presentation to highly specialized types of kernel development.  No matter
    what your skill level, there is almost certainly something you can do to
    help the project!</para>
      
  <para>Commercial entities engaged in FreeBSD-related enterprises are also
    encouraged to contact us.  Need a special extension to make your product
    work? You will find us receptive to your requests, given that they are not
    too outlandish.  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 a lot of existing assumptions about how software is
    developed, sold, and maintained throughout its life cycle, 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 the various core team <filename>TODO</filename> lists and
      user requests we have collected over the last couple of months.  Where
      possible, tasks have been ranked by degree of urgency.  If you are
      interested in working on one of the tasks you see here, send mail to the
      coordinator listed by clicking on their names.  If no coordinator has
      been appointed, maybe you would like to volunteer?</para>

    <sect2>
      <title>Ongoing Tasks</title>
      
      <para>Most of the tasks listed in the previous sections 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 &quot;weekend hackers&quot;, or people without
	programming skills.</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 and 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>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 not already available) &mdash; just send an email to &a.doc;
	    asking if anyone is working on it.  Note that you are not
	    committing yourself to translating every single FreeBSD document
	    by doing this &mdash; in fact, the documentation most in need of
	    translation is 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>

	<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
	    gets() or including malloc.h.</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>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.
	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.</para>

      <para>Start with the PRs that have not been assigned to anyone else, but
	if one them 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 6 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 <link
	  linkend="eresources-mail">mailing lists</link> 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="http://www.FreeBSD.org/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>
    </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;.  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 the core 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 <link
	  linkend="current">Staying current with FreeBSD</link> 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>
	  The Foundation is not yet able to accept other forms
	  of payment such as credit cards and PayPal.</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 FreeBSD project administrators
	  <email>hubs@FreeBSD.org</email> for more information.</para>
      </sect3>
    </sect2>
  </sect1>
  
</chapter>

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->