path: root/share/doc/handbook/submitters.sgml

<!-- submitters.sgml,v 1.2 1995/05/18 03:05:22 jfieber Exp -->
<!-- The FreeBSD Documentation Project -->

<chapt><heading>Contributing to FreeBSD</heading>

<p><em>Contributed by &a.jkh;.</em>

This guide is intended for those who are moderately familar with FreeBSD
and are now to the point where they have some locally developed
customizations or fixes to the system which they'd like to incorporate
back into the mainstream sources, thus saving the work of having to
re-integrate the changes for each subsequent FreeBSD release.  Submitting
something to the FreeBSD project is also an excellent way of getting your
code seriously <em>tested</em>!  Many people have developed an original concept
far beyond what they might have envisioned at the start just due to the
flood of feedback and ideas generated by the many thousands of users of
FreeBSD.  Contributions are also what FreeBSD lives and grows from,
and so your contributions are very important to the continued survival
of this communal effort of ours---we're very glad to see you reading this
documentation!

Submissions to FreeBSD can generally be classified into four catagories:
<enum>
<item>Ideas, general suggestions, bug reports.
<item>Addition, deletion, renaming or patching of existing sources.
<item>Significant contribution of a large body of independant work.
<item>Porting of freely available software.
</enum>
A submission in <em>any</em> of these catagories is highly welcomed as they
are each, in their own way, quite significant to the project.  


<sect><heading>Ideas and suggestions</heading>

<p>An idea, suggestion or fix can be communicated in one of the following ways:
<itemize>
	<item>An idea or suggestion of general technical interest should be
	  mailed to <tt>&lt;hackers@freebsd.org&gt;</tt>.  
          Likewise, people with an interest
	  in such things (and a tolerance for a <em>high</em>
	  volume of mail!) may
	  subscribe to the hackers mailing list by sendimg mail to 
          <tt>&lt;majordomo@freebsd.org&gt;</tt>.  
          See <ref id="eresources:mailing-lists"
          name="mailing lists">
	  for more information about this and other mailing lists.

	<item>An actual bug report should be filed by using the 
          <tt>send-pr(1)</tt> program.  This will prompt
	  you for various fields to fill in.  Simply go to the fields
	  surrounded by <tt>&lt;&gt;</tt>'s and fill in your own 
          information in place of
	  what's suggested there.  You should receive confirmation of your
	  bug report and a tracking number.  Keep this tracking number and use
	  it in any subsequent correspondence.
          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 <tt>send-pr(1)</tt> command,
	  then you may also file a bug report by sending mail to
          <tt>&lt;bugs@freebsd.org&gt;</tt>.
</itemize>

<sect><heading>Changes to the existing code</heading>

