From owner-freebsd-doc@FreeBSD.ORG Thu Apr 1 12:14:03 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5D86316A4CE; Thu, 1 Apr 2004 12:14:03 -0800 (PST) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0B8F943D2D; Thu, 1 Apr 2004 12:14:03 -0800 (PST) (envelope-from linimon@lonesome.com) Received: from lonesome.lonesome.com (cs242743-143.austin.rr.com [24.27.43.143]) (using TLSv1 with cipher RC4-MD5 (128/128 bits)) (No client certificate requested) by mail.soaustin.net (Postfix) with ESMTP id CAF7F1473C; Thu, 1 Apr 2004 14:14:01 -0600 (CST) From: Mark Linimon Organization: Lonesome Dove Computing Services To: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org Date: Thu, 1 Apr 2004 14:13:51 -0600 User-Agent: KMail/1.5.4 References: In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200404011413.51013.linimon@lonesome.com> cc: ceri@FreeBSD.org cc: Oliver Eikemeier Subject: Re: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 Apr 2004 20:14:03 -0000 Here is an updated (hopefully final) version of the patch. It is still vague on the detail of getting http://www.FreeBSD.org/ports/ updated, but since that seems to be still under discussion, IMHO we should go ahead and commit what's here and update that detail once that discussion is resolved. 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 1 Apr 2004 20:09:17 -0000 @@ -2516,6 +2516,179 @@ + Creating a New Category + + + + What is the procedure for creating a new category? + + + + 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. + + 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. + + + + + + What do I need to do? + + + + The procedure is a strict superset of the one to + repocopy individual ports (see above). + + File a PR in GNATS, listing the + reasons for the category request. Preferably, this should + also include patches for Makefiles for + the old ports, the Makefiles for their + old categories, and the VALID_CATEGORIES + definition in ports/Mk/bsd.port.mk. + Assign the PR to the &a.portmgr; (as portmgr). + If they approve it, it will be reassigned to &a.cvs; (as + cvs), 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: + + + + Upgrade each copied port's + Makefile. Do not connect the + new category to the build yet. + + To do this, you will need to: + + + Change the port's CATEGORIES + (this was the point of the exercise, remember?) + The new category should be listed + first. This will help to + ensure that the the PKGORIGIN + is correct. + + + + Run a make describe. Since + the top-level make index that + you will be running in a few steps is an interation + of make describe over the entire + ports hierarchy, catching any errors here will + save you having to re-run that step later on. + + + + If you want to be really thorough, now might + be a good time to run &man.portlint.1;. + + + + + + Check that the PKGORIGINs are + correct. The ports system uses each port's + CATEGORIES entry to create + its PKGORIGIN, 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. + + To do this, use the chkorigin.sh + tool, as follows: env + PORTSDIR=/path/to/ports + sh -e /path/to/ports/Tools/scripts/chkorigin.sh + . This will check every + 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 + PKGORIGINs of any slave ports of the + ports you just repocopied! + + + + On your own local system, test the proposed + changes: first, comment out the + SUBDIR entries in the old + ports' categories' Makefiles; + then, enable building the new category in + ports/Makefile. + Run make checksubdirs in the + affected category directories to check the + SUBDIR entries. Next, in + the ports/ + directory, run make index. This + can take over 40 minutes on even modern systems; + however, it is a necessary step to prevent problems + for other people. + + + + Once this is done, you can commit the + updated ports/Makefile to + connect the new category to the build; and also + commit the Makefile changes + for the old category or categories. The new + category's pkg/COMMENT + can be committed, too. + + + + Change all the affected module entries in + CVSROOT-ports/modules. + + + + Add appropriate entries to + ports/MOVED. + + + + Update the instructions for &man.cvsup.1; by + modifying distrib/cvsup/sup/README + and adding the following files into + cvsup/sup/ports-categoryname: + list.cvs and + releases. + + + + Submit a docs PR to add the new category both to the + + Porter's Handbook and to the file + www/en/ports/categories. + + + + Submit a www PR to request that the ports web pages + be updated to reflect the new category. Currently + this requires an import of + /usr/ports/INDEX into the www tree + (suggestions are welcome about how to get rid of this + dependency). The responsibility for doing this is not + yet well established. + + + + 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. + + + + + + + Miscellaneous Questions