docs/64144: [patch] document procedure to add a new ports category to Committer's Guide

Mark Linimon linimon at lonesome.com
Tue Mar 30 18:40:08 UTC 2004


The following reply was made to PR docs/64144; it has been noted by GNATS.

From: Mark Linimon <linimon at lonesome.com>
To: FreeBSD-gnats-submit at FreeBSD.org, freebsd-doc at FreeBSD.org
Cc: eik at 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>
 



More information about the freebsd-doc mailing list