551 lines
22 KiB
XML
551 lines
22 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
|
|
"../../../share/xml/freebsd45.dtd">
|
|
|
|
<article lang='en'>
|
|
<articleinfo>
|
|
<title>Contributing to FreeBSD</title>
|
|
|
|
<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>
|
|
|
|
<legalnotice id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.ieee;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
</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
|
|
(Docbook 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="&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 — 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 &a.questions; 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 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 <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—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 &a.bugs;. 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 class="directory">src/contrib</filename> in the
|
|
source tree.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Make sure code in
|
|
<filename class="directory">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 and you had to make
|
|
&os;-specific changes, send your patches
|
|
back to the original authors (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="&url.base;/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—they might already have a
|
|
patch ready to be tested, or further ideas that you can
|
|
discuss with them.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Pick one of the items from the <quote>Ideas</quote>
|
|
page</title>
|
|
|
|
<para>The <ulink url="http://wiki.freebsd.org/IdeasPage">&os;
|
|
list of
|
|
projects and ideas for volunteers</ulink> is also available
|
|
for people willing to contribute to the &os; project. The
|
|
list is being regularly updated and contains items for both
|
|
programmers and non-programmers with information about each
|
|
project.</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 &a.hackers;.
|
|
See <ulink
|
|
url="&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="&url.base;/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. When patches are a
|
|
lot larger than 20KB, consider compressing them (eg. with
|
|
&man.gzip.1; or &man.bzip2.1;) and using &man.uuencode.1; to
|
|
include their compressed form in your problem report.</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 &a.bugfollowup;. 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="&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="&url.books.fdp-primer;/index.html">FreeBSD
|
|
Documentation Project Primer</ulink> for complete
|
|
instructions. Send submissions and changes (even small ones
|
|
are welcome!) using &man.send-pr.1; 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="&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.</para>
|
|
|
|
<para>The preferred &man.diff.1; format for submitting patches
|
|
is the unified output format generated by <command>diff
|
|
-u</command>.</para>
|
|
|
|
<indexterm>
|
|
<primary><command>diff</command></primary>
|
|
</indexterm>
|
|
|
|
<screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen>
|
|
|
|
<para>or</para>
|
|
|
|
<screen>&prompt.user; <userinput>diff -u -r -N olddir newdir</userinput></screen>
|
|
|
|
<para>would generate a set of unified diffs for the given source
|
|
file or directory hierarchy.</para>
|
|
|
|
<para>See &man.diff.1; for more information.</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. Archives created with &man.shar.1; are also
|
|
welcome.</para>
|
|
|
|
<para>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 &a.core;
|
|
directly rather than submitting it with &man.send-pr.1;. The
|
|
&a.core; 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; 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>
|
|
<listitem>
|
|
<indexterm><primary>BSD copyright</primary></indexterm>
|
|
|
|
<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>
|
|
|
|
<listitem>
|
|
<indexterm>
|
|
<primary>GPL</primary>
|
|
<see>GNU General Public License</see>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>GNU General Public License</primary>
|
|
</indexterm>
|
|
|
|
<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 class="directory">/sys/gnu</filename> or
|
|
<filename class="directory">/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.
|
|
|
|
$&os;$</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>P.O. Box 20247</street>,
|
|
<city>Boulder</city>,
|
|
<state>CO</state> <postcode>80308</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>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
|
|
<ulink url="&url.base;/donations/">Donations Liaison
|
|
Office</ulink>.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</article>
|