445 lines
17 KiB
XML
445 lines
17 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
|
|
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
|
|
<info><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><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author>
|
|
</authorgroup>
|
|
|
|
<legalnotice xml:id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.ieee;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
</info>
|
|
|
|
<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 xml: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 xml: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 <link xlink:href="&url.books.fdp-primer;/translations.html">Translations
|
|
FAQ</link> 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 xml: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
|
|
<systemitem class="fqdomainname">current.FreeBSD.org</systemitem> 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>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 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;.
|
|
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 <link xlink:href="https://bugs.FreeBSD.org/search/">FreeBSD
|
|
PR list</link> 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 <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os;
|
|
list of projects and ideas for volunteers</link> 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 xml: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 xml: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 <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The
|
|
FreeBSD Handbook</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 <link
|
|
xlink:href="https://bugs.FreeBSD.org/submit/">bug submission form</link>.
|
|
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;) prior to
|
|
uploading them.</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.</para>
|
|
|
|
<para>See also <link xlink:href="&url.articles.problem-reports;/article.html">this
|
|
article</link> 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
|
|
<link xlink:href="&url.books.fdp-primer;/index.html">FreeBSD
|
|
Documentation Project Primer</link> for complete
|
|
instructions. Send submissions and changes (even small ones
|
|
are welcome!) using the same method any other bug
|
|
report.</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 <link xlink:href="&url.books.handbook;/current-stable.html">The FreeBSD
|
|
Handbook</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.</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 &os; as a bug report.
|
|
<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>
|
|
|
|
<para>If you feel it appropriate (e.g. you have added, deleted,
|
|
or renamed files), bundle your changes into a
|
|
<command>tar</command> file.
|
|
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 as a bug report. 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
|
|
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. &os;
|
|
prefers free software licenses such as BSD or ISC.
|
|
Copyleft licenses such as GPLv2 are sometimes permitted. The
|
|
complete listing can be found on the <link
|
|
xlink:href="&url.base;/internal/software-license.html">core team
|
|
licensing policy</link> page.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Money or Hardware</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 xml:id="donations">
|
|
<title>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
|
|
<link xlink:href="http://www.freebsdfoundation.org">web
|
|
site</link>.</para>
|
|
|
|
<para>More information about the FreeBSD Foundation can be
|
|
found in <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
|
|
FreeBSD Foundation -- an Introduction</link>. 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
|
|
<link xlink:href="&url.base;/donations/">Donations Liaison
|
|
Office</link>.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<index/>
|
|
</article>
|