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

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.

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.

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.

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 strongly discouraged 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.

The Tcl embedded programming
language will be used as example of how this model works:

src/contrib/tcl 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

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

src/usr.bin/tclsh 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.

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

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.

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.

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

If it seems easier, the bmakeMakefiles 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.

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

Which files have been left out

Where the original distribution was obtained from
and/or the official master site.

Where to send patches back to the original authors

Perhaps an overview of the FreeBSD-specific changes
that have been made.

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:

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