138 lines
6.0 KiB
Plaintext
138 lines
6.0 KiB
Plaintext
<!-- $Id: policies.sgml,v 1.2 1996/07/03 04:23:26 mpp 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</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 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's 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>
|