188 lines
8.1 KiB
Plaintext
188 lines
8.1 KiB
Plaintext
<!-- $Id$ -->
|
|
<!-- 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>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>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 updated, these are not part of the
|
|
build 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) 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 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.
|
|
|
|
<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 README.FreeBSD
|
|
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>
|
|
|
|
<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.
|