CFD: changes to the Porter's Handbook about proposing new categories

[Mark Linimon]

After checking where to direct someone who was inquiring about this, I
found that what I had written last time was in the Committer's Handbook
and effectively assumes that the proposer is a committer.  What the
following patch does is split the existing text into two pieces and
moves the general piece to the Porter's Handbook, after adding several
paragraphs along the way.  Since it affects policy, portmgr@ is copied.

(The patch does not include removing the text that moves, yet; the
implied change is fairly obvious and would collide with my other
outstanding patch to the CH.)

Unless there are objections, I'd like to commit this text within the
next day or so.

mcl

Index: book.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.507
diff -u -r1.507 book.sgml
--- book.sgml	19 Dec 2004 02:27:06 -0000	1.507
+++ book.sgml	19 Dec 2004 23:21:15 -0000
@@ -1290,23 +1290,6 @@
 	  the first category.  See <link
 	    linkend="choosing-categories">below</link> for more
 	  discussion about how to pick the right categories.</para>
-
-	<para>If your port truly belongs to something that is different from
-	  all the existing ones, you can even create a new category name.  In
-	  that case, please send mail to the &a.ports; to propose a new
-	  category.  However, in general, until there are more than a
-	  handful of ports which could be reclassified into the category
-	  you propose, you will probably be turned down.</para>
-
-	<note><para>Occasionally someone proposes reorganizing the categories
-	  with either a 2-level structure, or some other kind of keyword
-	  structure.  To date, nothing has come of any of these proposals
-	  because, while they are very easy to make, the effort involved to
-	  retrofit the entire existing ports collection with any kind of
-	  reorganization is daunting to say the very least.  Please read
-	  the history of these proposals in the mailing list archives before
-	  you post this idea; furthermore, you should be prepared to be
-	  challenged to offer a working prototype.</para></note>
       </sect2>
 
       <sect2 id="porting-categories">
@@ -1965,6 +1948,126 @@
 	  imported to the wrong category only to be moved right away.
 	  This causes unnecessary and undesirable bloat in the master
 	  source repository.</para>
+      </sect2>
+
+      <sect2 id="proposing-categories">
+	<title>Proposing a new category</title>
+
+	<para>As the Ports Collection has grown over time, various new
+	  categories have been introduced.  New categories can either
+	  be <emphasis>virtual</emphasis> categories—those that do
+	  not have a corresponding subdirectory in the ports tree—
+	  or <emphasis>physical</emphasis> categories—those that
+	  do.  The following text dicusses the issues involved in creating
+	  a new physical category so that you can understand them before
+	  you propose one.</para>
+
+	<para>Our existing practice has been to avoid creating a new
+	  physical category unless either a large number of ports would
+	  logically belong to it, or the ports that would belong to it
+	  are a logically distinct group that is of limited general
+	  interest (for instance, categories related to spoken human
+	  languages), or preferably both.</para>
+
+	<para>The rationale for this is that such a change creates a
+	  <ulink url="&url.articles.committers-guide;/#ports">
+	  fair amount of work</ulink> for both the committers and also
+	  for all users who track changes to the Ports Collection.  In
+	  addition, proposed category changes just naturally seem to
+	  attract controversy.  (Perhaps this is because there is no
+	  clear consensus on when a category is <quote>too big</quote>,
+	  nor whether categories should lend themselves to browsing (and
+	  thus what number of categories would be an ideal number), and
+	  so forth.)</para>
+
+	<para>Here is the procedure:</para>
+
+	<procedure>
+	  <step>
+	    <para>Propose the new category on &a.ports;.  You should
+	      include a detailed rationale for the new category,
+	      including why you feel the existing categories are not
+	      sufficient, and the list of existing ports proposed to move.
+	      (If there are new ports pending in
+	      <application>GNATS</application> that would fit this
+	      category, list them too.)  If you are the maintainer and/or
+	      submitter, respectively, mention that as it may help you
+	      to make your case.</para>
+	  </step>
+
+	  <step>
+	    <para>Participate in the discussion.</para>
+	  </step>
+
+	  <step>
+	    <para>If it seems that there is support for your idea,
+	      file a PR which includes both the rationale and the list
+	      of existing ports that need to be moved.  Ideally, this
+	      PR should also include patches for the following:</para>
+
+	    <itemizedlist>
+	      <listitem>
+		<para><filename>Makefile</filename>s for the
+		  new ports once they are repocopied</para>
+	      </listitem>
+
+	      <listitem>
+		<para><filename>Makefile</filename> for the
+		  new category</para>
+	      </listitem>
+
+	      <listitem>
+		<para><filename>Makefile</filename> for the
+		  old ports' categories</para>
+	      </listitem>
+
+	      <listitem>
+		<para><filename>Makefile</filename>s for ports
+		  that depend on the old ports</para>
+	      </listitem>
+
+	      <listitem>
+		<para>(for extra credit, you can include the other
+		  files that have to changes, as per the procedure
+		  in the Committer's Guide.)</para>
+	      </listitem>
+	    </itemizedlist>
+	  </step>
+
+	  <step>
+	    <para>Since it affects the ports infrastructure and involves
+	      not only performing repo-copies but also possibly running
+	      regression tests on the build cluster, the PR should be
+	      assigned to the &a.portmgr;.</para>
+	  </step>
+
+	  <step>
+	    <para>If that PR is approved, a committer will need to follow
+	      the rest of the procedure that is
+	      <ulink url="&url.articles.committers-guide;/#ports">
+	      outlined in the Committer's Guide</ulink>.</para>
+	  </step>
+	</procedure>
+
+	<para>Proposing a new virtual category should be similar to
+	  the above but much less involved, since no ports will
+	  actually have to move.  In this case, the only patches to
+	  include in the PR would be those to add the new category to the
+	  <makevar>CATEGORIES</makevar>s of the affected ports.</para>
+      </sect2>
+
+      <sect2 id="proposing-reorg">
+	<title>Proposing reorganizing all the categories</title>
+
+	<para>Occasionally someone proposes reorganizing the categories
+	  with either a 2-level structure, or some other kind of keyword
+	  structure.  To date, nothing has come of any of these proposals
+	  because, while they are very easy to make, the effort involved to
+	  retrofit the entire existing ports collection with any kind of
+	  reorganization is daunting to say the very least.  Please read
+	  the history of these proposals in the mailing list archives before
+	  you post this idea; furthermore, you should be prepared to be
+	  challenged to offer a working prototype.</para>
       </sect2>
     </sect1>