5.2 Contributed Software

Contributed by Poul-Henning Kamp, David O'Brien, and Gavin Atkinson.

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 sendmail, 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 direct repository 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 the 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. The repository bloat impact from a single character change can be rather dramatic.

5.2.1 Vendor Imports with CVS

The file utility, used to identify the format of a file, will be used as example of how this model works:

src/contrib/file 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 file(1), the python subdirectory and files with the lt prefix were eliminated before the import, amongst others.

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

src/usr.bin/file contains a bmake style Makefile which will produce and install the file program and its associated man-pages using the standard bsd.prog.mk rules.

The important thing here is that the src/contrib/file directory is created according to the rules: it is supposed to contain the sources as distributed (on a proper vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes as possible. 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”.

Because of the previously mentioned design limitations with 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 than 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 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.

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

Example wording from src/contrib/groff/FREEBSD-upgrade is below:

$FreeBSD: src/contrib/groff/FREEBSD-upgrade,v 1.5.12.1 2005/11/15 22:06:18 ru Exp $

This directory contains virgin copies 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.

To upgrade to a newer version of groff, when it is available:
    1. Unpack the new version into an empty directory.
       [Do not make ANY changes to the files.]

    2. Use the command:
        cvs import -m 'Virgin import of FSF groff v<version>' \
            src/contrib/groff FSF v<version>

       For example, to do the import of version 1.19.2, I typed:
        cvs import -m 'Virgin import of FSF groff v1.19.2' \
            src/contrib/groff FSF v1_19_2

    3. Follow the instructions printed out in step 2 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 groff, simply patch and commit to the main
branch (aka HEAD).  Never make local changes on the FSF branch.

All local changes should be submitted to Werner Lemberg <[email protected]> or 
Ted Harding <[email protected]> for inclusion in the next
vendor release.

[email protected] - 20 October 2005

Another approach my also be taken for the list of files to be excluded, which is especially useful when the list is large or complicated or where imports happen frequently. By creating a file FREEBSD-Xlist in the same directory the vendor source is imported into, containing a list of filename patterns to be excluded one per line, future imports can often performed with:

% tar -X FREEBSD-Xlist -xzf vendor-source.tgz

An example of a FREEBSD-Xlist file, from src/contrib/tcsh, is here:

*/BUGS
*/config/a*
*/config/bs2000
*/config/bsd
*/config/bsdreno
*/config/[c-z]*
*/tests
*/win32

Note: Please do not import FREEBSD-upgrade or FREEBSD-Xlist with the contributed source. Rather you should add these files after the initial import.

5.2.2 Vendor Imports with SVN

Contributed by Dag-Erling Smørgrav.

This section describes the vendor import procedure with Subversion in details.

  1. Preparing the Tree

    If this is your first import after the switch to SVN, you will have to flatten and clean up the vendor tree, and bootstrap merge history in the main tree. If not, you can safely omit this step.

    During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. For example, the foo vendor sources ended up in vendor/foo/dist/contrib/foo, but it is pointless and rather inconvenient. What we really want is to have the vendor source directly in vendor/foo/dist, like this:

    % cd vendor/foo/dist/contrib/foo
    % svn move $(svn list) ../..
    % cd ../..
    % svn remove contrib
    % svn propdel -R svn:mergeinfo
    % svn commit
    

    Note that, the propdel bit is necessary because starting with 1.5, Subversion will automatically add svn:mergeinfo to any directory you copy or move. In this case, you will not need this information, since you are not going to merge anything from the tree you deleted.

    Note: You may want to flatten the tags as well. The procedure is exactly the same. If you do this, put off the commit until the end.

    Check the dist tree and perform any cleanup that is deemed to be necessary. You may want to disable keyword expansion, as it makes no sense on unmodified vendor code. In some cases, it can be even be harmful.

    % svn propdel svn:keywords -R .
    % svn commit
    

    Bootstrapping of svn:mergeinfo on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed:

    % cd head/contrib/foo
    % svn merge --record-only svn_base/vendor/foo/dist@12345678 .
    % svn commit
    

    where svn_base is the base directory of your SVN repository, e.g. svn+ssh://svn.FreeBSD.org/base.

  2. Importing New Sources

    Prepare a full, clean tree of the vendor sources. With SVN, we can keep a full distribution in the vendor tree without bloating the main tree. Import everything but merge only what is needed.

    Note that you will need to add any files that were added since the last vendor import, and remove any that were removed. To facilitate this, you should prepare sorted lists of the contents of the vendor tree and of the sources you are about to import:

    % cd vendor/foo/dist
    % svn list -R | grep -v '/$' | sort > ../old
    % cd ../foo-9.9
    % find . -type f | cut -c 3- | sort > ../new
    

    With these two files, the following command will list list removed files (files only in old):

    % comm -23 ../old ../new
    

    While the command below will list added files (files only in new):

    % comm -13 ../old ../new
    

    Let's put this together:

    % cd vendor/foo/foo-9.9
    % tar cf - . | tar xf - -C ../dist
    % cd ../dist
    % comm -23 ../old ../new | xargs svn remove
    % comm -13 ../old ../new | xargs svn add
    

    Warning: If there are new directories in the new distribution, the last command will fail. You will have to add the directories, and run it again. Conversely, if any directories were removed, you will have to remove them manually.

    Check properties on any new files:

    • All text files should have svn:eol-style set to native.

    • All binary files should have svn:mime-type set to application/octet-stream, unless there is a more appropriate media type.

    • Executable files should have svn:executable set to *.

    • There should be no other properties on any file in the tree.

    Note: You are ready to commit, but you should first check the output of svn stat and svn diff to make sure everything is in order.

    Once you have committed the new vendor release, you should tag it for future reference. The best and quickest way is to do it directly in the repository:

    % svn copy svn_base/vendor/foo/dist svn_base/vendor/foo/9.9
    

    To get the new tag, you can update your working copy of vendor/foo.

    Note: If you choose to do the copy in the checkout instead, do not forget to remove the generated svn:mergeinfo as described above.

  3. Merging to -HEAD

    After you have prepared your import, it is time to merge. Option --accept=postpone tells SVN not to handle merge conflicts yet, because they will be taken care of manually:

    % cd head/contrib/foo
    % svn update
    % svn merge --accept=postpone svn_base/vendor/foo/dist
    

    Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been properly added or removed in the main tree. It is always a good idea to check differences against the vendor branch:

    % svn diff --no-diff-deleted --old=svn_base/vendor/foo/dist --new=.
    

    The --no-diff-deleted option tells SVN not to check files that are in the vendor tree but not in the main tree.

    Note: With SVN, there is no concept of on or off the vendor branch. If a file that previously had local modifications no longer does, just remove any left-over cruft, such as FreeBSD version tags, so it no longer shows up in diffs against the vendor tree.

    If any changes are required for the world to build with the new sources, make them now -- and test until you are satisfied that everything build and runs correctly.

  4. Commit

    Now, you are ready to commit. Make sure you get everything in one go. Ideally, you would have done all steps in a clean tree, in which case you can just commit from the top of that tree. That is the best way to avoid surprises. If you do it properly, the tree will move atomically from a consistent state with the old code to a consistent state with the new code.