diff options
Diffstat (limited to 'en_US.ISO8859-1/articles/contributing/article.xml')
| -rw-r--r-- | en_US.ISO8859-1/articles/contributing/article.xml | 581 |
1 files changed, 581 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml new file mode 100644 index 0000000000..046d23e68f --- /dev/null +++ b/en_US.ISO8859-1/articles/contributing/article.xml @@ -0,0 +1,581 @@ +<?xml version="1.0" encoding="iso-8859-1" standalone="no"?> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN" + "../../../share/sgml/freebsd42.dtd" [ +<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/sgml/entities.ent"> +%entities; +]> + +<article lang='en'> + <articleinfo> + <title>Contributing to FreeBSD</title> + + <abstract> + <para>This article describes the different ways in which an + individual or organization may contribute to the FreeBSD + Project.</para> + </abstract> + + <authorgroup> + <author> + <firstname>Jordan</firstname> + <surname>Hubbard</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + + <legalnotice id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.ieee; + &tm-attrib.general; + </legalnotice> + + <pubdate>$FreeBSD$</pubdate> + + <releaseinfo>$FreeBSD$</releaseinfo> + </articleinfo> + + <indexterm><primary>contributing</primary></indexterm> + + <para>So you want to contribute to FreeBSD? That is great! FreeBSD + <emphasis>relies</emphasis> on the contributions of its user base + to survive. Your contributions are not only appreciated, they are + vital to FreeBSD's continued growth.</para> + + <para>Contrary to what some people might have you believe, you do + not need to be a hot-shot programmer or a close personal friend of + the FreeBSD core team to have your contributions accepted. A + large and growing number of international contributors, of greatly + varying ages and areas of technical expertise, develop FreeBSD. + There is always more work to be done than there are people + available to do it, and more help is always appreciated.</para> + + <para>The FreeBSD project is responsible for an entire operating + system environment, rather than just a kernel or a few scattered + utilities. As such, our <filename>TODO</filename> lists span a + very wide range of tasks: from documentation, beta testing and + presentation, to the system installer and highly specialized types + of kernel development. People of any skill level, in almost any + area, can almost certainly help the project.</para> + + <para>Commercial entities engaged in FreeBSD-related enterprises are + also encouraged to contact us. Do you need a special extension to + make your product work? You will find us receptive to your + requests, given that they are not too outlandish. Are you working + on a value-added product? Please let us know! We may be able to + work cooperatively on some aspect of it. The free software world + is challenging many existing assumptions about how software is + developed, sold, and maintained, and we urge you to at least give + it a second look.</para> + + <sect1 id="contrib-what"> + <title>What Is Needed</title> + + <para>The following list of tasks and sub-projects represents + something of an amalgam of various <filename>TODO</filename> + lists and user requests.</para> + + <sect2 id="non-programmer-tasks"> + <title>Ongoing Non-Programmer Tasks</title> + + <para>Many people who are involved in FreeBSD are not + programmers. The Project includes documentation writers, Web + designers, and support people. All that these people need to + contribute is an investment of time and a willingness to + learn.</para> + + <orderedlist> + <listitem> + <para>Read through the FAQ and Handbook periodically. If + anything is badly explained, out of date or even just + completely wrong, let us know. Even better, send us a fix + (SGML is not difficult to learn, but there is no objection + to ASCII submissions).</para> + </listitem> + + <listitem> + <para>Help translate FreeBSD documentation into your native + language. If documentation already exists for your + language, you can help translate additional documents or + verify that the translations are up-to-date. First take a + look at the <ulink + url="&url.books.fdp-primer;/translations.html">Translations + FAQ</ulink> in the FreeBSD Documentation Project Primer. + You are not committing yourself to translating every + single FreeBSD document by doing this — as a + volunteer, you can do as much or as little translation as + you desire. Once someone begins translating, others + almost always join the effort. If you only have the time + or energy to translate one part of the documentation, + please translate the installation instructions.</para> + </listitem> + + <listitem> + <para>Read the &a.questions; and &ng.misc; + occasionally (or even regularly). It can be very + satisfying to share your expertise and help people solve + their problems; sometimes you may even learn something new + yourself! These forums can also be a source of ideas for + things to work on.</para> + </listitem> + </orderedlist> + </sect2> + + <sect2 id="ongoing-programmer-tasks"> + <title>Ongoing Programmer Tasks</title> + + <para>Most of the tasks listed here require either a + considerable investment of time, or an in-depth knowledge of + the FreeBSD kernel, or both. However, there are also many + useful tasks which are suitable for <quote>weekend + hackers</quote>.</para> + + <orderedlist> + <listitem> + <para>If you run FreeBSD-CURRENT and have a good Internet + connection, there is a machine <hostid + role="fqdn">current.FreeBSD.org</hostid> which builds a + full release once a day—every now and again, try to + install the latest release from it and report any failures + in the process.</para> + </listitem> + + <listitem> + <para>Read the &a.bugs;. There might be a + problem you can comment constructively on or with patches + you can test. Or you could even try to fix one of the + problems yourself.</para> + </listitem> + + <listitem> + <para>If you know of any bug fixes which have been + successfully applied to -CURRENT but have not been merged + into -STABLE after a decent interval (normally a couple of + weeks), send the committer a polite reminder.</para> + </listitem> + + <listitem> + <para>Move contributed software to + <filename class="directory">src/contrib</filename> in the + source tree.</para> + </listitem> + + <listitem> + <para>Make sure code in + <filename class="directory">src/contrib</filename> is up + to date.</para> + </listitem> + + <listitem> + <para>Build the source tree (or just part of it) with extra + warnings enabled and clean up the warnings.</para> + </listitem> + + <listitem> + <para>Fix warnings for ports which do deprecated things like + using <function>gets()</function> or including + <filename>malloc.h</filename>.</para> + </listitem> + + <listitem> + <para>If you have contributed any ports and you had to make + &os;-specific changes, send your patches + back to the original authors (this will make your life + easier when they bring out the next version).</para> + </listitem> + + <listitem> + <para>Get copies of formal standards like &posix;. You can + get some links about these standards at the <ulink + url="&url.base;/projects/c99/index.html">FreeBSD + C99 & POSIX Standards Conformance Project</ulink> web + site. Compare FreeBSD's behavior to that required by the + standard. If the behavior differs, particularly in subtle + or obscure corners of the specification, send in a PR + about it. If you are able, figure out how to fix it and + include a patch in the PR. If you think the standard is + wrong, ask the standards body to consider the + question.</para> + </listitem> + + <listitem> + <para>Suggest further tasks for this list!</para> + </listitem> + </orderedlist> + </sect2> + + <sect2> + <title>Work through the PR Database</title> + + <indexterm> + <primary>problem reports database</primary> + </indexterm> + + <para>The <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD + PR list</ulink> shows all the current active problem reports + and requests for enhancement that have been submitted by + FreeBSD users. The PR database includes both programmer and + non-programmer tasks. Look through the open PRs, and see if + anything there takes your interest. Some of these might be + very simple tasks that just need an extra pair of eyes to look + over them and confirm that the fix in the PR is a good one. + Others might be much more complex, or might not even have a + fix included at all.</para> + + <para>Start with the PRs that have not been assigned to anyone + else. If a PR is assigned to someone else, but it looks like + something you can handle, email the person it is assigned to + and ask if you can work on it—they might already have a + patch ready to be tested, or further ideas that you can + discuss with them.</para> + </sect2> + + <sect2> + <title>Pick one of the items from the <quote>Ideas</quote> + page</title> + + <para>The <ulink url="&url.base;/projects/ideas/">&os; list of + projects and ideas for volunteers</ulink> is also available + for people willing to contribute to the &os; project. The + list is being regularly updated and contains items for both + programmers and non-programmers with information about each + project.</para> + </sect2> + </sect1> + + <sect1 id="contrib-how"> + <title>How to Contribute</title> + + <para>Contributions to the system generally fall into one or more + of the following 5 categories:</para> + + <sect2 id="contrib-general"> + <title>Bug Reports and General Commentary</title> + + <para>An idea or suggestion of <emphasis>general</emphasis> + technical interest should be mailed to the &a.hackers;. + Likewise, people with an interest in such things (and a + tolerance for a <emphasis>high</emphasis> volume of mail!) may + subscribe to the &a.hackers;. + See <ulink + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The + FreeBSD Handbook</ulink> for more information about this and + other mailing lists.</para> + + <para>If you find a bug or are submitting a specific change, + please report it using the &man.send-pr.1; program or its + <ulink url="&url.base;/send-pr.html">WEB-based + equivalent</ulink>. Try to fill-in each field of the bug + report. Unless they exceed 65KB, include any patches directly + in the report. If the patch is suitable to be applied to the + source tree put <literal>[PATCH]</literal> in the synopsis of + the report. When including patches, <emphasis>do + not</emphasis> use cut-and-paste because cut-and-paste turns + tabs into spaces and makes them unusable. When patches are a + lot larger than 20KB, consider compressing them (eg. with + &man.gzip.1; or &man.bzip2.1;) and using &man.uuencode.1; to + include their compressed form in your problem report.</para> + + <para>After filing a report, you should receive confirmation + along with a tracking number. Keep this tracking number so + that you can update us with details about the problem by + sending mail to &a.bugfollowup;. Use + the number as the message subject, e.g. <literal>"Re: + kern/3377"</literal>. Additional information for any bug + report should be submitted this way.</para> + + <para>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 &man.send-pr.1; command, + then you may ask someone to file it for you by sending mail to + the &a.bugs;.</para> + + <para>See also <ulink + url="&url.articles.problem-reports;/article.html">this + article</ulink> on how to write good problem reports.</para> + </sect2> + + <sect2> + <title>Changes to the Documentation</title> + + <indexterm> + <primary>documentation submissions</primary> + </indexterm> + + <para>Changes to the documentation are overseen by the &a.doc;. + Please look at the + <ulink url="&url.books.fdp-primer;/index.html">FreeBSD + Documentation Project Primer</ulink> for complete + instructions. Send submissions and changes (even small ones + are welcome!) using &man.send-pr.1; as described in + <link linkend="contrib-general">Bug Reports and General + Commentary</link>.</para> + </sect2> + + <sect2> + <title>Changes to Existing Source Code</title> + + <indexterm><primary>FreeBSD-CURRENT</primary></indexterm> + + <para>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 FreeBSD + development. There is a special on-going release of FreeBSD + known as <quote>FreeBSD-CURRENT</quote> which is made + available in a variety of ways for the convenience of + developers working actively on the system. See + <ulink url="&url.books.handbook;/current-stable.html">The + FreeBSD Handbook</ulink> for more information about getting + and using FreeBSD-CURRENT.</para> + + <para>Working from older sources unfortunately means that your + changes may sometimes be too obsolete or too divergent for + easy re-integration into FreeBSD. Chances of this can be + minimized somewhat by subscribing to the &a.announce; and the + &a.current; lists, where discussions on the current state of + the system take place.</para> + + <para>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. This is done + with the &man.diff.1; command.</para> + + <para>The preferred &man.diff.1; format for submitting patches + is the unified output format generated by <command>diff + -u</command>. However, for patches that substantially + change a region of code, a context output format diff + generated by <command>diff -c</command> may be more readable + and thus preferable.</para> + + <indexterm> + <primary><command>diff</command></primary> + </indexterm> + + <para>For example:</para> + + <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen> + + <para>or</para> + + <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen> + + <para>would generate such a set of context diffs for the given + source file or directory hierarchy.</para> + + <para>Likewise,</para> + + <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen> + + <para>or</para> + + <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen> + + <para>would do the same, except in the unified diff + format.</para> + + <para>See the manual page for &man.diff.1; for more + details.</para> + + <para>Once you have a set of diffs (which you may test with the + &man.patch.1; command), you should submit them for inclusion + with FreeBSD. Use the &man.send-pr.1; program as described in + <link linkend="contrib-general">Bug Reports and General + Commentary</link>. <emphasis>Do not</emphasis> just send the + diffs to the &a.hackers; or they will get lost! We greatly + appreciate your submission (this is a volunteer project!); + because we are busy, we may not be able to address it + immediately, but it will remain in the PR database until we + do. Indicate your submission by including + <literal>[PATCH]</literal> in the synopsis of the + report.</para> + + <indexterm> + <primary><command>uuencode</command></primary> + </indexterm> + + <para>If you feel it appropriate (e.g. you have added, deleted, + or renamed files), bundle your changes into a + <command>tar</command> file and run the &man.uuencode.1; + program on it. Archives created with &man.shar.1; are also + welcome.</para> + + <para>If your change is of a potentially sensitive nature, + e.g. you are unsure of copyright issues governing its further + distribution or you are simply not ready to release it without + a tighter review first, then you should send it to &a.core; + directly rather than submitting it with &man.send-pr.1;. The + &a.core; reaches a much smaller group of people who + do much of the day-to-day work on FreeBSD. Note that this + group is also <emphasis>very busy</emphasis> and so you should + only send mail to them where it is truly necessary.</para> + + <para>Please refer to &man.intro.9; and &man.style.9; for + some information on coding style. We would appreciate it if + you were at least aware of this information before submitting + code.</para> + </sect2> + + <sect2> + <title>New Code or Major Value-Added Packages</title> + + <para>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 or upload them to a web or FTP site for + other people to access. If you do not have access to a web or + FTP site, ask on an appropriate FreeBSD mailing list for + someone to host the changes for you.</para> + + <para>When working with large amounts of code, the touchy + subject of copyrights also invariably comes up. Acceptable + copyrights for code included in FreeBSD are:</para> + + <orderedlist> + <listitem> + <indexterm><primary>BSD copyright</primary></indexterm> + + <para>The BSD copyright. This copyright is most preferred + due to its <quote>no strings attached</quote> 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.</para> + </listitem> + + <listitem> + <indexterm> + <primary>GPL</primary> + <see>GNU General Public License</see> + </indexterm> + + <indexterm> + <primary>GNU General Public License</primary> + </indexterm> + + <para>The GNU General Public License, or <quote>GPL</quote>. + This license is not 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 + <filename class="directory">/sys/gnu</filename> or + <filename class="directory">/usr/src/gnu</filename>, and + is therefore easily identifiable to anyone for whom the + GPL presents a problem.</para> + </listitem> + </orderedlist> + + <para>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.</para> + + <para>To place a <quote>BSD-style</quote> 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 <literal>%%</literal> with the appropriate + information:</para> + + <programlisting>Copyright (c) %%proper_years_here%% + %%your_name_here%%, %%your_state%% %%your_zip%%. + All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer as + the first lines of this file unmodified. +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +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$</programlisting> + + <para>For your convenience, a copy of this text can be found in + <filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para> + </sect2> + + <sect2> + <title>Money, Hardware or Internet Access</title> + + <para>We are always very happy to accept donations to further + the cause of the FreeBSD Project and, in a volunteer effort + like ours, a little can go a long way! Donations of hardware + are also very important to expanding our list of supported + peripherals since we generally lack the funds to buy such + items ourselves.</para> + + <sect3> + <title><anchor id="donations"/>Donating Funds</title> + + <para>The FreeBSD Foundation is a non-profit, tax-exempt + foundation established to further the goals of the FreeBSD + Project. As a 501(c)3 entity, the Foundation is generally + exempt from US federal income tax as well as Colorado State + income tax. Donations to a tax-exempt entity are often + deductible from taxable federal income.</para> + + <para>Donations may be sent in check form to: + <address> + The FreeBSD Foundation + <street>7321 Brockway Dr.</street> + <city>Boulder</city>, + <state>CO</state> <postcode>80303</postcode> + <country>USA</country> + </address></para> + + <para>The FreeBSD Foundation is now able to accept donations + through the web with PayPal. To place a donation, please + visit the Foundation + <ulink url="http://www.freebsdfoundation.org">web + site</ulink>.</para> + + <para>More information about the FreeBSD Foundation can be + found in <ulink + url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The + FreeBSD Foundation -- an Introduction</ulink>. To contact + the Foundation by email, write to + <email>bod@FreeBSDFoundation.org</email>.</para> + </sect3> + + <sect3> + <title>Donating Hardware</title> + <indexterm><primary>donations</primary></indexterm> + + <para>The FreeBSD Project happily accepts donations of + hardware that it can find good use for. If you are + interested in donating hardware, please contact the + <ulink url="&url.base;/donations/">Donations Liaison + Office</ulink>.</para> + </sect3> + + <sect3> + <title>Donating Internet Access</title> + + <para>We can always use new mirror sites for FTP, WWW or + <command>cvsup</command>. If you would like to be such a + mirror, please see the + <ulink url="&url.articles.hubs;/index.html">Mirroring + FreeBSD</ulink> article for more information.</para> + </sect3> + </sect2> + </sect1> + +</article> |