diff options
Diffstat (limited to 'en/handbook/policies/chapter.sgml')
| -rw-r--r-- | en/handbook/policies/chapter.sgml | 297 |
1 files changed, 0 insertions, 297 deletions
diff --git a/en/handbook/policies/chapter.sgml b/en/handbook/policies/chapter.sgml deleted file mode 100644 index 4f675a2c0d..0000000000 --- a/en/handbook/policies/chapter.sgml +++ /dev/null @@ -1,297 +0,0 @@ - <chapter id="policies"> - <title>Source Tree Guidelines and Policies</title> - - <para><emphasis>Contributed by &a.phk;.</emphasis></para> - - <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> - - <para>June 1996.</para> - - <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 answer 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 and - 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 doesn't have to be a committer and it can easily be a group of - people.</para> - - </sect1> - - <sect1> - <title>Contributed Software</title> - - <para>June 1996.</para> - - <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 perl, gcc and patch.</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 “official” 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 - “official” 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> - - <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 "bmake 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) with as few FreeBSD-specific changes - as possible. The 'easy-import' tool on freefall 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 “works out”. CVS is not forgiving of import accidents and a fair - amount of effort is required to back out major mistakes.</para> - - <para>Because of some unfortunate design limitations with CVS's vendor - branches, it is required that “official” 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 - "committed", 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 states 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-shlib"> - <title>Shared Libraries</title> - - <para><emphasis>Contributed by &a.asami;, &a.peter;, and - &a.obrien;.<!-- <br> --> 9 December 1996.</emphasis></para> - - <para>If you are adding shared library support to a port or other - piece of software that doesn't 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</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 - 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> (ie. 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 “micro” revision, <command>ld.so</command> will link with the higher one. - Ie: 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 - “minor” revision. Ie: 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>For non-port libraries, it is also our policy to change the - shared library version number only once between releases. 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-shorttag: nil - sgml-always-quote-attributes: t - sgml-minimize-attributes: max - sgml-parent-document: ("../handbook.sgml" "part" "chapter") - End: ---> - |