720d4d69c8
* Correct some broken links * Use relative links for freebsd.org documents PR: docs/31447 Submitted by: Cyrille Lefevre <clefevre@citeweb.net> Found by: linbot
495 lines
21 KiB
Text
495 lines
21 KiB
Text
<!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 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 <quote>weekend hackers</quote>, 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 — 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) — 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 — 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 <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>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—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 <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>
|
|
</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 <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.
|
|
|
|
$Id$</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>
|
|
|
|
</article>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-indent-data: t
|
|
sgml-omittag: nil
|
|
sgml-always-quote-attributes: t
|
|
End:
|
|
-->
|