diff options
Diffstat (limited to 'share/doc/handbook/policies.sgml')
| -rw-r--r-- | share/doc/handbook/policies.sgml | 230 |
1 files changed, 0 insertions, 230 deletions
diff --git a/share/doc/handbook/policies.sgml b/share/doc/handbook/policies.sgml deleted file mode 100644 index 094de26..0000000 --- a/share/doc/handbook/policies.sgml +++ /dev/null @@ -1,230 +0,0 @@ -<!-- $Id: policies.sgml,v 1.13 1997/04/03 01:07:38 max 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 -<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 FREEBSD-upgrade -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> - -<p>However, please do not import FREEBSD-upgrade with the contributed source. -Rather you should ``cvs add FREEBSD-upgrade ; cvs ci'' after the -initial import. Example wording from ``src/contrib/cpio'' is below: - -<verb>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. - -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 -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU v<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU v2.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</verb> - - -<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. |
