From 45316e458f0223cbcb4861ff688ab6a568ffe100 Mon Sep 17 00:00:00 2001 From: jkh Date: Thu, 2 Mar 1995 12:28:04 +0000 Subject: [PATCH] My first rough cut at a guide to new submitters. I started out answering someone's question and ended up writing an entire FAQ - I *hate* that! :-) --- share/FAQ/submitters.FAQ | 176 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 share/FAQ/submitters.FAQ diff --git a/share/FAQ/submitters.FAQ b/share/FAQ/submitters.FAQ new file mode 100644 index 000000000000..3534fb2f2ffa --- /dev/null +++ b/share/FAQ/submitters.FAQ @@ -0,0 +1,176 @@ +Thank you for your offer of this driver! It does look like it will be of +use to our many japanese users. I am appending a copy of my standard +"how to submit code to FreeBSD" document below. It hopefully explains +any questions you may have, though please do not hesitate in contacting +me should you have any further questions. + + Jordan + +-- 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 . Likewise, people with an interest + in such things (and a tolerance for a HIGH volume of mail!) may + subscribe by sendimg mail to . 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: + + + + +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 obsolute to use, or too divergent to allow for easy + re-integration. This can be minimized somewhat by subscribing to the + 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 or diff -c -r ). + + 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 . 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 . 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 rather than . 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 + . + + +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