diff options
Diffstat (limited to 'en_US.ISO8859-1/articles/committers-guide/article.sgml')
| -rw-r--r-- | en_US.ISO8859-1/articles/committers-guide/article.sgml | 173 |
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> |