From owner-freebsd-doc@FreeBSD.ORG Tue May 18 19:10:12 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 D8E5416A4CF for ; Tue, 18 May 2004 19:10:12 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id C6AF543D48 for ; Tue, 18 May 2004 19:10:12 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) i4J2ACxO051851 for ; Tue, 18 May 2004 19:10:12 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.11/8.12.11/Submit) id i4J2AC7x051850; Tue, 18 May 2004 19:10:12 -0700 (PDT) (envelope-from gnats) Resent-Date: Tue, 18 May 2004 19:10:12 -0700 (PDT) Resent-Message-Id: <200405190210.i4J2AC7x051850@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 668EA16A4CE; Tue, 18 May 2004 19:02:41 -0700 (PDT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id E730C43D48; Tue, 18 May 2004 19:02:40 -0700 (PDT) (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 26774148B4; Tue, 18 May 2004 21:02:40 -0500 (CDT) 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 i4J1xh0S033167; Tue, 18 May 2004 20:59:43 -0500 (CDT) (envelope-from linimon@lonesome.lonesome.com) Received: (from linimon@localhost) by lonesome.lonesome.com (8.12.9/8.12.9/Submit) id i4J1xgr5033166; Tue, 18 May 2004 20:59:42 -0500 (CDT) (envelope-from linimon) Message-Id: <200405190159.i4J1xgr5033166@lonesome.lonesome.com> Date: Tue, 18 May 2004 20:59:42 -0500 (CDT) From: Mark Linimon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 cc: ceri@FreeBSD.org cc: portmgr@FreeBSD.org Subject: docs/66855: [patch] rewrite sections of Porter's Handbook dealing with keeping up-to-date 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: Wed, 19 May 2004 02:10:13 -0000 >Number: 66855 >Category: docs >Synopsis: [patch] rewrite sections of Porter's Handbook dealing with keeping up-to-date >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 May 18 19:10:12 PDT 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: Craig Rodrigues , in docs/65170, pointed out that the Porter's Handbook lacks important information about how to keep up with changes to the Ports Collection, especially where maintainers are concerned. This PR rewrites some of the existing text about updating, but mostly adds new text at the end that describes the UPDATING and CHANGES files, FreshPorts, portsmon, and various other strategies and considerations for staying informed and avoiding duplicated effort and frustration. >How-To-Repeat: (n/a) >Fix: The changes are in 3 sections: first, the material on FreshPorts is moved to the end (the materail on 'sanity tests' was otherwise introduced before any other 'keeping up' material). Secondly, the technical information about preparing a port update is reworded and missing information is added. Finally, the section 'changes' at the end is totally rewritten. I will assign this PR to myself, but will wait to commit until I get more community feedback. Index: book.sgml =================================================================== RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v retrieving revision 1.402 diff -u -r1.402 book.sgml --- book.sgml 17 May 2004 19:08:44 -0000 1.402 +++ book.sgml 19 May 2004 01:49:03 -0000 @@ -4750,49 +4964,56 @@ have a better chance of working if the system administrator has moved the whole /usr/local tree somewhere else. - - - FreshPorts sanity tests - - has - a sanity test feature which automatically tests each commit to the - FreeBSD ports tree. If subscribed to this service, you will be - notified of any errors which FreshPorts detects during sanity - testing of your commits. - - If you wish to use this service, all you need is a FreshPorts - account. If your registered email address is - @FreeBSD.org, you'll see the opt-in link on the - right hand side of the webpages. - For those of you who already have a FreshPorts account, but are not - using your @FreeBSD.org email address, - just change your email to @FreeBSD.org, subscribe, - then change it back again. - Upgrading When you notice that a port is out of date compared to the latest - version from the original authors, first make sure you have the latest + version from the original authors, you should first ensure that you + have the latest port. You can find them in the ports/ports-current directory of the &os; FTP mirror - sites. You may also use CVSup to keep your whole ports collection - up-to-date, as described in the Handbook. - - The next step is to send an email to the maintainer, if one is - listed in the port's Makefile. That person may + sites. However, if you are working with more than a few + ports, will will probably find it easier to use + CVSup to keep your whole ports collection + up-to-date, as described in the + Handbook. + This will have the added benefit of tracking all the ports' + dependencies. + + The next step is to see if there is an update already pending. + To do this, you have two options. There is a searchable interface + to the + + FreeBSD Problem Report (PR) database (also known as + GNATS). Select ports in the + dropdown, and enter the name of the port. + + However, sometimes people forget to put the name of the port + into the Synopsis field in an unambiguous fashion. In that case, + you can try the + FreeBSD Ports Monitoring System (also known as + portsmon). This system attempts to classify + port PRs by portname. To search for PRs about a particular port, + use the + Overview of One Port. + + If there is no pending PR, the next step is to send an email + to the port's maintainer, as shown by + make maintainer. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version); you would not want to duplicate their work. Note that unmaintained ports are listed with a maintainer of - ports@FreeBSD.org; mail to that address + ports@FreeBSD.org, which is just the general + ports mailing list, so sending mail there probably will not help in this case. - If the maintainer asks you to do the upgrade or the maintainer - is ports@FreeBSD.org, - please make the upgrade and save the result of the + If the maintainer asks you to do the upgrade or there is + no maintainer, then you have a chance to help out &os; by + preparing the update yourself! Please make the changes and save + the result of the recursive diff output of the new and old ports directories (e.g., if your modified port directory is @@ -4806,21 +5027,33 @@ deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. + If the port is unmaintained, and you are actively using + it yourself, please consider volunteering to become its + maintainer. &os; has over 2000 ports without maintainers, + and this is an area where more volunteers are always needed. + (For a detailed description of the responsibilities of maintainers, + refer to the + + MAINTAINER on Makefiles section.) + The best way to send us the diff is by including it via &man.send-pr.1; (category - ports). If you are going to be the maintainer for the port, + ports). If you are volunteering to maintain 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 + of your synopsis line and set the Class of your PR + to maintainer-update. Otherwise, the + Class of your PR should be + change-request. Please mention any added or deleted files in the message, as they have to be explicitly specified - to CVS when doing a commit. If the diff is more than about 20KB, + to &man.cvs.1; when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is. - Finally, please see the + Before you &man.send-pr.1;, you should review the Writing the problem report section in the Problem - Reports article for more information about how to write + Reports article; it contains far more information about how to write useful problem reports. @@ -4837,6 +5070,10 @@ Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! + + Now that you have done all that, you will want to read about + how to keep up-to-date in . + @@ -6896,22 +7133,125 @@ package list automatically. - - Changes to this document and the ports system + + Keeping Up + + The &os; Ports Collection is constantly changing. Here is + some information on how to keep up. + + + FreshPorts + + On of the easiest ways to learn about updates that have + already been committed is by subscribing to + FreshPorts. + You can select multiple ports to monitor. Maintainers are + strongly encouraged to subscribe, because they will receive + notification of not only their own changes, but also any + changes that any other &os; committer has made. (These are + often necessary to keep up with changes in the underlying + ports framework—although it would be most polite to + receive an advance heads-up from those committing such changes, + sometimes this is overlooked or just simply impractical. + Also, in some cases, the changes are very minor in nature. + We expect everyone to use their best judgement in these + cases.) + + If you wish to use FreshPorts, all you need is an + account. If your registered email address is + @FreeBSD.org, you'll see the opt-in link on the + right hand side of the webpages. + For those of you who already have a FreshPorts account, but are not + using your @FreeBSD.org email address, + just change your email to @FreeBSD.org, subscribe, + then change it back again. + + FreshPorts also has + a sanity test feature which automatically tests each commit to the + FreeBSD ports tree. If subscribed to this service, you will be + notified of any errors which FreshPorts detects during sanity + testing of your commits. + + + + The Web Interface to the Source Repository + + It is possible to browse the files in the source repository by + using a web interface. Changes that affect the entire port system + are now documented in the + + CHANGES file. Changes that affect individual ports + are now documented in the + + UPDATING file. However, the definitive answer to any + question is undoubtedly to read the source code of + bsd.port.mk, and associated files. + + + + + The &os; Ports Mailing List + + If you maintain ports, you should consider following the + &a.ports;. Important changes to the way ports work will be announced + there, and then committed to CHANGES. + + + + + The &os; Port Building Cluster + + One of the least-publicized strengths of &os; is that + an entire cluster of machines is dedicated to continually + building the Ports Collection, for each of the major OS + releases and for each Tier-1 architecture. You can find + the results of these builds at + package building logs + and errors. + + + + + The &os; Port Distfile Survey + + The build cluster is dedicated to building the latest + release of each port with distfiles that have already been + fetched. However, as the Internet continually changes, + distfiles can quickly go missing. The FreeBSD + Ports distfiles survey attempts to query every + download site for every port to find out if each distfile + is still currently available. Maintainers are asked to + check this report periodically, not only to speed up the + building process for users, but to help avoid wasting + bandwidth of the sites that volunteer to host all these + distfiles. + + + + + + The &os; Ports Monitoring System + + Another handy resource is the + + FreeBSD Ports Monitoring System (also known as + portsmon). This system comprises a + database that processes information from several sources + and allows its to be browsed via a web interface. Currently, + the ports Problem Reports (PRs), the error logs from + the build cluster, and individual files from the ports + collection are used. In the future, this will be expanded + to include the distfile survey, as well as other sources. + + To get started, you can view all information about a + particular port by using the + + Overview of One Port. + + - If you maintain a lot of ports, you should consider following the - &a.ports;. Important changes to the way ports work will be announced - there. You can always find more detailed information on the latest - changes by looking at the - bsd.port.mk CVS log. - - Other resources to assist port maintainers include a list of - package building logs and - errors hosted on the bento cluster, - and also the FreeBSD - Ports distfiles survey. >Release-Note: >Audit-Trail: >Unformatted: