Contributed by &a.phk;. This chapter documents various guidelines and policies in force for the FreeBSD source tree. MAINTAINER on Makefiles

June 1996.

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 MAINTAINER= email-addresses

line to the makefiles covering this portion of the source tree.

The semantics of this are as follows:

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.

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.

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. Contributed software

June 1996.

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.

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 updated, these are not part of the build 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) 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 some unfortunate 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 "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/tcl level directory, a file called README.FreeBSD 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. Shared libraries

Contributed by &a.asami;, &a.peter;, and &a.obrien;. 9 December 1996.

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.

The three principles of shared library building are: Start from 1.0 If there is a change that is backwards compatible, bump minor number If there is an incompatible change, bump major number

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.

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

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.

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.