<p>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 ``FreeBSD-current'' and made available in a variety of
   ways for the convenience of developers who wish to actively work on the 
   system.  See <ref id="current:" name="Staying current with
   FreeBSD"> for more information about getting and using FreeBSD-current.

   Working from older sources unfortunately means that your changes may
   sometimes be too obsolete to use, or too divergent to allow for easy
   re-integration.  This can be minimized somewhat by subscribing to the
   <tt>&lt;announce@freebsd.org&gt;</tt> mailing list, among
   others, where periodic
   announcements concerning the current state of the system are made.
   If you see a change being proposed for which you have a better solution,
   by all means come forward with your contribution and we
   will do our very best to evaluate it fairly and perhaps integrate it if
   it is indeed a better solution.

   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 for evaluation and possible adoption.  This is done
   with the <tt>diff(1)</tt> command, with the FreeBSD
   maintainers preferring to receive
   diffs in `context diff' form. For example:
<tscreen><verb>
diff -c &lt;oldfile&gt &lt;newfile&gt;
</verb></tscreen>
or
<tscreen><verb>
diff -c -r &lt;olddir&gt &lt;newdir&gt;
</verb></tscreen>
   See the man page for <tt>diff(1)</tt> for more details
   on producing both context and recursive context diffs.

   Once you have a set of diffs that are capable of taking a copy
   of the original code and bringing it to a state identical to
   the ``new'' sources (you may test this with the
   <tt>patch(1)</tt> command), you should bundle them up in an
   email message and send it, along with a brief description of
   what the diffs are for, to
   <tt>&lt;hackers@freebsd.org&gt;</tt>.  Someone will very
   likely get back in touch with you in 24 hours or less,
   assuming of course that your diffs are interesting!

   If your changes don't express themselves well as diffs alone
   (e.g. you've perhaps added, deleted or renamed files as well)
   then you may be better off bundling any new files, diffs and
   instructions for deleting/renaming any others into a
   <tt>tar</tt> file and running the <tt>uuencode(1)</tt> program
   on it before sending the output of that to
   <tt>&lt;hackers@freebsd.org&gt;</tt>.  See the man pages on
   <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more info on
   bundling files through the mail this way.

   If your change is of a potentially sensitive nature, for
   example you're unsure of copyright issues governing its
   further distribution, or you're simply not ready to release it
   without a tighter review first, then you should send it to
   <tt>&lt;core@freebsd.org&gt;</tt> rather than
   <tt>&lt;hackers@freebsd.org&gt;</tt>.  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
   <em>very busy</em> and so you should only mail to them
   in cases where mailing to hackers truly is impractical.


<sect><heading>Contributions of new code</heading>

<p>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 our ftp site <url
   url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> where
   users may log in anonymously and upload their work or download
   the work-in-progress files left by others.

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

<enum>
	<item>Contributions under the BSD copyright 
	    are greatly preferred due to its ``no strings attached''
	    nature and general attractiveness to commercial enterprises
	    who might then be inclined to invest something of their own
	    into FreeBSD.

	<item>Contributions under the GNU Public License, or ``GPL''.  This is
	    not quite as popular a solution for us, due to
	    the amount of extra effort demanded of anyone
	    using the code for commercial purposes.  However, given the
	    sheer quantity of GPL'd code we currently require (compiler,
	    assembler, text formatter, etc), it would be silly to pretend
	    that we couldn't deal with the GPL at all and so we have become
	    more willing to accept code with either the BSD or the GPL
	    copyright.  Code under the GPL also goes into a different part
	    of the tree, that being <tt>/sys/gnu</tt> or 
	    <tt>/usr/src/gnu</tt>.

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

   To place such a copyright on your work, place the following
   text at the very beginning of every source code file you wish
   to protect, replacing the text between the `<tt>%%</tt>' with
   the appropriate information.
<tscreen><verb>
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.
3. All advertising materials mentioning features or use of this software
   must display the following acknowledgment:
	This product includes software developed by %%your_name_here%%.
4. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

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.

	submitters.sgml,v 1.2 1995/05/18 03:05:22 jfieber Exp
</verb></tscreen>
For your convenience, a copy of this text can be found in
<tt>/usr/share/examples/etc/bsd-style-copyright</tt>.
		      

<sect><heading>Porting of software</heading>

<p>The porting of freely available software, while perhaps not as
gratifying as developing your own package from scratch, is still
a vital part of FreeBSD's growth and of great usefulness to those
who wouldn't otherwise know where to turn for it.  All ported
software is organized into a hierarchy know as ``the ports
collection''.  This collection enables a new user to get a
complete overview of what's available in a short time, and with a
logical framework.  The ports collection also saves
considerable space by not actually containing the the majority of
the sources being ported.  See <ref id="ports:" name="The ports
collection"> for more information on using the ports collection
and <ref id="porting:" name="Porting applications"> for
guidelines on creating new ports.  You may also send mail to
<tt>&lt;ports@freebsd.org&gt;</tt>.

Whichever way you decide to contribute, we hope you'll find it an
enjoyable process and also realize how valuable your
contributions are to the project!  FreeBSD is one of those great
projects where the more we all put in, the more we all get back
out of it again, and with enough steady contributions it begins
to aquire a momentum of its own.  It is through such momentum
that mountains are moved!