Date: Tue, 30 Mar 2004 10:40:07 -0800 (PST) From: Mark Linimon <linimon@lonesome.com> To: freebsd-doc@FreeBSD.org Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide Message-ID: <200403301840.i2UIe7nn043099@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/64144; it has been noted by GNATS.
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200403301840.i2UIe7nn043099>