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

Substantial re-write.

Browse source
This commit is contained in:
Jordan K. Hubbard 1995-08-12 21:33:24 +00:00
parent 0e794a3b34
commit 3a1ccb8d54
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=49
1 changed files with 83 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

180
handbook/submitters.sgml
View file

@ -1,28 +1,28 @@
<!-- $Id: submitters.sgml,v 1.5 1995-07-07 22:25:54 jfieber Exp $ -->
<!-- $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 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!
This guide is intended for those who are moderately familar 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 catagories:
<enum>
<item>Ideas, general suggestions, bug reports.
<item>Addition, deletion, renaming or patching of existing sources.
<item>Changes to existing sources.
<item>Significant contribution of a large body of independant work.
<item>Porting of freely available software.
</enum>
@ -64,28 +64,23 @@ are each, in their own way, quite significant to the project.
<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.
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 to use, or too divergent to allow for easy
re-integration. This can be minimized somewhat by subscribing to the
<tt>&lt;announce@freebsd.org&gt;</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.
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>&lt;announce@freebsd.org&gt;</tt> and
<tt>&lt;current@freebsd.org&gt;</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 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:
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 &lt;oldfile&gt &lt;newfile&gt;
</verb></tscreen>
@ -93,39 +88,36 @@ or
<tscreen><verb>
diff -c -r &lt;olddir&gt &lt;newdir&gt;
</verb></tscreen>
See the man page for <tt>diff(1)</tt> for more details
on producing both context and recursive context diffs.
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 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
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>&lt;hackers@freebsd.org&gt;</tt>. Someone will very
likely get back in touch with you in 24 hours or less,
assuming of course that your diffs are interesting!
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>&lt;hackers@freebsd.org&gt;</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.
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>&lt;hackers@freebsd.org&gt;</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, 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>&lt;core@freebsd.org&gt;</tt> rather than
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>&lt;core@freebsd.org&gt;</tt> rather than
<tt>&lt;hackers@freebsd.org&gt;</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.
<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>
@ -134,42 +126,40 @@ diff -c -r &lt;olddir&gt &lt;newdir&gt;
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.
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>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
<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>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.
<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 identifable to anyone for whom the GPL presents a problem.
</enum>
To place such a copyright on your work, place the following
<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.
@ -203,7 +193,7 @@ 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.5 1995-07-07 22:25:54 jfieber Exp $
$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>.
@ -212,25 +202,21 @@ For your convenience, a copy of this text can be found in
<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
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>&lt;ports@freebsd.org&gt;</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!
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!