396 lines
17 KiB
Text
396 lines
17 KiB
Text
<!--
|
|
The FreeBSD Documentation Project
|
|
|
|
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml,v 1.18 2000/08/20 17:18:43 chris Exp $
|
|
-->
|
|
|
|
<chapter id="policies">
|
|
<title>Source Tree Guidelines and Policies</title>
|
|
|
|
<para><emphasis>Contributed by &a.phk;.</emphasis></para>
|
|
|
|
<para>This chapter documents various guidelines and policies in force for
|
|
the FreeBSD source tree.</para>
|
|
|
|
<sect1 id="policies-maintainer">
|
|
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
|
|
|
|
<para>June 1996.</para>
|
|
|
|
<para>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
|
|
|
|
<programlisting>MAINTAINER= email-addresses</programlisting>
|
|
|
|
line to the <filename>Makefile</filename>s covering this portion of the
|
|
source tree.</para>
|
|
|
|
<para>The semantics of this are as follows:</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="policies-contributed">
|
|
<title>Contributed Software</title>
|
|
|
|
<para><emphasis>Contributed by &a.phk; and &a.obrien;. </emphasis></para>
|
|
|
|
<para>June 1996.</para>
|
|
|
|
<para>Some parts of the FreeBSD distribution consist of software that is
|
|
actively being maintained outside the FreeBSD project. For historical
|
|
reasons, we call this <emphasis>contributed</emphasis> software. Some
|
|
examples are perl, gcc and patch.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Since this is the case, after some debate one of these methods has
|
|
been selected as the <quote>official</quote> 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
|
|
<quote>official</quote> 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.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<note>
|
|
<para>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 <emphasis>strongly discouraged</emphasis> on
|
|
files that are still tracking the vendor branch. <quote>Spelling
|
|
fixes</quote> are explicitly included here under the
|
|
<quote>cosmetic</quote> 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.</para>
|
|
</note>
|
|
|
|
<para>The <application>TCL</application> embedded programming
|
|
language will be used as example of how this model works:</para>
|
|
|
|
<para><filename>src/contrib/tcl</filename> 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
|
|
<filename>mac</filename>, <filename>win</filename> and
|
|
<filename>compat</filename> subdirectories were eliminated before the
|
|
import</para>
|
|
|
|
<para><filename>src/lib/libtcl</filename> contains only a "bmake style"
|
|
<filename>Makefile</filename> that uses the standard
|
|
<filename>bsd.lib.mk</filename> makefile rules to produce the library
|
|
and install the documentation.</para>
|
|
|
|
<para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
|
|
<filename>Makefile</filename> which will produce and install the
|
|
<command>tclsh</command> program and its associated man-pages using the
|
|
standard <filename>bsd.prog.mk</filename> rules.</para>
|
|
|
|
<para><filename>src/tools/tools/tcl_bmake</filename> 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.</para>
|
|
|
|
<para>The important thing here is that the
|
|
<filename>src/contrib/tcl</filename> 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 <quote>works out</quote>. CVS is not forgiving of
|
|
import accidents and a fair amount of effort is required to back out
|
|
major mistakes.</para>
|
|
|
|
<para>Because of the previously mentioned design limitations with CVS's
|
|
vendor branches, it is required that <quote>official</quote> 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.</para>
|
|
|
|
<para>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 <emphasis>not</emphasis> be removed.</para>
|
|
|
|
<para>If it seems easier, the <command>bmake</command>
|
|
<filename>Makefile</filename>s 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
|
|
<filename>src/tools</filename> directory along with the port itself so
|
|
that it is available to future maintainers.</para>
|
|
|
|
<para>In the <filename>src/contrib/tcl</filename> level directory, a file
|
|
called <filename>FREEBSD-upgrade</filename> should be added and it
|
|
should states things like:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Which files have been left out</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Where the original distribution was obtained from and/or the
|
|
official master site.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Where to send patches back to the original authors</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Perhaps an overview of the FreeBSD-specific changes that have
|
|
been made.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>However, please do not import <filename>FREEBSD-upgrade</filename>
|
|
with the contributed source. Rather you should <command>cvs add
|
|
FREEBSD-upgrade ; cvs ci</command> after the initial import. Example
|
|
wording from <filename>src/contrib/cpio</filename> is below:</para>
|
|
|
|
<programlisting>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</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="policies-encumbered">
|
|
<title>Encumbered Files</title>
|
|
|
|
<para>It might occasionally be necessary to include an encumbered file in
|
|
the FreeBSD source tree. For example, if a device requires a small
|
|
piece of binary code to be loaded to it before the device will operate,
|
|
and we do not have the source to that code, then the binary file is said
|
|
to be encumbered. The following policies apply to including encumbered
|
|
files in the FreeBSD source tree.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Any file which is interpreted or executed by the system CPU(s)
|
|
and not in source format is encumbered.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any file with a license more restrictive than BSD or GNU is
|
|
encumbered.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A file which contains downloadable binary data for use by the
|
|
hardware is not encumbered, unless (1) or (2) apply to it. It must
|
|
be stored in an architecture neutral ASCII format (file2c or
|
|
uuencoding is recommended).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any encumbered file requires specific approval from the <link
|
|
linkend="staff-core">Core team</link> before it is added to the
|
|
CVS repository.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Encumbered files go in <filename>src/contrib</filename> or
|
|
<filename>src/sys/contrib</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The entire module should be kept together. There is no point in
|
|
splitting it, unless there is code-sharing with non-encumbered
|
|
code.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Object files are named
|
|
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Kernel files;</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Should always be referenced in
|
|
<filename>conf/files.*</filename> (for build simplicity).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Should always be in <filename>LINT</filename>, but the <link
|
|
linkend="staff-core">Core team</link> decides per case if it
|
|
should be commented out or not. The <link
|
|
linkend="staff-core">Core team</link> can, of course, change
|
|
their minds later on.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <link linkend="staff-who">Release Engineer</link>
|
|
decides whether or not it goes in to the release.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>User-land files;</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The <link linkend="staff-core">Core team</link> decides if
|
|
the code should be part of <command>make world</command>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <link linkend="staff-who">Release Engineer</link>
|
|
decides if it goes in to the release.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="policies-shlib">
|
|
<title>Shared Libraries</title>
|
|
|
|
<para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien; 9
|
|
December 1996.</emphasis></para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>The three principles of shared library building are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Start from <literal>1.0</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If there is a change that is backwards compatible, bump minor
|
|
number (note that ELF systems ignore the minor number)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If there is an incompatible change, bump major number</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Stick to version numbers of the form major.minor
|
|
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out
|
|
dynamic linker does not handle version numbers of the form
|
|
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
|
|
well. Any version number after the <replaceable>y</replaceable>
|
|
(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 <quote>micro</quote> revision,
|
|
<command>ld.so</command> will link with the higher one. Ie: if you link
|
|
with <filename>libfoo.so.3.3.3</filename>, the linker only records
|
|
<literal>3.3</literal> in the headers, and will link with anything
|
|
starting with
|
|
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >=
|
|
3)</replaceable>.<replaceable>(highest
|
|
available)</replaceable>.</para>
|
|
|
|
<note>
|
|
<para><command>ld.so</command> will always use the highest
|
|
<quote>minor</quote> revision. Ie: it will use
|
|
<filename>libc.so.2.2</filename> in preference to
|
|
<filename>libc.so.2.0</filename>, even if the program was initially
|
|
linked with <filename>libc.so.2.0</filename>.</para>
|
|
</note>
|
|
|
|
<para>In addition, our ELF dynamic linker does not handle minor version
|
|
numbers at all. However, one should still specify a major and minor
|
|
version number as our <filename>Makefile</filename>s "do the right thing"
|
|
based on the type of system.</para>
|
|
|
|
<para>For non-port libraries, it is also our policy to change the shared
|
|
library version number only once between releases. In addition, it is
|
|
our policy to change the major shared library version number only once
|
|
between major OS releases. Ie: X.0 to (X+1).0. When you make a
|
|
change to a system library that requires the version number to be
|
|
bumped, check the <filename>Makefile</filename>'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 <filename>Makefile</filename> to be updated, and any subsequent
|
|
changes will not.</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-declaration: "../chapter.decl"
|
|
sgml-indent-data: t
|
|
sgml-omittag: nil
|
|
sgml-always-quote-attributes: t
|
|
sgml-parent-document: ("../book.sgml" "part" "chapter")
|
|
End:
|
|
-->
|
|
|