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

<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<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-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 <link
	    linkend="staff-core">Core team</link> 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 <link 
              linkend="staff-core">Core team</link> decides per case if it
	      should be commented out or not.  The <link
	      linkend="staff-core">Core team</link> can, of course, change
	      their minds later on.</para>
          </listitem>

          <listitem>
            <para>The <link linkend="staff-who">Release Engineer</link>
              decides whether or not it goes in to the release.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>User-land files;</para>

        <orderedlist>
          <listitem>
            <para>The <link linkend="staff-core">Core team</link> decides if
              the code should be part of <command>make world</command>.</para>
          </listitem>
         
          <listitem>
            <para>The <link linkend="staff-who">Release Engineer</link>
              decides if it goes in to the release.</para>
          </listitem>
        </orderedlist>
      </listitem>
    </orderedlist>
  </sect1>
  
  <sect1 id="policies-shlib">
    <title>Shared Libraries</title>
    
    <para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;  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: ("../book.sgml" "part" "chapter")
     End:
-->