From linimon@lonesome.com  Thu Mar 11 23:09:25 2004
Return-Path: <linimon@lonesome.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id CFDD316A4CE; Thu, 11 Mar 2004 23:09:25 -0800 (PST)
Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 7209543D48; Thu, 11 Mar 2004 23:09:23 -0800 (PST)
	(envelope-from linimon@lonesome.com)
Received: from lonesome.lonesome.com (cs242743-143.austin.rr.com [24.27.43.143])
	(using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits))
	(No client certificate requested)
	by mail.soaustin.net (Postfix) with ESMTP
	id 9C4661472E; Fri, 12 Mar 2004 01:09:22 -0600 (CST)
Received: from lonesome.lonesome.com (localhost.lonesome.com [127.0.0.1])
	by lonesome.lonesome.com (8.12.9/8.12.9) with ESMTP id i2C79ic7019624;
	Fri, 12 Mar 2004 01:09:44 -0600 (CST)
	(envelope-from linimon@lonesome.lonesome.com)
Received: (from linimon@localhost)
	by lonesome.lonesome.com (8.12.9/8.12.9/Submit) id i2C79i2h019623;
	Fri, 12 Mar 2004 01:09:44 -0600 (CST)
	(envelope-from linimon)
Message-Id: <200403120709.i2C79i2h019623@lonesome.lonesome.com>
Date: Fri, 12 Mar 2004 01:09:44 -0600 (CST)
From: Mark Linimon <linimon@lonesome.com>
Reply-To: Mark Linimon <linimon@lonesome.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc: ports-developers@freebsd.org
Subject: [patch] document procedure to add a new ports category to Committer's Guide
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         64144
>Category:       docs
>Synopsis:       [patch] document procedure to add a new ports category to Committer's Guide
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    linimon
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 11 23:10:01 PST 2004
>Closed-Date:    Sun Apr 04 10:05:42 PDT 2004
>Last-Modified:  Sun Apr 04 10:05:42 PDT 2004
>Originator:     Mark Linimon
>Release:        FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #3: Thu Jan 22 20:41:05 CST 2004 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
	There is no documentation of all the steps that are involved
	in creating a new ports category.  The following patch, while
	incomplete, is at least a first attempt at it.

	Patches and other discussion (especially by the people who
	have been through the exercise before) are welcomed.
>How-To-Repeat:
	(n/a)
>Fix:

Index: article.sgml
===================================================================
RCS file: /mnt/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
retrieving revision 1.180
diff -u -r1.180 article.sgml
--- article.sgml	27 Feb 2004 15:23:15 -0000	1.180
+++ article.sgml	12 Mar 2004 06:57:35 -0000
@@ -2516,6 +2516,133 @@
       </qandadiv>
 
       <qandadiv>
+	<title>Creating a New Category</title>
+
+	<qandaentry>
+	  <question>
+	    <para>What is the procedure for creating a new category?</para>
+	  </question>
+
+	  <answer>
+	    <para>A developer who wishes to propose a new category
+	      should submit a detailed rationale for the new category,
+	      including why existing categories are not sufficient,
+	      and the list of ports proposed to move.</para>
+
+	    <para>Before submitting, keep in mind that there is a fair
+	      amount of work involved from multiple parties; that the
+	      changes affect everyone who wants to keep up-to-date with
+	      the entire ports tree; and that such proposals tend to
+	      attract controversy.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>What do I need to do?</para>
+	  </question>
+
+	  <answer>
+	    <para>The procedure is a strict superset of the one to
+	      repocopy individual ports (see above).</para>
+
+	    <para>File a PR in <application>GNATS</application>, listing the
+	      reasons for the category request.  Preferably, this should
+	      also include patches for <filename>Makefile</filename>s for
+	      the old ports, the <filename>Makefile</filename>s for their
+	      old categories, and the <makevar>VALID_CATEGORIES</makevar>
+	      definition in <filename>ports/Mk/bsd.port.mk</filename>.
+	      Assign the PR to <literal>portmgr</literal>.
+	      If &a.portmgr; approves it, it will be reassigned to
+	      <literal>cvs</literal>.  &a.cvs; will do a repository copy
+	      from the old to the new locations, and reassign the PR back
+	      to you.  Once everything is done, perform the following:</para>
+
+	    <itemizedlist>
+	      <listitem>
+		<para>When the repocopies have been finished:</para>
+
+		<procedure>
+		  <step>
+		    <para>Upgrade each copied port's
+		      <filename>Makefile</filename>.  Do not
+		      connect the new category to the build yet.</para>
+		  </step>
+
+		  <step>
+		    <para>On your own local system, test the proposed
+		      changes: first, comment out the
+		      <makevar>SUBDIR</makevar> entries in the old
+		      ports' categories' <filename>Makefile</filename>s;
+		      then, enable the Makefile for the new category in
+		      <filename>ports/Makefile</filename>.
+		      Run <command>make checksubdirs</command> in the
+		      affected category directories to check the
+		      <makevar>SUBDIR</makevar> entries.  Next, in
+		      the <filename>ports/</filename> directory, run
+		      <command>make index</command>.  This can take
+		      over 40 minutes on even modern systems; however,
+		      it is a necessary step to prevent problems for
+		      other people.</para>
+		  </step>
+
+		  <step>
+		    <para>Once this is done, you can commit the
+		      updated <filename>ports/Makefile</filename> to
+		      connect the new category to the build; and also
+		      commit the <filename>Makefile</filename> changes
+		      for the old category or categories.  The new
+		      category's <filename>pkg/COMMENT</filename>
+		      can be committed, too.</para>
+		  </step>
+
+		  <step>
+		    <para>Change all the affected module entries.</para>
+		  </step>
+
+		  <step>
+		    <para>Add appropriate entries to
+		      <filename>ports/MOVED</filename>.</para>
+		  </step>
+
+		  <step>
+		    <para>Update the instructions for
+		      <command>cvsup(1)</command> by modifying
+		      <filename>distrib/cvsup/sup/README</filename>
+		      and adding the following files into
+		      <filename>cvsup/sup/ports-categoryname</filename>:
+		      <filename>list.cvs</filename> and
+		      <filename>releases</filename>.</para>
+		  </step>
+
+		  <step>
+		    <para>Submit a PR to add the new category to
+		      the Porter's Handbook, and to add it to
+		      <filename>www/en/ports/categories</filename>,
+		      and assign it to <literal>docs</literal>.</para>
+		  </step>
+
+		  <step>
+		    <para>Submit a PR to request that the web
+		      page build be updated to reflect the new
+		      category.  The responsibility for doing this
+		      is not yet well established.</para>
+		  </step>
+
+		  <step>
+		    <para>Only once all the above have been done, and
+		      no one is any longer reporting problems with the
+		      new ports, should the old ports be deleted from
+		      their previous locations in the repository.</para>
+		  </step>
+		</procedure>
+	      </listitem>
+	    </itemizedlist>
+	  </answer>
+	</qandaentry>
+      </qandadiv>
+
+      <qandadiv>
 	<title>Miscellaneous Questions</title>
 
 	<qandaentry>
>Release-Note:
>Audit-Trail:

From: Ceri Davies <ceri@submonkey.net>
To: Mark Linimon <linimon@lonesome.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org, ports-developers@FreeBSD.org
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Fri, 12 Mar 2004 11:21:06 +0000

 On Fri, Mar 12, 2004 at 01:09:44AM -0600, Mark Linimon wrote:
 
 > +	  <answer>
 > +	    <para>The procedure is a strict superset of the one to
 > +	      repocopy individual ports (see above).</para>
 > +
 > +	    <para>File a PR in <application>GNATS</application>, listing the
 > +	      reasons for the category request.  Preferably, this should
 > +	      also include patches for <filename>Makefile</filename>s for
 > +	      the old ports, the <filename>Makefile</filename>s for their
 > +	      old categories, and the <makevar>VALID_CATEGORIES</makevar>
 > +	      definition in <filename>ports/Mk/bsd.port.mk</filename>.
 > +	      Assign the PR to <literal>portmgr</literal>.
 > +	      If &a.portmgr; approves it, it will be reassigned to
 > +	      <literal>cvs</literal>.  &a.cvs; will do a repository copy
 > +	      from the old to the new locations, and reassign the PR back
 > +	      to you.  Once everything is done, perform the following:</para>
 
 Mark,
 
 Is it desirable to put this into state repocopy?  If so, the paragraph
 above should probably restate that.
 
 Ceri
 -- 

From: Mark Linimon <linimon@lonesome.com>
To: Ceri Davies <ceri@submonkey.net>
Cc: Mark Linimon <linimon@lonesome.com>,
	<FreeBSD-gnats-submit@FreeBSD.org>, <ports-developers@FreeBSD.org>
Subject: Re: docs/64144: [patch] document procedure to add a new ports category
 to Committer's Guide
Date: Fri, 12 Mar 2004 06:16:30 -0600 (CST)

 > Is it desirable to put this into state repocopy?  If so, the paragraph
 > above should probably restate that.
 
 I don't know enough about how the repocopy state works to say one
 way or the other -- basically, I cloned it from the text in Section 2.
 
 I think kris was alluding to the fact that the text in Section 2
 needed some work -- I think you're probably in a better position
 to propose better wording than I am.  I documented the parts that
 I understood, but I have no doubt that there's some I just don't.
 As written, is was intended more as a spur to discussion.
 
 mcl
 
 

From: Oliver Eikemeier <eikemeier@fillmore-labs.com>
To: freebsd-gnats-submit@FreeBSD.org, linimon@lonesome.com
Cc:  
Subject: Re: docs/64144: [patch] document procedure to add a new ports category
 to Committer's Guide
Date: Fri, 19 Mar 2004 12:21:53 +0100

 I've added a new script to Tools, please add the line 
 
 run
   env PORTSDIR=/path/to/ports sh /usr/ports/Tools/scripts/chkorigin.sh
 and correct all errors
 
 probably immediately before or after running `make INDEX'.
 
 Thanks
     Oliver

From: Mark Linimon <linimon@lonesome.com>
To: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org
Cc: eik@FreeBSD.org
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Tue, 30 Mar 2004 12:33:26 -0600

 Here is a revised patch that incorporates feedback that I got from
 eik@, and my own slightly improved knowledge of both the underlying
 problems, and of DocBook.
 
 Index: article.sgml
 ===================================================================
 RCS 
 file: /mnt/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
 retrieving revision 1.180
 diff -u -r1.180 article.sgml
 --- article.sgml	27 Feb 2004 15:23:15 -0000	1.180
 +++ article.sgml	30 Mar 2004 18:32:36 -0000
 @@ -2516,6 +2516,173 @@
        </qandadiv>
  
        <qandadiv>
 +	<title>Creating a New Category</title>
 +
 +	<qandaentry>
 +	  <question>
 +	    <para>What is the procedure for creating a new category?</para>
 +	  </question>
 +
 +	  <answer>
 +	    <para>A developer who wishes to propose a new category
 +	      should submit a detailed rationale for the new category,
 +	      including why existing categories are not sufficient,
 +	      and the list of ports proposed to move.</para>
 +
 +	    <para>Before submitting, keep in mind that there is a fair
 +	      amount of work involved from multiple parties; that the
 +	      changes affect everyone who wants to keep up-to-date with
 +	      the entire ports tree; and that such proposals tend to
 +	      attract controversy.</para>
 +	  </answer>
 +	</qandaentry>
 +
 +	<qandaentry>
 +	  <question>
 +	    <para>What do I need to do?</para>
 +	  </question>
 +
 +	  <answer>
 +	    <para>The procedure is a strict superset of the one to
 +	      repocopy individual ports (see above).</para>
 +
 +	    <para>File a PR in <application>GNATS</application>, listing the
 +	      reasons for the category request.  Preferably, this should
 +	      also include patches for <filename>Makefile</filename>s for
 +	      the old ports, the <filename>Makefile</filename>s for their
 +	      old categories, and the <makevar>VALID_CATEGORIES</makevar>
 +	      definition in <filename>ports/Mk/bsd.port.mk</filename>.
 +	      Assign the PR to the &a.portmgr; (as <literal>portmgr</literal>).
 +	      If they approve it, it will be reassigned to &a.cvs; (as
 +	      <literal>cvs</literal>), who will do a repository copy from
 +	      the old to the new locations, and reassign the PR back to you.
 +	      Once everything is done, perform the following steps:</para>
 +
 +	      <procedure>
 +		<step>
 +		  <para>Upgrade each copied port's
 +		    <filename>Makefile</filename>.  Do not connect the
 +		    new category to the build yet.</para>
 +
 +		  <para>To do this, you will need to:
 +		    <procedure>
 +		      <step>
 +			<para>Change the port's <makevar>CATEGORIES</makevar>
 +			  (this was the point of the exercise, remember?)
 +			  The new category should be listed
 +			  <emphasis>first</emphasis>.</para>
 +		      </step>
 +
 +		      <step>
 +			<para>Do a <command>make -V PKGORIGIN</command> and
 +			  ensure that it is correct.  If you got the
 +			  previous step right, this should be fine.</para>
 +		      </step>
 +
 +		      <step>
 +			<para>Run a <command>make describe</command>.  Since
 +			  the top-level <command>make index</command> that
 +			  you will be running in a few steps is an interation
 +			  of <command>make describe</command> over the entire
 +			  ports hierarchy, catching any errors here will
 +			  save you having to re-run that step later on.</para>
 +		      </step>
 +		    </procedure>
 +		</step>
 +
 +		<step>
 +		  <para>Check that the <makevar>PKGORIGIN</makevar>s are
 +		    correct.  The ports system uses each port's
 +		    <makevar>CATEGORIES</makevar> entry to create
 +		    its <makevar>PKGORIGIN</makevar>, which is used to
 +		    connect installed packages to the port directory they
 +		    were built from. If this entry is wrong, common port
 +		    tools like &man.pkg.version.1; and
 +		    &man.portupgrade.1; fail.</para>
 +
 +		  <para>To do this, use the <filename></filename> tool, as
 +		    follows: <command>env
 +		    PORTSDIR=<replaceable>/path/to/ports</replaceable>
 +		    sh -e /usr/ports/Tools/scripts/chkorigin</command>.
 +		    It checks <emphasis>every</emphasis> port in the ports
 +		    tree, even those not connected to the build, so you can
 +		    run it directly after the repocopy.</para>
 +		</step>
 +
 +		<step>
 +		  <para>On your own local system, test the proposed
 +		    changes: first, comment out the
 +		    <makevar>SUBDIR</makevar> entries in the old
 +		    ports' categories' <filename>Makefile</filename>s;
 +		    then, enable building the new category in
 +		    <filename>ports/Makefile</filename>.
 +		    Run <command>make checksubdirs</command> in the
 +		    affected category directories to check the
 +		    <makevar>SUBDIR</makevar> entries.  Next, in
 +		    the <filename>ports/</filename> directory, run
 +		    <command>make index</command>.  This can take
 +		    over 40 minutes on even modern systems; however,
 +		    it is a necessary step to prevent problems for
 +		    other people.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Once this is done, you can commit the
 +		    updated <filename>ports/Makefile</filename> to
 +		    connect the new category to the build; and also
 +		    commit the <filename>Makefile</filename> changes
 +		    for the old category or categories.  The new
 +		    category's <filename>pkg/COMMENT</filename>
 +		    can be committed, too.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Change all the affected module entries in
 +		    <filename>CVSROOT-ports/modules</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Add appropriate entries to
 +		    <filename>ports/MOVED</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Update the instructions for
 +		    <command>cvsup(1)</command> by modifying
 +		    <filename>distrib/cvsup/sup/README</filename>
 +		    and adding the following files into
 +		    <filename>cvsup/sup/ports-categoryname</filename>:
 +		    <filename>list.cvs</filename> and
 +		    <filename>releases</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Submit a PR to add the new category both to the
 +		    <ulink 
 url="../../books/porters-handbook/makefile-categories.html#PORTING-CATEGORIES">
 +		    Porter's Handbook</ulink> and to the file
 +		    <filename>www/en/ports/categories</filename>,
 +		    and assign it to <literal>docs</literal>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Submit a PR to request that the web
 +		    page build be updated to reflect the new
 +		    category.  The responsibility for doing this
 +		    is not yet well established.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Only once all the above have been done, and
 +		    no one is any longer reporting problems with the
 +		    new ports, should the old ports be deleted from
 +		    their previous locations in the repository.</para>
 +		</step>
 +	      </procedure>
 +	  </answer>
 +	</qandaentry>
 +      </qandadiv>
 +
 +      <qandadiv>
  	<title>Miscellaneous Questions</title>
  
  	<qandaentry>
 

From: "Simon L. Nielsen" <simon@FreeBSD.org>
To: Mark Linimon <linimon@lonesome.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	eik@FreeBSD.org
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Tue, 30 Mar 2004 22:12:10 +0200

 --OgqxwSJOaUobr8KG
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On 2004.03.30 12:33:26 -0600, Mark Linimon wrote:
 > Here is a revised patch that incorporates feedback that I got from
 > eik@, and my own slightly improved knowledge of both the underlying
 > problems, and of DocBook.
 
 Looks good in general, but a few comments :
 
 [CUT]
 
 > +		<step>
 > +		  <para>On your own local system, test the proposed
 > +		    changes: first, comment out the
 > +		    <makevar>SUBDIR</makevar> entries in the old
 > +		    ports' categories' <filename>Makefile</filename>s;
 > +		    then, enable building the new category in
 > +		    <filename>ports/Makefile</filename>.
 > +		    Run <command>make checksubdirs</command> in the
 > +		    affected category directories to check the
 > +		    <makevar>SUBDIR</makevar> entries.  Next, in
 > +		    the <filename>ports/</filename> directory, run
 
 Should be :
 
 +		    the <filename class=3D"directory">ports/</filename> directory, run
 
 [CUT]
 
 > +		<step>
 > +		  <para>Update the instructions for
 > +		    <command>cvsup(1)</command> by modifying
 
 Here you should use &man.cvsup.1;.
 
 > +		    <filename>distrib/cvsup/sup/README</filename>
 > +		    and adding the following files into
 > +		    <filename>cvsup/sup/ports-categoryname</filename>:
 > +		    <filename>list.cvs</filename> and
 > +		    <filename>releases</filename>.</para>
 > +		</step>
 > +
 > +		<step>
 > +		  <para>Submit a PR to add the new category both to the
 > +		    <ulink=20
 > url=3D"../../books/porters-handbook/makefile-categories.html#PORTING-CATE=
 GORIES">
 > +		    Porter's Handbook</ulink> and to the file
 > +		    <filename>www/en/ports/categories</filename>,
 > +		    and assign it to <literal>docs</literal>.</para>
 
 If the category is set to "docs" there is no need to reassign it.  It
 will automatically be assigned to freebsd-doc.
 
 > +		</step>
 > +
 > +		<step>
 > +		  <para>Submit a PR to request that the web
 > +		    page build be updated to reflect the new
 > +		    category.  The responsibility for doing this
 > +		    is not yet well established.</para>
 > +		</step>
 
 Shouldn't this just be a "www" PR?  I'm not really sure what needs to be
 changed on the web pages?
 
 Of course the issue with the ports/ pages being based on a INDEX still
 exist...
 
 --=20
 Simon L. Nielsen
 FreeBSD Documentation Team
 
 --OgqxwSJOaUobr8KG
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.3 (FreeBSD)
 
 iD8DBQFAadSah9pcDSc1mlERAtxyAJ4/iyF6Ijqd7HIChWmqG4O7v1s8jgCfXkr/
 yRFadwmFGQsIUEEJQpbZA9w=
 =6K8P
 -----END PGP SIGNATURE-----
 
 --OgqxwSJOaUobr8KG--

From: Mark Linimon <linimon@lonesome.com>
To: "Simon L. Nielsen" <simon@FreeBSD.org>
Cc: Mark Linimon <linimon@lonesome.com>,
	<FreeBSD-gnats-submit@FreeBSD.org>, <freebsd-doc@FreeBSD.org>,
	<eik@FreeBSD.org>
Subject: Re: docs/64144: [patch] document procedure to add a new ports category
 to Committer's Guide
Date: Tue, 30 Mar 2004 14:26:30 -0600 (CST)

 On Tue, 30 Mar 2004, Simon L. Nielsen wrote:
 > +		    the <filename class="directory">ports/</filename> directory, run
 
 OK, that's the first I've seen of this.
 
 > > +		    <command>cvsup(1)</command> by modifying
 > 
 > Here you should use &man.cvsup.1;.
 
 I have it right elsewhere -- this was a cut-and-paste from ... somwehere.
 
 > If the category is set to "docs" there is no need to reassign it.  It
 > will automatically be assigned to freebsd-doc.
 
 D'oh!
 
 > > +		<step>
 > > +		  <para>Submit a PR to request that the web
 > > +		    page build be updated to reflect the new
 > > +		    category.  The responsibility for doing this
 > > +		    is not yet well established.</para>
 > > +		</step>
 > 
 > Shouldn't this just be a "www" PR?  I'm not really sure what needs to be
 > changed on the web pages?
 > 
 > Of course the issue with the ports/ pages being based on a INDEX still
 > exist...
 
 The latter is what I was trying to imply.  IMHO, at least the ports index
 page at http://www.freebsd.org/ports/index.html ought to be updated as
 soon as a category is added.
 

From: "Simon L. Nielsen" <simon@FreeBSD.org>
To: Mark Linimon <linimon@lonesome.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	eik@FreeBSD.org
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Wed, 31 Mar 2004 00:30:26 +0200

 --tvOENZuN7d6HfOWU
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On 2004.03.30 14:26:30 -0600, Mark Linimon wrote:
 > On Tue, 30 Mar 2004, Simon L. Nielsen wrote:
 > > +		    the <filename class=3D"directory">ports/</filename> directory, r=
 un
 >=20
 > OK, that's the first I've seen of this.
 
 Well, it don't think we (doc people) have been aware that the class
 existed for very long.  Ceri has mentioned at least once, on some
 mailing list.
 
 It's not terribly important, as nothing actually uses it at the moment
 and as you noted in another mail - a lot of existing docs doesn't use
 it. For new content we might as well add it, since we might find some
 use for it at some point.
 
 > > > +		<step>
 > > > +		  <para>Submit a PR to request that the web
 > > > +		    page build be updated to reflect the new
 > > > +		    category.  The responsibility for doing this
 > > > +		    is not yet well established.</para>
 > > > +		</step>
 > >=20
 > > Shouldn't this just be a "www" PR?  I'm not really sure what needs to be
 > > changed on the web pages?
 > >=20
 > > Of course the issue with the ports/ pages being based on a INDEX still
 > > exist...
 >=20
 > The latter is what I was trying to imply.  IMHO, at least the ports index
 > page at http://www.freebsd.org/ports/index.html ought to be updated as
 > soon as a category is added.
 
 It should, but the category list is generated from INDEX... I will look
 more into this.
 
 --=20
 Simon L. Nielsen
 FreeBSD Documentation Team
 
 --tvOENZuN7d6HfOWU
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.3 (FreeBSD)
 
 iD8DBQFAafUBh9pcDSc1mlERAmdkAJ9iGOqjNlPWha9mA9zZ0u+ejWEzsACcDASH
 gt8LyuTR4Zyd0d7RYdd7XSc=
 =MF6p
 -----END PGP SIGNATURE-----
 
 --tvOENZuN7d6HfOWU--
Responsible-Changed-From-To: freebsd-doc->linimon 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Wed Mar 31 09:57:34 PST 2004 
Responsible-Changed-Why:  
Submitter is now committer. 

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

From: Mark Linimon <linimon@lonesome.com>
To: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org
Cc: Oliver Eikemeier <eikemeier@fillmore-labs.com>, ceri@FreeBSD.org
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Thu, 1 Apr 2004 14:13:51 -0600

 Here is an updated (hopefully final) version of the patch.  It is still
 vague on the detail of getting http://www.FreeBSD.org/ports/ updated,
 but since that seems to be still under discussion, IMHO we should
 go ahead and commit what's here and update that detail once that
 discussion is resolved.
 
 Index: article.sgml
 ===================================================================
 RCS 
 file: /mnt/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
 retrieving revision 1.180
 diff -u -r1.180 article.sgml
 --- article.sgml	27 Feb 2004 15:23:15 -0000	1.180
 +++ article.sgml	1 Apr 2004 20:09:17 -0000
 @@ -2516,6 +2516,179 @@
        </qandadiv>
  
        <qandadiv>
 +	<title>Creating a New Category</title>
 +
 +	<qandaentry>
 +	  <question>
 +	    <para>What is the procedure for creating a new category?</para>
 +	  </question>
 +
 +	  <answer>
 +	    <para>A developer who wishes to propose a new category
 +	      should submit a detailed rationale for the new category,
 +	      including why existing categories are not sufficient,
 +	      and the list of ports proposed to move.</para>
 +
 +	    <para>Before submitting, keep in mind that there is a fair
 +	      amount of work involved from multiple parties; that the
 +	      changes affect everyone who wants to keep up-to-date with
 +	      the entire ports tree; and that such proposals tend to
 +	      attract controversy.</para>
 +	  </answer>
 +	</qandaentry>
 +
 +	<qandaentry>
 +	  <question>
 +	    <para>What do I need to do?</para>
 +	  </question>
 +
 +	  <answer>
 +	    <para>The procedure is a strict superset of the one to
 +	      repocopy individual ports (see above).</para>
 +
 +	    <para>File a PR in <application>GNATS</application>, listing the
 +	      reasons for the category request.  Preferably, this should
 +	      also include patches for <filename>Makefile</filename>s for
 +	      the old ports, the <filename>Makefile</filename>s for their
 +	      old categories, and the <makevar>VALID_CATEGORIES</makevar>
 +	      definition in <filename>ports/Mk/bsd.port.mk</filename>.
 +	      Assign the PR to the &a.portmgr; (as <literal>portmgr</literal>).
 +	      If they approve it, it will be reassigned to &a.cvs; (as
 +	      <literal>cvs</literal>), who will do a repository copy from
 +	      the old to the new locations, and reassign the PR back to you.
 +	      Once everything is done, perform the following steps:</para>
 +
 +	      <procedure>
 +		<step>
 +		  <para>Upgrade each copied port's
 +		    <filename>Makefile</filename>.  Do not connect the
 +		    new category to the build yet.</para>
 +
 +		  <para>To do this, you will need to:
 +		    <procedure>
 +		      <step>
 +			<para>Change the port's <makevar>CATEGORIES</makevar>
 +			  (this was the point of the exercise, remember?)
 +			  The new category should be listed
 +			  <emphasis>first</emphasis>.  This will help to
 +			  ensure that the the <makevar>PKGORIGIN</makevar>
 +			  is correct.</para>
 +		      </step>
 +
 +		      <step>
 +			<para>Run a <command>make describe</command>.  Since
 +			  the top-level <command>make index</command> that
 +			  you will be running in a few steps is an interation
 +			  of <command>make describe</command> over the entire
 +			  ports hierarchy, catching any errors here will
 +			  save you having to re-run that step later on.</para>
 +		      </step>
 +
 +		      <step>
 +			<para>If you want to be really thorough, now might
 +			  be a good time to run &man.portlint.1;.</para>
 +		      </step>
 +		    </procedure>
 +		</step>
 +
 +		<step>
 +		  <para>Check that the <makevar>PKGORIGIN</makevar>s are
 +		    correct.  The ports system uses each port's
 +		    <makevar>CATEGORIES</makevar> entry to create
 +		    its <makevar>PKGORIGIN</makevar>, which is used to
 +		    connect installed packages to the port directory they
 +		    were built from. If this entry is wrong, common port
 +		    tools like &man.pkg.version.1; and
 +		    &man.portupgrade.1; fail.</para>
 +
 +		  <para>To do this, use the <filename>chkorigin.sh</filename>
 +		    tool, as follows: <command>env
 +		    PORTSDIR=<replaceable>/path/to/ports</replaceable>
 +		    sh -e 
 <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh
 +		    </command>.  This will check <emphasis>every</emphasis>
 +		    port in the ports tree, even those not connected to the
 +		    build, so you can run it directly after the repocopy.
 +		    Hint: do not forget to look at the
 +		    <makevar>PKGORIGIN</makevar>s of any slave ports of the
 +		    ports you just repocopied!</para>
 +		</step>
 +
 +		<step>
 +		  <para>On your own local system, test the proposed
 +		    changes: first, comment out the
 +		    <makevar>SUBDIR</makevar> entries in the old
 +		    ports' categories' <filename>Makefile</filename>s;
 +		    then, enable building the new category in
 +		    <filename>ports/Makefile</filename>.
 +		    Run <command>make checksubdirs</command> in the
 +		    affected category directories to check the
 +		    <makevar>SUBDIR</makevar> entries.  Next, in
 +		    the <filename class="directory">ports/</filename>
 +		    directory, run <command>make index</command>.  This
 +		    can take over 40 minutes on even modern systems;
 +		    however, it is a necessary step to prevent problems
 +		    for other people.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Once this is done, you can commit the
 +		    updated <filename>ports/Makefile</filename> to
 +		    connect the new category to the build; and also
 +		    commit the <filename>Makefile</filename> changes
 +		    for the old category or categories.  The new
 +		    category's <filename>pkg/COMMENT</filename>
 +		    can be committed, too.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Change all the affected module entries in
 +		    <filename>CVSROOT-ports/modules</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Add appropriate entries to
 +		    <filename>ports/MOVED</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Update the instructions for &man.cvsup.1; by
 +		    modifying <filename>distrib/cvsup/sup/README</filename>
 +		    and adding the following files into
 +		    <filename>cvsup/sup/ports-categoryname</filename>:
 +		    <filename>list.cvs</filename> and
 +		    <filename>releases</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Submit a docs PR to add the new category both to the
 +		    <ulink 
 url="../../books/porters-handbook/makefile-categories.html#PORTING-CATEGORIES">
 +		    Porter's Handbook</ulink> and to the file
 +		    <filename>www/en/ports/categories</filename>.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Submit a www PR to request that the <ulink
 +		    url="../../../../ports/index.html">ports web pages</ulink>
 +		    be updated to reflect the new category.  Currently
 +		    this requires an import of
 +		    <filename>/usr/ports/INDEX</filename> into the www tree
 +		    (suggestions are welcome about how to get rid of this
 +		    dependency).  The responsibility for doing this is not
 +		    yet well established.</para>
 +		</step>
 +
 +		<step>
 +		  <para>Only once all the above have been done, and
 +		    no one is any longer reporting problems with the
 +		    new ports, should the old ports be deleted from
 +		    their previous locations in the repository.</para>
 +		</step>
 +	      </procedure>
 +	  </answer>
 +	</qandaentry>
 +      </qandadiv>
 +
 +      <qandadiv>
  	<title>Miscellaneous Questions</title>
  
  	<qandaentry>
 

From: Ceri Davies <ceri@FreeBSD.org>
To: Mark Linimon <linimon@lonesome.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	Oliver Eikemeier <eikemeier@fillmore-labs.com>
Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Date: Fri, 2 Apr 2004 02:40:09 +0100

 --5FDiZl1vRbLRjwwc
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Thu, Apr 01, 2004 at 02:13:51PM -0600, Mark Linimon wrote:
 > Here is an updated (hopefully final) version of the patch.  It is still
 > vague on the detail of getting http://www.FreeBSD.org/ports/ updated,
 > but since that seems to be still under discussion, IMHO we should
 > go ahead and commit what's here and update that detail once that
 > discussion is resolved.
 
 I'm happy for you to commit this, on the proviso that this comma goes
 away:
 
 > +	      Assign the PR to the &a.portmgr; (as <literal>portmgr</literal>).
 > +	      If they approve it, it will be reassigned to &a.cvs; (as
 > +	      <literal>cvs</literal>), who will do a repository copy from
 > +	      the old to the new locations, and reassign the PR back to you.
 	                                 ^^^
 
 And that this becomes a real word:
 
 > +			<para>Run a <command>make describe</command>.  Since
 > +			  the top-level <command>make index</command> that
 > +			  you will be running in a few steps is an interation
 			                                           ^^^^^^^^^^
 > +			  of <command>make describe</command> over the entire
 > +			  ports hierarchy, catching any errors here will
 > +			  save you having to re-run that step later on.</para>
 
 Not sure about this apostrophe either.  Do the right thing (which may be
 to leave it, it's 2.30 am here):
 
 > +		  <para>On your own local system, test the proposed
 > +		    changes: first, comment out the
 > +		    <makevar>SUBDIR</makevar> entries in the old
 > +		    ports' categories' <filename>Makefile</filename>s;
 		        ^^^
 
 I don't like this comma either:
 
 > +		    then, enable building the new category in
 		       ^^^
 > +		    <filename>ports/Makefile</filename>.
 
 Think this semicolon should go:
 
 > +		  <para>Once this is done, you can commit the
 > +		    updated <filename>ports/Makefile</filename> to
 > +		    connect the new category to the build; and also
 		                                        ^^^
 > +		    commit the <filename>Makefile</filename> changes
 > +		    for the old category or categories.  The new
 > +		    category's <filename>pkg/COMMENT</filename>
 > +		    can be committed, too.</para>
 
 It may or may not be worth mentioning that distrib/ lives in the src
 repository.
 
 > +		  <para>Update the instructions for &man.cvsup.1; by
 > +		    modifying <filename>distrib/cvsup/sup/README</filename>
 > +		    and adding the following files into
 > +		    <filename>cvsup/sup/ports-categoryname</filename>:
 > +		    <filename>list.cvs</filename> and
 > +		    <filename>releases</filename>.</para>
 
 s/both to/to both/ perhaps?
 
 > +		  <para>Submit a docs PR to add the new category both to the
 > +		    <ulink=20
 > url=3D"../../books/porters-handbook/makefile-categories.html#PORTING-CATE=
 GORIES">
 
 The FDP says get rid of "the file" below (grep for "Avoid redundant
 phrases"):
 
 > +		    Porter's Handbook</ulink> and to the file
 > +		    <filename>www/en/ports/categories</filename>.</para>
 
 Ceri
 --=20
 
 --5FDiZl1vRbLRjwwc
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.4 (FreeBSD)
 
 iD8DBQFAbMR5ocfcwTS3JF8RAiHhAJ9eFqo1mvLgMm4PYxgE9Jb6nC6GPACgvyxA
 YOtm1EO92FiEISmZl5y3zNg=
 =KYIZ
 -----END PGP SIGNATURE-----
 
 --5FDiZl1vRbLRjwwc--
State-Changed-From-To: open->closed 
State-Changed-By: linimon 
State-Changed-When: Sun Apr 4 10:05:26 PDT 2004 
State-Changed-Why:  
Committed after community review. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=64144 
>Unformatted:
