223 lines
11 KiB
Plaintext
223 lines
11 KiB
Plaintext
<!-- $Id: submitters.sgml,v 1.6 1995/08/12 21:33:24 jkh Exp $ -->
|
|
<!-- The FreeBSD Documentation Project -->
|
|
|
|
<chapt><heading>Contributing to FreeBSD<label id="submitters"></heading>
|
|
|
|
<p><em>Contributed by &a.jkh;.</em>
|
|
|
|
This guide is intended for those who are moderately familiar with
|
|
FreeBSD and have reached a point where they have some locally
|
|
developed customizations or fixes to the system which they'd like to
|
|
incorporate back into the mainstream sources. Submitting something to
|
|
the FreeBSD project ensures that you won't have to continually
|
|
reintegrate it with each subsequent release and is also an excellent
|
|
way of getting your code seriously <em>tested</em>! Many people have
|
|
seen an original concept develop far beyond what they might have
|
|
originally envisioned simply 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, 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 document!
|
|
|
|
Submissions to FreeBSD can generally be classified into four categories:
|
|
<enum>
|
|
<item>Ideas, general suggestions, bug reports.
|
|
<item>Changes to existing sources.
|
|
<item>Significant contribution of a large body of independent work.
|
|
<item>Porting of freely available software.
|
|
</enum>
|
|
A submission in <em>any</em> of these categories 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><hackers@freebsd.org></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 sending mail to
|
|
<tt><majordomo@freebsd.org></tt>.
|
|
See <ref id="eresources:mail" 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><></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><bugs@freebsd.org></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'' which is made available in
|
|
a variety of ways for the convenience of developers working
|
|
actively 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 or too divergent for easy re-integration into
|
|
FreeBSD. Chances of this can be minimized somewhat by subscribing to the
|
|
<tt><announce@freebsd.org></tt> and
|
|
<tt><current@freebsd.org></tt> mailing lists, where discussions
|
|
on the current state of the system take place.
|
|
|
|
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 <tt>diff(1)</tt> command,
|
|
with the `context diff' form being preferred. For example:
|
|
<tscreen><verb>
|
|
diff -c <oldfile> <newfile>
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
diff -c -r <olddir> <newdir>
|
|
</verb></tscreen>
|
|
would generate such a set of context diffs for the given source file
|
|
or directory hierarchy. See the man page for <tt>diff(1)</tt> for more
|
|
details.
|
|
|
|
Once you have a set of diffs (which you may test 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><hackers@freebsd.org></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 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><hackers@freebsd.org></tt>.
|
|
See the man pages on <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more
|
|
information on bundling files this way.
|
|
|
|
If your change is of a potentially sensitive nature, e.g.
|
|
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><core@freebsd.org></tt> rather than
|
|
<tt><hackers@freebsd.org></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 send mail to them
|
|
in cases where mailing to hackers is truly 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://ftp.freebsd.org/pub/FreeBSD/incoming">.
|
|
|
|
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>The BSD copyright. This copyright is most preferred
|
|
due to its ``no strings attached'' 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.
|
|
|
|
<item>The GNU Public License, or ``GPL''. This license isn't 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
|
|
<tt>/sys/gnu</tt> or <tt>/usr/src/gnu</tt>, and is therefore
|
|
easily identifiable to anyone for whom the GPL presents a problem.
|
|
</enum>
|
|
|
|
<p>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.
|
|
|
|
To place a ``BSD-style'' 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 `<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.
|
|
|
|
$Id: submitters.sgml,v 1.6 1995/08/12 21:33:24 jkh 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 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 carefully organized hierarchy know as ``the ports collection''.
|
|
The collection enables a new user to get a quick and complete overview
|
|
of what's available for FreeBSD in an easy-to-compile form. It also
|
|
saves considerable space by not actually containing the the majority
|
|
of the sources being ported, but merely those differences required for
|
|
running under FreeBSD. 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><ports@freebsd.org></tt>.
|
|
|
|
Whichever way you decide to contribute, we hope you'll find it an
|
|
enjoyable and rewarding process. Such contributions are also very
|
|
valuable to FreeBSD's continued progress, and as a free software
|
|
effort, the more we all put in the more we all get back out of it!
|