docs/126030: [patch] updates to developers handbook: policies section
Gavin Atkinson
gavin at FreeBSD.org
Mon Jul 28 09:30:02 UTC 2008
>Number: 126030
>Category: docs
>Synopsis: [patch] updates to developers handbook: policies section
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Jul 28 09:30:01 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator: Gavin Atkinson
>Release: FreeBSD 7.0-STABLE amd64
>Organization:
>Environment:
System: FreeBSD buffy.york.ac.uk 7.0-STABLE FreeBSD 7.0-STABLE #3: Fri Jun 20 09:21:51 UTC 2008 root at buffy.york.ac.uk:/usr/obj/usr/src/sys/GENERIC amd64
>Description:
The "policies" section of the developers-handbook is outdated,
and doesn't document some recent and not-so-recent changes to FreeBSD:
1. The existence of src/MAINTAINERS is not mentioned
2. Add suggestion about how to identify possible maintainers, inspired
by the committers-guide
3. Tcl has been removed from the base distribution, so doesn't really
serve as a good example of contributed software any more
(obsoletes docs/50735)
4. Mention the growing use of FREEBSD-Xlist files for contrib software
5. Clarify about shared library bumps.
Note that this section really could do with mention and example of
versioned libraries, I'm not able to contribute that. Also, somebody
who knows how the CDDL fits with FreeBSD needs to update the "encumbered"
section to either show that it is treated like GPL software, or that it
isn't. Again, I've left that untouched as I don't know the answer.
>How-To-Repeat:
N/A
>Fix:
--- devh-policies.diff begins here ---
Index: doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml,v
retrieving revision 1.33
diff -u -r1.33 chapter.sgml
--- doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 28 Feb 2007 18:21:29 -0000 1.33
+++ doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 28 Jul 2008 09:15:12 -0000
@@ -24,17 +24,26 @@
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
<indexterm><primary>ports maintainer</primary></indexterm>
-
- <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
+
+ <para>If a particular portion of the FreeBSD <filename>src/</filename>
+ distribution is being maintained by a person or group of persons, this
+ is communicated through an entry in the <filename>src/MAINTAINERS</filename>
+ file.</para>
+
+ <para>Maintainers of ports within the Ports Collection express their
+ maintainership to the world by adding a <makevar>MAINTAINER</makevar>
+ line to the <filename>Makefile</filename> of the port in question:
<programlisting>MAINTAINER= email-addresses</programlisting>
- line to the <filename>Makefile</filename>s covering this portion of the
- source tree.</para>
+ </para>
- <para>The semantics of this are as follows:</para>
+ <para>For other parts of the repository, or for sections not listed as
+ having a maintainer, if you are unsure who the active maintainer might
+ be it may help to scan the output of <command>cvs log</command>
+ to see who has committed changes in the past.</para>
+
+ <para>The role of the maintainer is as follows:</para>
<para>The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answering problem reports
@@ -111,32 +120,27 @@
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>The <application>file</application> utility, used to identify the format
+ of a file, will be used as example of how this model works:</para>
- <para><filename>src/contrib/tcl</filename> contains the source as
+ <para><filename>src/contrib/file</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>
+ not applicable for FreeBSD can be removed. In the case of &man.file.1;, the
+ <filename>python</filename> subdirectory and <filename>lt*</filename> files
+ were eliminated before the import, amongst others.</para>
- <para><filename>src/lib/libtcl</filename> contains only a <application>bmake</application> style
+ <para><filename>src/lib/libmagic</filename> contains only a <application>bmake</application> 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
+ <para><filename>src/usr.bin/file</filename> contains only a <application>bmake</application> style
<filename>Makefile</filename> which will produce and install the
- <command>tclsh</command> program and its associated man-pages using the
+ <command>file</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
+ <filename>src/contrib/file</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. If there are any doubts on
@@ -168,7 +172,7 @@
<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
+ <para>In the <filename>src/contrib/file</filename> level directory, a file
called <filename>FREEBSD-upgrade</filename> should be added and it
should state things like:</para>
@@ -192,10 +196,8 @@
</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>
+ <para>Example wording from
+ <filename>src/contrib/cpio/FREEBSD-upgrade</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
@@ -235,6 +237,33 @@
inclusion in the next vendor release.
obrien at FreeBSD.org - 30 March 1997</programlisting>
+
+ <para>Another approach may also be taken for the list of files to be
+ excluded, which is especially useful when the list is large or
+ complicated or where imports happen frequently. By creating a file
+ <filename>FREEBSD-Xlist</filename> in the same directory the vendor source
+ is imported into, containing a list of filename patterns to be excluded one
+ per line, future imports can often be performed with:</para>
+
+ <screen>&prompt.user; <userinput>tar -X FREEBSD-Xlist -xzf <replaceable>vendor-source.tgz</replaceable></userinput>
+ </screen>
+
+ <para>An example of a <filename>FREEBSD-Xlist</filename> file, from
+ <filename>src/contrib/tcsh</filename>, is here:</para>
+
+ <programlisting>*/BUGS
+*/config/a*
+*/config/bs2000
+*/config/bsd
+*/config/bsdreno
+*/config/[c-z]*
+*/tests
+*/win32</programlisting>
+
+ <para>However, please do not import <filename>FREEBSD-upgrade</filename>
+ or <filename>FREEBSD-Xlist</filename> with the contributed source.
+ Rather you should <command>cvs add FREEBSD-upgrade FREEBSD-Xlist;
+ cvs ci</command> after the initial import.</para>
</sect1>
<sect1 id="policies-encumbered">
@@ -409,9 +438,9 @@
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
+ library version number at most once between releases. In addition, it is
our policy to change the major shared library version number only once
- between major OS releases (i.e. from 3.0 to 4.0). When you make a
+ between major OS releases (i.e. from 6.0 to 7.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
--- devh-policies.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list