From ga9@buffy.york.ac.uk  Mon Jul 28 09:27:07 2008
Return-Path: <ga9@buffy.york.ac.uk>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 1D63E106567B
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jul 2008 09:27:07 +0000 (UTC)
	(envelope-from ga9@buffy.york.ac.uk)
Received: from mail-gw2.york.ac.uk (mail-gw2.york.ac.uk [144.32.128.247])
	by mx1.freebsd.org (Postfix) with ESMTP id BD80B8FC19
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jul 2008 09:27:06 +0000 (UTC)
	(envelope-from ga9@buffy.york.ac.uk)
Received: from mail-gw6.york.ac.uk (mail-gw6.york.ac.uk [144.32.129.26])
	by mail-gw2.york.ac.uk (8.13.6/8.13.6) with ESMTP id m6S9R2FP020528
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jul 2008 10:27:02 +0100 (BST)
Received: from buffy-128.york.ac.uk ([144.32.128.160] helo=buffy.york.ac.uk)
	by mail-gw6.york.ac.uk with esmtps (TLSv1:AES256-SHA:256)
	(Exim 4.68)
	(envelope-from <ga9@buffy.york.ac.uk>)
	id 1KNP0Q-0003dl-Ja
	for FreeBSD-gnats-submit@freebsd.org; Mon, 28 Jul 2008 10:27:02 +0100
Received: from buffy.york.ac.uk (localhost [127.0.0.1])
	by buffy.york.ac.uk (8.14.2/8.14.2) with ESMTP id m6S9R2oD063283
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jul 2008 10:27:02 +0100 (BST)
	(envelope-from ga9@buffy.york.ac.uk)
Received: (from ga9@localhost)
	by buffy.york.ac.uk (8.14.2/8.14.2/Submit) id m6S9R2Hc063282;
	Mon, 28 Jul 2008 10:27:02 +0100 (BST)
	(envelope-from ga9)
Message-Id: <200807280927.m6S9R2Hc063282@buffy.york.ac.uk>
Date: Mon, 28 Jul 2008 10:27:02 +0100 (BST)
From: Gavin Atkinson <gavin@freebsd.org>
Reply-To: Gavin Atkinson <gavin@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] updates to developers handbook: policies section
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         126030
>Category:       docs
>Synopsis:       [patch] updates to developers handbook: policies section
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pgj
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Jul 28 09:30:01 UTC 2008
>Closed-Date:    Sun Aug 31 13:05:01 UTC 2008
>Last-Modified:  Sun Aug 31 13:10:04 UTC 2008
>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@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@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:
Responsible-Changed-From-To: freebsd-doc->pgj 
Responsible-Changed-By: pgj 
Responsible-Changed-When: Fri Aug 1 19:03:49 UTC 2008 
Responsible-Changed-Why:  
Grab. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=126030 
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Sun Aug 31 13:04:25 UTC 2008 
State-Changed-Why:  
I've committed the patch on behalf of Gabor. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=126030 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/126030: commit references a PR
Date: Sun, 31 Aug 2008 13:04:25 +0000 (UTC)

 keramida    2008-08-31 13:04:12 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/developers-handbook/policies 
                                                        chapter.sgml 
   Log:
   Various dev-handbook updates:
   
   1. Mention src/MAINTAINERS and how it works.
   2. Add a short suggestion about how to identify possible
      maintainers, inspired by the committers-guide
   3. Tcl has been removed from the base distribution, so it does
      not 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. Describe how vendor imports of Subversion code can be done (inspired
      by the Subversion docs of the Wiki).
   6. Use slightly more up to date release numbers when describing library
      version bumps.
   
   Submitted by:   Gavin Atkinson <gavin@freebsd.org>
   Patches by:     gavin, pgj, keramida
   PR:             docs/126030
   
   Revision  Changes    Path
   1.35      +345 -69   doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
