237 lines
12 KiB
Plaintext
237 lines
12 KiB
Plaintext
<!-- $Id: submitters.sgml,v 1.4 1995/06/30 17:37:51 jfieber 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 familar with FreeBSD
|
|
and are now to the point where they have some locally developed
|
|
customizations or fixes to the system which they'd like to incorporate
|
|
back into the mainstream sources, thus saving the work of having to
|
|
re-integrate the changes for each subsequent FreeBSD release. Submitting
|
|
something to the FreeBSD project 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 envisioned at the start just 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,
|
|
and 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 catagories:
|
|
<enum>
|
|
<item>Ideas, general suggestions, bug reports.
|
|
<item>Addition, deletion, renaming or patching of existing sources.
|
|
<item>Significant contribution of a large body of independant work.
|
|
<item>Porting of freely available software.
|
|
</enum>
|
|
A submission in <em>any</em> of these catagories 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 sendimg 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'' and made available in a variety of
|
|
ways for the convenience of developers who wish to actively work 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 to use, or too divergent to allow for easy
|
|
re-integration. This can be minimized somewhat by subscribing to the
|
|
<tt><announce@freebsd.org></tt> mailing list, among
|
|
others, where periodic
|
|
announcements concerning the current state of the system are made.
|
|
If you see a change being proposed for which you have a better solution,
|
|
by all means come forward with your contribution and we
|
|
will do our very best to evaluate it fairly and perhaps integrate it if
|
|
it is indeed a better solution.
|
|
|
|
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 for evaluation and possible adoption. This is done
|
|
with the <tt>diff(1)</tt> command, with the FreeBSD
|
|
maintainers preferring to receive
|
|
diffs in `context diff' form. For example:
|
|
<tscreen><verb>
|
|
diff -c <oldfile> <newfile>
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
diff -c -r <olddir> <newdir>
|
|
</verb></tscreen>
|
|
See the man page for <tt>diff(1)</tt> for more details
|
|
on producing both context and recursive context diffs.
|
|
|
|
Once you have a set of diffs that are capable of taking a copy
|
|
of the original code and bringing it to a state identical to
|
|
the ``new'' sources (you may test this 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 any 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 info on
|
|
bundling files through the mail this way.
|
|
|
|
If your change is of a potentially sensitive nature, for
|
|
example 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 mail to them
|
|
in cases where mailing to hackers truly is 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://freefall.cdrom.com/pub/FreeBSD/incoming"> where
|
|
users may log in anonymously and upload their work or download
|
|
the work-in-progress files left by others.
|
|
|
|
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>Contributions under the BSD copyright
|
|
are greatly preferred due to its ``no strings attached''
|
|
nature and general attractiveness to commercial enterprises
|
|
who might then be inclined to invest something of their own
|
|
into FreeBSD.
|
|
|
|
<item>Contributions under the GNU Public License, or ``GPL''. This is
|
|
not quite as popular a solution for us, due to
|
|
the amount of extra effort demanded of anyone
|
|
using the code for commercial purposes. However, given the
|
|
sheer quantity of GPL'd code we currently require (compiler,
|
|
assembler, text formatter, etc), it would be silly to pretend
|
|
that we couldn't deal with the GPL at all and so we have become
|
|
more willing to accept code with either the BSD or the GPL
|
|
copyright. 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>.
|
|
|
|
<item>Contributions coming under any other type of copyright must be
|
|
carefully reviewed before their inclusion into FreeBSD will even
|
|
be considered. Contributions for which particularly restrictive
|
|
commercial copyrights apply are generally rejected, though the
|
|
authors are always free to make the changes available through
|
|
their own channels.
|
|
</enum>
|
|
|
|
To place such a copyright on your work, place 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.4 1995/06/30 17:37:51 jfieber 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 package 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 hierarchy know as ``the ports
|
|
collection''. This collection enables a new user to get a
|
|
complete overview of what's available in a short time, and with a
|
|
logical framework. The ports collection also saves
|
|
considerable space by not actually containing the the majority of
|
|
the sources being ported. 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 process and also realize how valuable your
|
|
contributions are to the project! FreeBSD is one of those great
|
|
projects where the more we all put in, the more we all get back
|
|
out of it again, and with enough steady contributions it begins
|
|
to aquire a momentum of its own. It is through such momentum
|
|
that mountains are moved!
|
|
|