Add an appendix with policies and insert the maintainer & contrib

policies there.
This commit is contained in:
Poul-Henning Kamp 1996-06-30 18:01:25 +00:00
parent c003550d72
commit 6b830c00df
Notes: svn2git 2020-12-20 02:59:44 +00:00
svn path=/head/; revision=16855
4 changed files with 153 additions and 4 deletions

View File

@ -1,4 +1,4 @@
# $Id: Makefile,v 1.12 1996/05/14 20:31:49 rich Exp $
# $Id: Makefile,v 1.13 1996/06/07 15:56:34 alex Exp $
SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml
SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml
@ -7,7 +7,7 @@ SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml
SRCS+= firewalls.sgml glossary.sgml goals.sgml
SRCS+= handbook.sgml history.sgml hw.sgml install.sgml kerberos.sgml
SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml
SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml
SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml
SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml quotas.sgml relnotes.sgml
SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml
SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml

View File

@ -1,4 +1,4 @@
<!-- $Id: handbook.sgml,v 1.47 1996/05/15 15:17:25 jfieber Exp $ -->
<!-- $Id: handbook.sgml,v 1.48 1996/05/16 23:17:58 mpp Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@ -159,6 +159,7 @@ name="FreeBSD FTP server"> or one of the numerous
&bibliography;
&eresources;
&contrib;
&policies;
&pgpkeys;
<!-- &glossary; -->

View File

@ -0,0 +1,147 @@
<!-- $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 sourcetree.
<sect><heading>MAINTAINER on Makefiles</heading>
<p>June 1996.
<p>If a particular subpart of the FreeBSD 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 piece of subpart of the tree.
<p>The semantics of this is as follows:
<p>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer PRs pertaining
to that piece of the code, and in the case of contrib software,
for tracking new versions, as appropriate.
<p>Commits to the directories covered by this shall be sent to the
maintainer for review. Only if the maintainer does not respond
for un unacceptable period of time, to several emails, will it be
acceptable to commit changes without review by the maintainer.
<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 to be a group of people.
<p> Some software distributions have attacked this problem by
providing configuration scripts. Some of these are very clever, but
they have an unfortunate tendency to triumphantly announce that your
system is something you've never heard of and then ask you lots of
questions that sound like a final exam in system-level Unix
programming (``Does your system's gethitlist function return a const
pointer to a fromboz or a pointer to a const fromboz? Do you have
Foonix style unacceptable exception handling? And if not, why not?'').
<p> Fortunately, with the Ports collection, all the hard work involved
has already been done, and you can just type 'make install' and get a
working program.
<sect><heading>contributed software</heading>
<p>June 1996.
<p>Some parts of the FreeBSD distribution consists of software that
is actively being maintained outside the FreeBSD project. For
historical reasons, we call this "contributed" 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 contrib 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 "Tcl" embeddable 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-scrips 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
imports 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 dist 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 >not< 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>

View File

@ -1,4 +1,4 @@
<!-- $Id: sections.sgml,v 1.12 1996/05/14 20:31:53 rich Exp $ -->
<!-- $Id: sections.sgml,v 1.13 1996/06/07 15:56:40 alex Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!-- Entities containing all the pieces of the handbook are -->
@ -32,6 +32,7 @@
<!ENTITY nfs SYSTEM "nfs.sgml">
<!ENTITY nutshell SYSTEM "nutshell.sgml">
<!ENTITY pgpkeys SYSTEM "pgpkeys.sgml">
<!ENTITY policies SYSTEM "policies.sgml">
<!ENTITY porting SYSTEM "porting.sgml">
<!ENTITY ports SYSTEM "ports.sgml">
<!ENTITY ppp SYSTEM "ppp.sgml">