Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 12 Mar 2004 01:09:44 -0600 (CST)
From:      Mark Linimon <linimon@lonesome.com>
To:        FreeBSD-gnats-submit@FreeBSD.org
Cc:        ports-developers@FreeBSD.org
Subject:   docs/64144: [patch] document procedure to add a new ports category to Committer's Guide
Message-ID:  <200403120709.i2C79i2h019623@lonesome.lonesome.com>
Resent-Message-ID: <200403120710.i2C7A15B012086@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>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:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 11 23:10:01 PST 2004
>Closed-Date:
>Last-Modified:
>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:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200403120709.i2C79i2h019623>