From owner-freebsd-doc@FreeBSD.ORG Tue Jan 20 14:51:55 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 B98CC16A4CF for ; Tue, 20 Jan 2004 14:51:55 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 57B5743D64 for ; Tue, 20 Jan 2004 14:50:16 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) i0KMoGFR075403 for ; Tue, 20 Jan 2004 14:50:16 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.10/8.12.10/Submit) id i0KMoGwq075402; Tue, 20 Jan 2004 14:50:16 -0800 (PST) (envelope-from gnats) Resent-Date: Tue, 20 Jan 2004 14:50:16 -0800 (PST) Resent-Message-Id: <200401202250.i0KMoGwq075402@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 C9F4716A4CE for ; Tue, 20 Jan 2004 14:49:45 -0800 (PST) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id BC50443D6D for ; Tue, 20 Jan 2004 14:48:25 -0800 (PST) (envelope-from linimon@lonesome.com) Received: from lonesome.lonesome.com (cs242719-195.austin.rr.com [24.27.19.195]) (using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits)) (No client certificate requested) by mail.soaustin.net (Postfix) with ESMTP id D53781469F for ; Tue, 20 Jan 2004 16:48:24 -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 i0KMlSql076490 for ; Tue, 20 Jan 2004 16:47:28 -0600 (CST) (envelope-from linimon@lonesome.lonesome.com) Received: (from linimon@localhost) by lonesome.lonesome.com (8.12.9/8.12.9/Submit) id i0KMlSuU076489; Tue, 20 Jan 2004 16:47:28 -0600 (CST) (envelope-from linimon) Message-Id: <200401202247.i0KMlSuU076489@lonesome.lonesome.com> Date: Tue, 20 Jan 2004 16:47:28 -0600 (CST) From: Mark Linimon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Subject: docs/61653: [patch] cleanup after recent changes to Porter's Handbook 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: Tue, 20 Jan 2004 22:51:55 -0000 >Number: 61653 >Category: docs >Synopsis: [patch] cleanup after recent changes to Porter's Handbook >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: Tue Jan 20 14:50:16 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 #0: Fri Sep 5 01:19:33 CDT 2003 linimon@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA_DEBUG i386 (n/a) >Description: The recent commit of my changes to the Porter's Handbook left some rough edges; this patch fixes them. First, some text was proposed but not accepted; there was some dangling text left behind that kind-of went with the rejected text. Next, some content that was added to replace existing content, or move it around, didn't have the original text deleted afterwards. Third, there are some places where a concept is introduced, then elaborated on, then the reason is given for having the concept. This patch switches those latter two around. Lastly, in a few places the language wound up being awkward. There is no new content in this patch; it's just a cleanup that IMHO makes the document "flow" a little bit better. >How-To-Repeat: (n/a) >Fix: --- book.sgml.dist Tue Jan 20 16:33:11 2004 +++ book.sgml Tue Jan 20 16:33:16 2004 @@ -64,7 +64,7 @@ Making a port yourself - So, you are still interested in making your own port or + So, you are interested in making your own port or upgrading an existing one? Great! What follows are some guidelines for creating a new port for @@ -348,8 +348,19 @@ Also add a short description of the program you ported to the Description field of the PR and the shar or uuencoded tarfile to the - Fix field. The latter one helps the committers - a lot, who use scripts for the ports-work. + Fix field. + + + You can make our work a lot easier, if you use a good + description in the synopsis of the problem report. + We prefer something like + New port: <category>/<portname> + <short description of the port> for new ports and + Update port: <category>/<portname> + <short description of the update> for port updates. + If you stick to this scheme, the chance that someone takes a + look at your PR soon is much bigger. + One more time, do not include the original source distfile, the work directory, or the package @@ -375,18 +386,6 @@ Additional FreeBSD Contributors and other files. Isn't that great?!? :-) - - - You can make our work a lot easier, if you use a good - description in the synopsis of the problem report. - We prefer something like - New port: <short description of the port> for - new ports and - Update port: <category>/<port> <short description - of the update> for port updates. - If you stick to this scheme, the chance that one takes a look at - your PR soon is much bigger. - @@ -757,8 +756,13 @@ every increase of PORTVERSION (i.e. every time a new official vendor release is made), and appended to the package name if non-zero. - PORTREVISION is increased each time a - change is made to the FreeBSD port which significantly + Changes to PORTREVISION are + used by automated tools (e.g. &man.pkg.version.1;) + to highlight the fact that a new package is + available. + + PORTREVISION should be increased + each time a change is made to the port which significantly affects the content or structure of the derived package. @@ -769,7 +773,7 @@ Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to - the FreeBSD port. + the port. @@ -832,7 +836,7 @@ the changes do not introduce any functional change on any other platforms on which the port did previously build). Since PORTREVISION reflects - the content of the package, if no package was + the content of the package, if the package was not previously buildable then there is no need to increase PORTREVISION to mark a change. @@ -846,10 +850,7 @@ actually work at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the - PORTREVISION should be bumped so that - automated tools (e.g. &man.pkg.version.1;) - will highlight the fact that a new package is - available. + PORTREVISION should be bumped. @@ -1577,7 +1578,7 @@ safely delete misc and just put the port in that other subdirectory! If at all possible, try to find a better category for your port than - misc ports tend to get overlooked + misc, as ports tend to get overlooked in here. @@ -1814,8 +1815,7 @@ If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate - categories. Also, many of them go into other - x11-* categories (see below). + category. @@ -1938,7 +1938,7 @@ DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to - ${PORTNAME}-${PORTVERSION}, so override it if necessary. + ${PORTNAME}-${PORTVERSION}, so override it only if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to @@ -1950,7 +1950,7 @@ PKGNAMEPREFIX and PKGNAMESUFFIX do not affect - DISTNAME. Also note that when + DISTNAME. Also note that if WRKSRC is equal to work/${PORTNAME}-${PORTVERSION} while the original source archive is named something other than @@ -1997,7 +1997,7 @@ These variables are defined in /usr/ports/Mk/bsd.sites.mk. There are - new archives added all the time, so make sure to check the + new entries added all the time, so make sure to check the latest version of this file before submitting a port. The user can also set the MASTER_SITE_* @@ -2793,7 +2793,9 @@ Set your mail-address here. Please. :-) - The format used should be user@hostname.domain. + Note that only a single address without comment part is + allowed as a MAINTAINER value. + The format used should be user@hostname.domain. Please do not include any descriptive text such as your real name in this entry—that merely confuses bsd.port.mk. Instead, put that information @@ -2803,9 +2805,6 @@ refer to the MAINTAINER on Makefiles section. - Note that only a single address without comment part is - allowed as a MAINTAINER value. - If the maintainer of a port does not respond to an update request from a user after two weeks (excluding major public holidays), then that is considered a maintainer timeout, and the @@ -3440,7 +3443,7 @@ package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to - it at compile time. + it at compile time, set NO_PACKAGE. NO_PACKAGE should be set to a string describing the reason why the package should not be @@ -4547,7 +4549,7 @@ occurrences of /usr/local (or /usr/X11R6 for X ports that do not use imake) in the various scripts/Makefiles in the port to read - PREFIX, as this variable is automatically passed + ${PREFIX}, as this variable is automatically passed down to every stage of the build and install processes. Make sure your application is not installing things in @@ -4557,7 +4559,7 @@ &prompt.root; make clean; make package PREFIX=/var/tmp/port-name If anything is installed outside of PREFIX, - making the package creation process will complain that it + the package creation process will complain that it cannot find the files. @@ -4634,23 +4636,23 @@ If the maintainer asks you to do the upgrade or the maintainer is ports@FreeBSD.org, - please make the upgrade and send the + please make the upgrade and save the result of the recursive diff output of the new and old - ports directories to us (e.g., if your modified port directory is + ports directories. (e.g., if your modified port directory is called superedit and the original is in our tree - as superedit.bak, then send us the result of + as superedit.bak, then save the result of diff -ruN superedit.bak superedit). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the -N option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being - deleted. + deleted. Before sendingus the diff, please examine the + output to make sure all the changes make sense. - Please examine - the output to make sure all the changes make sense. The best way to + The best way to send us the diff is by including it via &man.send-pr.1; (category - ports). If you are the maintainer for the port, + ports). If you are going to be the maintainer for the port, be sure to put [maintainer update] at the beginning of your synopsis line and/or set the Class of your PR to maintainer-update. Please mention any added or @@ -4676,8 +4678,8 @@ - Once again, please use &man.diff.1; and not &man.shar.1; to send - updates to existing ports! + Once again, please use &man.diff.1;, and not &man.shar.1;, to send + updates to existing ports! @@ -6397,8 +6399,8 @@ number of vulnerable FreeBSD hosts (we like being known for being secure), however sometimes there is a noticeable time gap between disclosure of a - vulnerability and an updated software release of a piece - of vulnerable software. Do not mark a port + vulnerability and an updated release of the + vulnerable software. Do not mark a port FORBIDDEN for any reason other than security. >Release-Note: >Audit-Trail: >Unformatted: