diff options
Diffstat (limited to 'en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml | 434 |
1 files changed, 0 insertions, 434 deletions
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml deleted file mode 100644 index aec9e1649d..0000000000 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml +++ /dev/null @@ -1,434 +0,0 @@ -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> - -<chapter id="policies"> - <chapterinfo> - <authorgroup> - <author> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - <!-- June 1996 --> - </chapterinfo> - - <title>Source Tree Guidelines and Policies</title> - - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> - - <sect1 id="policies-maintainer"> - <title><makevar>MAINTAINER</makevar> on Makefiles</title> - <indexterm><primary>ports maintainer</primary></indexterm> - - <para>If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a - - <programlisting>MAINTAINER= email-addresses</programlisting> - - line to the <filename>Makefile</filename>s covering this portion of the - source tree.</para> - - <para>The semantics of this are as follows:</para> - - <para>The maintainer owns and is responsible for that code. This means - that he is responsible for fixing bugs and answering problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate.</para> - - <para>Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try to have the - changes reviewed by someone else if at all possible.</para> - - <para>It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - does not have to be a committer and it can easily be a group of - people.</para> - </sect1> - - <sect1 id="policies-contributed"> - <sect1info> - <authorgroup> - <author> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>David</firstname> - <surname>O'Brien</surname> - </author> - </authorgroup> - <!-- June 1996 --> - </sect1info> - - <title>Contributed Software</title> - - <indexterm><primary>contributed software</primary></indexterm> - - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are <application>sendmail</application>, <application>gcc</application> and <application>patch</application>.</para> - - <para>Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the <quote>official</quote> method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - <quote>official</quote> versions of the source by everyone (even without - cvs access). This will make it significantly easier to return changes - to the primary developers of the contributed software.</para> - - <para>Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions.</para> - - <note> - <para>Because of some unfortunate design limitations with the RCS file - format and CVS's use of vendor branches, minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch. <quote>Spelling - fixes</quote> are explicitly included here under the - <quote>cosmetic</quote> category and are to be avoided for files with - revision 1.1.x.x. The repository bloat impact from a single character - change can be rather dramatic.</para> - </note> - - <para>The <application>Tcl</application> embedded programming - language will be used as example of how this model works:</para> - - <para><filename>src/contrib/tcl</filename> contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - <filename>mac</filename>, <filename>win</filename> and - <filename>compat</filename> subdirectories were eliminated before the - import.</para> - - <para><filename>src/lib/libtcl</filename> contains only a <application>bmake</application> style - <filename>Makefile</filename> that uses the standard - <filename>bsd.lib.mk</filename> makefile rules to produce the library - and install the documentation.</para> - - <para><filename>src/usr.bin/tclsh</filename> contains only a bmake style - <filename>Makefile</filename> which will produce and install the - <command>tclsh</command> program and its associated man-pages using the - standard <filename>bsd.prog.mk</filename> rules.</para> - - <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of - shell-scripts that can be of help when the tcl software needs updating. - These are not part of the built or installed software.</para> - - <para>The important thing here is that the - <filename>src/contrib/tcl</filename> directory is created according to - the rules: it is supposed to contain the sources as distributed (on a - proper CVS vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. The 'easy-import' tool on - <hostid>freefall</hostid> will assist in doing the import, but if there are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it <quote>works out</quote>. CVS is not forgiving of - import accidents and a fair amount of effort is required to back out - major mistakes.</para> - - <para>Because of the previously mentioned design limitations with CVS's - vendor branches, it is required that <quote>official</quote> patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and <quote>committed</quote>, as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts.</para> - - <para>Since many packages contain files that are meant for compatibility - with other architectures and environments that FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall <emphasis>not</emphasis> be removed.</para> - - <para>If it seems easier, the <command>bmake</command> - <filename>Makefile</filename>s can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - <filename>src/tools</filename> directory along with the port itself so - that it is available to future maintainers.</para> - - <para>In the <filename>src/contrib/tcl</filename> level directory, a file - called <filename>FREEBSD-upgrade</filename> should be added and it - should state things like:</para> - - <itemizedlist> - <listitem> - <para>Which files have been left out.</para> - </listitem> - - <listitem> - <para>Where the original distribution was obtained from and/or the - official master site.</para> - </listitem> - - <listitem> - <para>Where to send patches back to the original authors.</para> - </listitem> - - <listitem> - <para>Perhaps an overview of the FreeBSD-specific changes that have - been made.</para> - </listitem> - </itemizedlist> - - <para>However, please do not import <filename>FREEBSD-upgrade</filename> - with the contributed source. Rather you should <command>cvs add - FREEBSD-upgrade ; cvs ci</command> after the initial import. Example - wording from <filename>src/contrib/cpio</filename> is below:</para> - - <programlisting>This directory contains virgin sources of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. New versions or -official-patch versions must be imported. Please remember to import with -"-ko" to prevent CVS from corrupting any vendor RCS Ids. - -For the import of GNU cpio 2.4.2, the following files were removed: - - INSTALL cpio.info mkdir.c - Makefile.in cpio.texi mkinstalldirs - -To upgrade to a newer version of cpio, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Remove the files listed above and any others that don't apply to - FreeBSD. - - 3. Use the command: - cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU cpio_<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -ko -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU cpio_2_4_2 - - 4. Follow the instructions printed out in step 3 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to cpio, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the GNU branch. - -All local changes should be submitted to "cpio@gnu.ai.mit.edu" for -inclusion in the next vendor release. - -obrien@FreeBSD.org - 30 March 1997</programlisting> - </sect1> - - <sect1 id="policies-encumbered"> - <title>Encumbered Files</title> - - <para>It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree.</para> - - <orderedlist> - <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> - </listitem> - - <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> - </listitem> - - <listitem> - <para>A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended).</para> - </listitem> - - <listitem> - <para>Any encumbered file requires specific approval from the - <ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> before it is added to the - CVS repository.</para> - </listitem> - - <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> - </listitem> - - <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> - </listitem> - - <listitem> - <para>Object files are named - <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> - </listitem> - - <listitem> - <para>Kernel files:</para> - - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> - </listitem> - - <listitem> - <para>Should always be in <filename>LINT</filename>, but the - <ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> decides per case if it - should be commented out or not. The - <ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> can, of course, change - their minds later on.</para> - </listitem> - - <listitem> - <para>The <firstterm>Release Engineer</firstterm> - decides whether or not it goes into the release.</para> - </listitem> - </orderedlist> - </listitem> - - <listitem> - <para>User-land files:</para> - - <orderedlist> - <listitem> - <indexterm><primary>core team</primary></indexterm> - <para>The <ulink url="&url.articles.contributors;/staff-core.html">Core team</ulink> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <indexterm><primary>release engineer</primary></indexterm> - <para>The <ulink url="&url.articles.contributors;/staff-who.html">Release Engineer</ulink> - decides if it goes into the release.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </sect1> - - <sect1 id="policies-shlib"> - <sect1info> - <authorgroup> - <author> - <firstname>Satoshi</firstname> - <surname>Asami</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Peter</firstname> - <surname>Wemm</surname> - </author> - <author> - <firstname>David</firstname> - <surname>O'Brien</surname> - </author> - </authorgroup> - <!-- 9 Dec 1996 --> - </sect1info> - - <title>Shared Libraries</title> - - <para>If you are adding shared library support to a port or other piece of - software that does not have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software.</para> - - <para>The three principles of shared library building are:</para> - - <itemizedlist> - <listitem> - <para>Start from <literal>1.0</literal></para> - </listitem> - - <listitem> - <para>If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number)</para> - </listitem> - - <listitem> - <para>If there is an incompatible change, bump major number</para> - </listitem> - </itemizedlist> - - <para>For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax, etc. will force the major version number to change.</para> - - <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out - dynamic linker does not handle version numbers of the form - <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> - well. Any version number after the <replaceable>y</replaceable> - (i.e. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the <quote>micro</quote> revision, - <command>ld.so</command> will link with the higher one. That is, if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(highest - available)</replaceable>.</para> - - <note> - <para><command>ld.so</command> will always use the highest - <quote>minor</quote> revision. For instance, it will use - <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> - </note> - - <para>In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our <filename>Makefile</filename>s <quote>do the right thing</quote> - based on the type of system.</para> - - <para>For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is - our policy to change the major shared library version number only once - between major OS releases (i.e. from 3.0 to 4.0). When you make a - change to a system library that requires the version number to be - bumped, check the <filename>Makefile</filename>'s commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> |