os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

These haven't built for a while.

Browse source 
Let them RIP now that we have an article with the same stuff.
This commit is contained in:
Giorgos Keramidas 2002-06-23 03:10:18 +00:00
parent 886255268c
commit 05e3f8234c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=13454
2 changed files with 0 additions and 495 deletions
en_US.ISO8859-1/books/handbook/contrib
Makefilechapter.sgml

15
en_US.ISO8859-1/books/handbook/contrib/Makefile
View file

@ -1,15 +0,0 @@
#
# Build the Handbook with just the content from this chapter.
#
# $FreeBSD$
#
CHAPTERS= contrib/chapter.sgml
VPATH= ..
MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
DOC_PREFIX?= ${.CURDIR}/../../../..
.include "../Makefile"

480
en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
View file

@ -1,480 +0,0 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<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 to 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="../../../../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://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
&a.hubs; 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:
-->