path: root/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml

    <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><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para>
    
	<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 &ldquo;official&rdquo; 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
	  &ldquo;official&rdquo; 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. &ldquo;Spelling
	fixes&rdquo; are explicitly included here under the
	&ldquo;cosmetic&rdquo; 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 "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 and without RCS keyword expansion) 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 &ldquo;works out&rdquo;. 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 &ldquo;official&rdquo; 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&lt;version&gt;' \
                        src/contrib/cpio GNU cpio_&lt;version&gt;

           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 &ldquo;micro&rdquo; 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 &gt;=
	    3)</replaceable>.<replaceable>(highest available)</replaceable>.</para>

	<note>
	  <para><command>ld.so</command> will always use the highest
	    &ldquo;minor&rdquo; 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-always-quote-attributes: t
     sgml-parent-document: ("../handbook.sgml" "part" "chapter")
     End:
-->