o Remove chapter entities for the policies and kernel debug chapters.
Both of them have been moved to the Developers Handbook two years ago. o Delete the leftover files from the policies chapter. Reviewed by: murray Approved by: ceri (mentor)
This commit is contained in:
Simon L. B. Nielsen
parent
9b375974be
commit
331829158a
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=17792
3 changed files with 0 additions and 455 deletions
|
|
@ -46,8 +46,6 @@
|
|||
<!ENTITY % chap.advanced-networking "IGNORE">
|
||||
<!ENTITY % chap.mail "IGNORE">
|
||||
<!ENTITY % chap.cutting-edge "IGNORE">
|
||||
<!ENTITY % chap.policies "IGNORE">
|
||||
<!ENTITY % chap.kerneldebug "IGNORE">
|
||||
<!ENTITY % chap.linuxemu "IGNORE">
|
||||
<!ENTITY % chap.mirrors "IGNORE">
|
||||
<!ENTITY % chap.bibliography "IGNORE">
|
||||
|
|
@ -186,8 +184,6 @@
|
|||
<![ %chap.advanced-networking; [ &chap.advanced-networking; ]]>
|
||||
<![ %chap.mail; [ &chap.mail; ]]>
|
||||
<![ %chap.cutting-edge; [ &chap.cutting-edge; ]]>
|
||||
<![ %chap.policies; [ &chap.policies; ]]>
|
||||
<![ %chap.kerneldebug; [ &chap.kerneldebug; ]]>
|
||||
<![ %chap.linuxemu; [ &chap.linuxemu; ]]>
|
||||
</part>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,15 +0,0 @@
|
|||
#
|
||||
# Build the Handbook with just the content from this chapter.
|
||||
#
|
||||
# $FreeBSD$
|
||||
#
|
||||
|
||||
CHAPTERS= policies/chapter.sgml
|
||||
|
||||
VPATH= ..
|
||||
|
||||
MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/../../../..
|
||||
|
||||
.include "../Makefile"
|
||||
|
|
@ -1,436 +0,0 @@
|
|||
<!--
|
||||
The FreeBSD Documentation Project
|
||||
|
||||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter id="policies">
|
||||
<chapterinfo>
|
||||
<authorgroup>
|
||||
<firstname>Poul-Henning</firstname>
|
||||
<surname>Kamp</surname>
|
||||
<contrib>Contributed by </contrib>
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Source Tree Guidelines and Policies</title>
|
||||
|
||||
<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>
|
||||
<indexterm><primary>ports maintainer</primary></indexterm>
|
||||
|
||||
<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 to 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
|
||||
does not have to be a committer and it can easily be a group of
|
||||
people.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="policies-contributed">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Poul-Henning</firstname>
|
||||
<surname>Kamp</surname>
|
||||
<contrib>Contributed by </contrib>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<surname>O'Brien</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<!-- June 1996 -->
|
||||
</sect1info>
|
||||
|
||||
<title>Contributed Software</title>
|
||||
|
||||
<indexterm><primary>contributed software</primary></indexterm>
|
||||
|
||||
<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 <command>perl</command>, <command>gcc</command> and
|
||||
<command>patch</command>.</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
|
||||
<command>bmake</command> 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
|
||||
<hostid>freefall</hostid> 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 into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>User-land files:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<indexterm><primary>core team</primary></indexterm>
|
||||
<para>The <link linkend="staff-core">Core team</link> decides if
|
||||
the code should be part of <command>make world</command>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<indexterm><primary>release engineer</primary></indexterm>
|
||||
<para>The <link linkend="staff-who">Release Engineer</link>
|
||||
decides if it goes into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="policies-shlib">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Satoshi</firstname>
|
||||
<surname>Asami</surname>
|
||||
<contrib>Contributed by </contrib>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Peter</firstname>
|
||||
<surname>Wemm</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<surname>O'Brien</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<!-- 9 Dec 1996 -->
|
||||
</sect1info>
|
||||
|
||||
<title>Shared Libraries</title>
|
||||
|
||||
<para>If you are adding shared library support to a port or other piece of
|
||||
software that does not 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:
|
||||
-->
|
||||
Loading…
Reference in a new issue