diff options
Diffstat (limited to 'handbook/submitters.sgml')
| -rw-r--r-- | handbook/submitters.sgml | 187 |
1 files changed, 86 insertions, 101 deletions
diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml index 3389f8a917..0107139f71 100644 --- a/handbook/submitters.sgml +++ b/handbook/submitters.sgml @@ -1,28 +1,28 @@ -<!-- $Id: submitters.sgml,v 1.2 1995-05-18 03:05:22 jfieber Exp $ --> +<!-- $Id: submitters.sgml,v 1.2.4.1 1995-09-17 11:19:43 davidg Exp $ --> <!-- The FreeBSD Documentation Project --> -<chapt><heading>Contributing to FreeBSD</heading> +<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 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! +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> @@ -41,8 +41,7 @@ are each, in their own way, quite significant to the project. volume of mail!) may subscribe to the hackers mailing list by sendimg mail to <tt><majordomo@freebsd.org></tt>. - See <ref id="eresources:mailing-lists" - name="mailing lists"> + 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 @@ -65,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><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. + 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 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 <oldfile> <newfile> </verb></tscreen> @@ -94,39 +88,36 @@ 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. + 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><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! + 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 + 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 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> @@ -135,42 +126,40 @@ diff -c -r <olddir> <newdir> 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. @@ -204,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.2 1995-05-18 03:05:22 jfieber Exp $ + $Id: submitters.sgml,v 1.2.4.1 1995-09-17 11:19:43 davidg Exp $ </verb></tscreen> For your convenience, a copy of this text can be found in <tt>/usr/share/examples/etc/bsd-style-copyright</tt>. @@ -213,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><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! - +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! |