From owner-freebsd-doc@FreeBSD.ORG Thu Mar 11 23:10:02 2004 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1DCA616A4D0 for ; Thu, 11 Mar 2004 23:10:02 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0B8B143D48 for ; Thu, 11 Mar 2004 23:10:02 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) i2C7A1bv012087 for ; Thu, 11 Mar 2004 23:10:01 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.10/8.12.10/Submit) id i2C7A15B012086; Thu, 11 Mar 2004 23:10:01 -0800 (PST) (envelope-from gnats) Resent-Date: Thu, 11 Mar 2004 23:10:01 -0800 (PST) Resent-Message-Id: <200403120710.i2C7A15B012086@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Mark Linimon Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id CFDD316A4CE; Thu, 11 Mar 2004 23:09:25 -0800 (PST) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 7209543D48; Thu, 11 Mar 2004 23:09:23 -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 EDH-RSA-DES-CBC3-SHA (168/168 bits)) (No client certificate requested) by mail.soaustin.net (Postfix) with ESMTP id 9C4661472E; Fri, 12 Mar 2004 01:09:22 -0600 (CST) Received: from lonesome.lonesome.com (localhost.lonesome.com [127.0.0.1]) by lonesome.lonesome.com (8.12.9/8.12.9) with ESMTP id i2C79ic7019624; Fri, 12 Mar 2004 01:09:44 -0600 (CST) (envelope-from linimon@lonesome.lonesome.com) Received: (from linimon@localhost) by lonesome.lonesome.com (8.12.9/8.12.9/Submit) id i2C79i2h019623; Fri, 12 Mar 2004 01:09:44 -0600 (CST) (envelope-from linimon) Message-Id: <200403120709.i2C79i2h019623@lonesome.lonesome.com> Date: Fri, 12 Mar 2004 01:09:44 -0600 (CST) From: Mark Linimon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 cc: ports-developers@FreeBSD.org Subject: 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 Reply-To: Mark Linimon List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 12 Mar 2004 07:10:02 -0000 >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 @@ + 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 portmgr. + If &a.portmgr; approves it, it will be reassigned to + cvs. &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: + + + + When the repocopies have been finished: + + + + Upgrade each copied port's + Makefile. Do not + connect the new category to the build yet. + + + + On your own local system, test the proposed + changes: first, comment out the + SUBDIR entries in the old + ports' categories' Makefiles; + then, enable the Makefile for 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. + + + + Add appropriate entries to + ports/MOVED. + + + + Update the instructions for + cvsup(1) by modifying + distrib/cvsup/sup/README + and adding the following files into + cvsup/sup/ports-categoryname: + list.cvs and + releases. + + + + Submit a PR to add the new category to + the Porter's Handbook, and to add it to + www/en/ports/categories, + and assign it to docs. + + + + 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. + + + + 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 >Release-Note: >Audit-Trail: >Unformatted: