1 files changed, 170 insertions, 3 deletions

diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml
index d7c2186302..6f44dc7efb 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.sgml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml
@@ -678,11 +678,11 @@ alias scvs env CVS_RSH=ssh cvs -d <replaceable>user</replaceable>@ncvs.freebsd.o
 	</itemizedlist>
 
 	<para>You will almost certainly get a conflict because
-	  of the <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> (or in FreeBSD's case,
+	  of the <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> (or in FreeBSD's case,
 	  <literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>)
 	  lines, so you will have to edit the file to resolve the conflict
-	  (remove the marker lines and the second <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> line,
-	  leaving the original <literal>$Id: article.sgml,v 1.183 2004-04-02 19:30:29 des Exp $</literal> line intact).</para>
+	  (remove the marker lines and the second <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> line,
+	  leaving the original <literal>$Id: article.sgml,v 1.184 2004-04-04 17:05:14 linimon Exp $</literal> line intact).</para>
       </listitem>
 
       <listitem>
@@ -2522,6 +2522,173 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
       </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 iteration
+			  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.</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>.  (Note: these are
+		    in the src, not the ports, repository).</para>
+		</step>
+
+		<step>
+		  <para>Submit a docs PR to add the new category to both the
+		    <ulink url="../../books/porters-handbook/makefile-categories.html#PORTING-CATEGORIES">
+		    Porter's Handbook</ulink> and to
+		    <filename>www/en/ports/categories</filename>.</para>
+		</step>
+
+		<step>
+		  <para>The procedure to update the <ulink
+		    url="../../../../ports/index.html">ports web pages</ulink>
+		    to reflect the new category is not yet defined.</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>