168 lines
8.9 KiB
Plaintext
168 lines
8.9 KiB
Plaintext
|
-- A submitter's guide to FreeBSD --
|
||
|
|
|
||
|
|
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 *tested*! Many people have developed an original concept
|
||
|
|
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
|
||
|
|
documentation! :-)
|
||
|
|
|
||
|
|
Submissions to FreeBSD can generally be classified into four catagories:
|
||
|
|
|
||
|
|
1. Ideas, general suggestions, bug reports.
|
||
|
|
2. Addition, deletion, renaming or patching of existing sources.
|
||
|
|
3. Significant contribution of a large body of independant work.
|
||
|
|
4. Porting of freely available software.
|
||
|
|
|
||
|
|
A submission in *any* of these catagories is highly welcomed as they
|
||
|
|
are each, in their own way, quite significant to the project.
|
||
|
|
|
||
|
|
|
||
|
|
1. An idea, suggestion or fix can be communicated in one of the following ways:
|
||
|
|
|
||
|
|
o An idea or suggestion of general technical interest should be
|
||
|
|
mailed to <hackers@freebsd.org>. Likewise, people with an interest
|
||
|
|
in such things (and a tolerance for a HIGH volume of mail!) may
|
||
|
|
subscribe by sendimg mail to <majordomo@freebsd.org>. See also the
|
||
|
|
file /usr/share/FAQ/mailing-list.FAQ.
|
||
|
|
|
||
|
|
o An actual bug report should be filed by using the send-pr(1)
|
||
|
|
command (``man send-pr'' for information). This will prompt
|
||
|
|
you for various fields to fill in. Simply go to the fields
|
||
|
|
surrounded by <>'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 (which you should also reference 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 send-pr command, then you may also
|
||
|
|
file a bug report (or follow-up to one) by sending mail to:
|
||
|
|
|
||
|
|
<bugs@freebsd.org>
|
||
|
|
|
||
|
|
|
||
|
|
2. 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 (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for
|
||
|
|
the convenience of developers who wish to actively work on the system.
|
||
|
|
|
||
|
|
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
|
||
|
|
<announce@freebsd.org> 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,
|
||
|
|
then please, 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 (or easier :) 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 diff(1) command, with the FreeBSD maintainers preferring to receive
|
||
|
|
diffs in `context diff' form. See the man page for diff for more details
|
||
|
|
on producing both context and recursive context diffs
|
||
|
|
(diff -c <oldfile> <newfile> or diff -c -r <olddir> <newdir>).
|
||
|
|
|
||
|
|
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 patch(1) command - see patch man page), you
|
||
|
|
should bundle them up in an email message and send it, along with a brief
|
||
|
|
description of what the diffs are for, to <hackers@freebsd.org>. 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 tar file and running the `uuencode' program on it before
|
||
|
|
sending the output of that to <hackers@freebsd.org>. See the man pages
|
||
|
|
on tar and uuencode for more info on bundling files through the mail 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 <core@freebsd.org> rather than <hackers@freebsd.org>. 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 VERY BUSY and so
|
||
|
|
you should really only mail to them in cases where mailing to hackers
|
||
|
|
truly is impractical.
|
||
|
|
|
||
|
|
|
||
|
|
3. 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 (see above)
|
||
|
|
or upload them to our ftp site:
|
||
|
|
ftp://freefall.cdrom.com/pub/FreeBSD/incoming
|
||
|
|
|
||
|
|
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. The view of the FreeBSD project towards
|
||
|
|
acceptable copyrights (for code included in FreeBSD) are:
|
||
|
|
|
||
|
|
3a. Contributions under the BSD copyright (see the file
|
||
|
|
/usr/share/examples/etc/bsd-style-copyright for a template)
|
||
|
|
is 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.
|
||
|
|
|
||
|
|
3b. Contributions under the GNU Public License, or "GPL". This is
|
||
|
|
not quite as popular a solution for us, due to (all religious
|
||
|
|
issues aside) 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 /sys/gnu or /usr/src/gnu.
|
||
|
|
|
||
|
|
3c. 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.
|
||
|
|
|
||
|
|
|
||
|
|
4. 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 (we hope) framework. The ports collection also saves
|
||
|
|
considerable space by not actually containing the the majority of the
|
||
|
|
sources being ported. This can be confusing to the new user and the file
|
||
|
|
/usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works.
|
||
|
|
|
||
|
|
If you have the ports collection on your machine, the file
|
||
|
|
/usr/ports/GUIDELINES also helps to explain the process of creating
|
||
|
|
and contributing a port of your own. For more information on the ports
|
||
|
|
collection (that wasn't available in the FAQ), you may also send mail to
|
||
|
|
<ports@freebsd.org>.
|
||
|
|
|
||
|
|
|
||
|
|
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! :-)
|
||
|
|
|
||
|
|
Jordan
|