doc/handbook/policies.sgml

<!-- $Id: policies.sgml,v 1.18 1998-09-13 09:09:39 obrien Exp $ -->
<!-- The FreeBSD Documentation Project -->

<chapt><heading>Source Tree Guidelines and Policies
<label id="policies">
</heading>

<p><em>Contributed by &a.phk;.</em>

This chapter documents various guidelines and policies in force
for the FreeBSD source tree.

<sect><heading>MAINTAINER on Makefiles
<label id="policies:maintainer">
</heading>

<p>June 1996.

<p>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

<verb>
	MAINTAINER= email-addresses
</verb>

<p>line to the makefiles covering this portion of the source tree.

<p>The semantics of this are as follows:

<p>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.

<p>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.

<p>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.

<sect><heading>Contributed Software</heading>
<p><em>Contributed by &a.phk; and &a.obrien;.</em>

<p>June 1996.

<p>Some parts of the FreeBSD distribution consist of software that
is actively being maintained outside the FreeBSD project.  For
historical reasons, we call this <em>contributed</em> software.  Some
examples are perl, gcc and patch.

<p>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.

<p>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.

<p>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.

<p>Please Note: 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 <em>strongly discouraged</em> on files that
are still tracking the vendor branch.  "Spelling fixes" are explicitly
included here under the "cosmetic" 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.

<p>The <tt>Tcl</tt> embedded programming language will be used as example
of how this model works:

<p><verb>src/contrib/tcl</verb> 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 "mac", "win" and "compat"
subdirectories were eliminated before the import

<p><verb>src/lib/libtcl</verb> contains only a "bmake style" Makefile that uses
the standard bsd.lib.mk makefile rules to produce the library and
install the documentation.

<p><verb>src/usr.bin/tclsh</verb> contains only a bmake style Makefile which will
produce and install the "tclsh" program and its associated man-pages
using the standard bsd.prog.mk rules.

<p><verb>src/tools/tools/tcl_bmake</verb> 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.

<p>The important thing here is that the "src/contrib/tcl" 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 "works out".  CVS is not forgiving
of import accidents and a fair amount of effort is required to back
out major mistakes.

<p>Because of the previously mentioned 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.

<p>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 <em>not</em> be removed.

<p>If it seems easier, the "bmake" makefiles 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
src/tools directory along with the port itself so that it is available
to future maintainers.

<p>In the src/contrib/tcl level directory, a file called FREEBSD-upgrade
should be added and it should states things like:

<itemize>
 <item> Which files have been left out
 <item> Where the original distribution was obtained from and/or the official
   master site.
 <item> Where to send patches back to the original authors
 <item> Perhaps an overview of the FreeBSD-specific changes that have been made.
</itemize>

<p>However, please do not import FREEBSD-upgrade with the contributed source.  
Rather you should ``cvs add FREEBSD-upgrade ; cvs ci'' after the
initial import.  Example wording from ``src/contrib/cpio'' is below:

<verb>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</verb>


<sect><heading>Shared Libraries
<label id="policies:shlib">
</heading>

<p><em>Contributed by &a.asami;, &a.peter;, and &a.obrien;.
  <newline>9 December 1996.</em></p>

  <p>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.

  <p>The three principles of shared library building are:

  <itemize>
    <item>Start from 1.0
    <item>If there is a change that is backwards compatible, bump
          minor number
    <item>If there is an incompatible change, bump major number
  </itemize>

  <p>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.

  <p>Stick to version numbers of the form major.minor (x.y).  Our dynamic
    linker does not handle version numbers of the form x.y.z well.  Any
    version number after the ``y'' (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, ld.so will link with the higher one.  Ie: if you link with
    libfoo.so.3.3.3, the linker only records 3.3 in the headers, and will
    link with anything starting with libfoo.so.3.(anything >= 3).(highest
    available).
  <p>Note that ld.so will always use the highest "minor" revision.
    Ie: it will use libc.so.2.2 in preference to libc.so.2.0, even if the
    program was initially linked with libc.so.2.0.

  <p>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 Makefile'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 Makefile to be updated, and any subsequent changes
    will not.