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

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 --> <!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD<label id="submitters"></heading> <chapt><heading>Contributing to FreeBSD<label id="submitters"></heading>
<p><em>Contributed by &a.jkh;.</em> <p><em>Contributed by &a.jkh;.</em>
This guide is intended for those who are moderately familar with FreeBSD This guide is intended for those who are moderately familar with
and are now to the point where they have some locally developed FreeBSD and have reached a point where they have some locally
customizations or fixes to the system which they'd like to incorporate developed customizations or fixes to the system which they'd like to
back into the mainstream sources, thus saving the work of having to incorporate back into the mainstream sources. Submitting something to
re-integrate the changes for each subsequent FreeBSD release. Submitting the FreeBSD project ensures that you won't have to continually
something to the FreeBSD project is also an excellent way of getting your reintegrate it with each subsequent release and is also an excellent
code seriously <em>tested</em>! Many people have seen an original concept way of getting your code seriously <em>tested</em>! Many people have
develop far beyond what they might have envisioned at the start just due to the seen an original concept develop far beyond what they might have
flood of feedback and ideas generated by the many thousands of users of originally envisioned simply due to the flood of feedback and ideas
FreeBSD. Contributions are also what FreeBSD lives and grows from, generated by the many thousands of users of FreeBSD. Contributions
and so your contributions are very important to the continued survival are also what FreeBSD lives and grows from, so your contributions are
of this communal effort of ours---we're very glad to see you reading this very important to the continued survival of this communal effort of
document! ours---we're very glad to see you reading this document!
Submissions to FreeBSD can generally be classified into four catagories: Submissions to FreeBSD can generally be classified into four catagories:
<enum> <enum>
<item>Ideas, general suggestions, bug reports. <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>Significant contribution of a large body of independant work.
<item>Porting of freely available software. <item>Porting of freely available software.
</enum> </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 <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 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 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 of FreeBSD known as ``FreeBSD-current'' which is made available in
ways for the convenience of developers who wish to actively work on the a variety of ways for the convenience of developers working
system. See <ref id="current" name="Staying current with actively on the system. See <ref id="current" name="Staying
FreeBSD"> for more information about getting and using FreeBSD-current. current with FreeBSD"> for more information about getting and using
FreeBSD-current.
Working from older sources unfortunately means that your changes may Working from older sources unfortunately means that your changes may
sometimes be too obsolete to use, or too divergent to allow for easy sometimes be too obsolete or too divergent for easy re-integration into
re-integration. This can be minimized somewhat by subscribing to the FreeBSD. Chances of this can be minimized somewhat by subscribing to the
<tt>&lt;announce@freebsd.org&gt;</tt> mailing list, among <tt>&lt;announce@freebsd.org&gt;</tt> and
others, where periodic <tt>&lt;current@freebsd.org&gt;</tt> mailing lists, where discussions
announcements concerning the current state of the system are made. on the current state of the system take place.
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 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 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 FreeBSD maintainers. This is done with the <tt>diff(1)</tt> command,
with the <tt>diff(1)</tt> command, with the FreeBSD with the `context diff' form being preferred. For example:
maintainers preferring to receive
diffs in `context diff' form. For example:
<tscreen><verb> <tscreen><verb>
diff -c &lt;oldfile&gt &lt;newfile&gt; diff -c &lt;oldfile&gt &lt;newfile&gt;
</verb></tscreen> </verb></tscreen>
@ -93,39 +88,36 @@ or
<tscreen><verb> <tscreen><verb>
diff -c -r &lt;olddir&gt &lt;newdir&gt; diff -c -r &lt;olddir&gt &lt;newdir&gt;
</verb></tscreen> </verb></tscreen>
See the man page for <tt>diff(1)</tt> for more details would generate such a set of context diffs for the given source file
on producing both context and recursive context diffs. 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 Once you have a set of diffs (which you may test with the
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 <tt>patch(1)</tt> command), you should bundle them up in an
email message and send it, along with a brief description of email message and send it, along with a brief description of
what the diffs are for, to what the diffs are for, to
<tt>&lt;hackers@freebsd.org&gt;</tt>. Someone will very <tt>&lt;hackers@freebsd.org&gt;</tt>. Someone will very
likely get back in touch with you in 24 hours or less, 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 If your changes don't express themselves well as diffs alone
(e.g. you've perhaps added, deleted or renamed files as well) (e.g. you've perhaps added, deleted or renamed files as well)
then you may be better off bundling any new files, diffs and then you may be better off bundling any new files, diffs and
instructions for deleting/renaming any others into a instructions for deleting/renaming others into a <tt>tar</tt>
<tt>tar</tt> file and running the <tt>uuencode(1)</tt> program file and running the <tt>uuencode(1)</tt> program on it before
on it before sending the output of that to sending the output of that to <tt>&lt;hackers@freebsd.org&gt;</tt>.
<tt>&lt;hackers@freebsd.org&gt;</tt>. See the man pages on See the man pages on <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more
<tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more info on information on bundling files this way.
bundling files through the mail this way.
If your change is of a potentially sensitive nature, for If your change is of a potentially sensitive nature, e.g.
example you're unsure of copyright issues governing its you're unsure of copyright issues governing its further distribution
further distribution, or you're simply not ready to release it or you're simply not ready to release it without a tighter review first,
without a tighter review first, then you should send it to then you should send it to <tt>&lt;core@freebsd.org&gt;</tt> rather than
<tt>&lt;core@freebsd.org&gt;</tt> rather than
<tt>&lt;hackers@freebsd.org&gt;</tt>. The core mailing list <tt>&lt;hackers@freebsd.org&gt;</tt>. The core mailing list
reaches a much smaller group of people who do much of the reaches a much smaller group of people who do much of the
day-to-day work on FreeBSD. Note that this group is also day-to-day work on FreeBSD. Note that this group is also
<em>very busy</em> and so you should only mail to them <em>very busy</em> and so you should only send mail to them
in cases where mailing to hackers truly is impractical. in cases where mailing to hackers is truly impractical.
<sect><heading>Contributions of new code</heading> <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, work, or the addition of an important new feature to FreeBSD,
it becomes almost always necessary to either send changes as it becomes almost always necessary to either send changes as
uuencoded tar files or upload them to our ftp site <url uuencoded tar files or upload them to our ftp site <url
url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> where url="ftp://ftp.freebsd.org/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 When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights copyrights also invariably comes up. Acceptable copyrights
for code included in FreeBSD are: for code included in FreeBSD are:
<enum> <enum>
<item>Contributions under the BSD copyright <item>The BSD copyright. This copyright is most preferred
are greatly preferred due to its ``no strings attached'' due to its ``no strings attached'' nature and general
nature and general attractiveness to commercial enterprises attractiveness to commercial enterprises. Far from
who might then be inclined to invest something of their own 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. into FreeBSD.
<item>Contributions under the GNU Public License, or ``GPL''. This is <item>The GNU Public License, or ``GPL''. This license isn't quite
not quite as popular a solution for us, due to as popular with us due to the amount of extra effort demanded
the amount of extra effort demanded of anyone of anyone using the code for commercial purposes, but given
using the code for commercial purposes. However, given the the sheer quantity of GPL'd code we currently require (compiler,
sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc) it would be silly to refuse
assembler, text formatter, etc), it would be silly to pretend additional contributions under this license. Code under the GPL
that we couldn't deal with the GPL at all and so we have become also goes into a different part of the tree, that being
more willing to accept code with either the BSD or the GPL <tt>/sys/gnu</tt> or <tt>/usr/src/gnu</tt>, and is therefore
copyright. Code under the GPL also goes into a different part easily identifable to anyone for whom the GPL presents a problem.
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> </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 text at the very beginning of every source code file you wish
to protect, replacing the text between the `<tt>%%</tt>' with to protect, replacing the text between the `<tt>%%</tt>' with
the appropriate information. 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 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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> </verb></tscreen>
For your convenience, a copy of this text can be found in For your convenience, a copy of this text can be found in
<tt>/usr/share/examples/etc/bsd-style-copyright</tt>. <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> <sect><heading>Porting of software</heading>
<p>The porting of freely available software, while perhaps not as <p>The porting of freely available software, while perhaps not as
gratifying as developing your own package from scratch, is still gratifying as developing your own from scratch, is still a vital part
a vital part of FreeBSD's growth and of great usefulness to those of FreeBSD's growth and of great usefulness to those who wouldn't
who wouldn't otherwise know where to turn for it. All ported otherwise know where to turn for it. All ported software is organized
software is organized into a hierarchy know as ``the ports into a carefully organized hierarchy know as ``the ports collection''.
collection''. This collection enables a new user to get a The collection enables a new user to get a quick and complete overview
complete overview of what's available in a short time, and with a of what's available for FreeBSD in an easy-to-compile form. It also
logical framework. The ports collection also saves saves considerable space by not actually containing the the majority
considerable space by not actually containing the the majority of of the sources being ported, but merely those differences required for
the sources being ported. See <ref id="ports" name="The ports running under FreeBSD. See <ref id="ports" name="The ports
collection"> for more information on using the ports collection collection"> for more information on using the ports collection and
and <ref id="porting" name="Porting applications"> for <ref id="porting" name="Porting applications"> for guidelines on
guidelines on creating new ports. You may also send mail to creating new ports. You may also send mail to
<tt>&lt;ports@freebsd.org&gt;</tt>. <tt>&lt;ports@freebsd.org&gt;</tt>.
Whichever way you decide to contribute, we hope you'll find it an Whichever way you decide to contribute, we hope you'll find it an
enjoyable process and also realize how valuable your enjoyable and rewarding process. Such contributions are also very
contributions are to the project! FreeBSD is one of those great valuable to FreeBSD's continued progress, and as a free software
projects where the more we all put in, the more we all get back effort, the more we all put in the more we all get back out of it!
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!