docs/66855: [patch] rewrite sections of Porter's Handbook dealing with keeping up-to-date
Mark Linimon
linimon at lonesome.com
Wed May 19 02:10:13 UTC 2004
>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 at lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
Craig Rodrigues <rodrigc at crodrigues.org>, 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 <filename>/usr/local</filename> tree somewhere else.</para>
</sect1>
-
- <sect1 id="testing-freshports">
- <title>FreshPorts sanity tests</title>
-
- <para><ulink url="http://www.FreshPorts.org/"></ulink> 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.</para>
-
- <para>If you wish to use this service, all you need is a FreshPorts
- account. If your registered email address is
- <literal>@FreeBSD.org</literal>, 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 <literal>@FreeBSD.org</literal> email address,
- just change your email to <literal>@FreeBSD.org</literal>, subscribe,
- then change it back again.</para>
- </sect1>
</chapter>
<chapter id="port-upgrading">
<title>Upgrading</title>
<para>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
<filename>ports/ports-current</filename> directory of the &os; FTP mirror
- sites. You may also use <application>CVSup</application> to keep your whole ports collection
- up-to-date, as described in the <ulink url="../handbook/synching.html#CVSUP-CONFIG">Handbook</ulink>.</para>
-
- <para>The next step is to send an email to the maintainer, if one is
- listed in the port's <filename>Makefile</filename>. That person may
+ sites. However, if you are working with more than a few
+ ports, will will probably find it easier to use
+ <application>CVSup</application> to keep your whole ports collection
+ up-to-date, as described in the
+ <ulink url="../handbook/synching.html#CVSUP-CONFIG">Handbook</ulink>.
+ This will have the added benefit of tracking all the ports'
+ dependencies.</para>
+
+ <para>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
+ <ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
+ FreeBSD Problem Report (PR) database</ulink> (also known as
+ <literal>GNATS</literal>). Select <literal>ports</literal> in the
+ dropdown, and enter the name of the port.</para>
+
+ <para>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 <ulink URL="http://portsmon.firepipe.net">
+ FreeBSD Ports Monitoring System</ulink> (also known as
+ <literal>portsmon</literal>). This system attempts to classify
+ port PRs by portname. To search for PRs about a particular port,
+ use the <ulink URL="http://portsmon.firepipe.net/portoverview.py">
+ Overview of One Port</ulink>.</para>
+
+ <para>If there is no pending PR, the next step is to send an email
+ to the port's maintainer, as shown by
+ <command>make maintainer</command>. 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
- <literal>ports at FreeBSD.org</literal>; mail to that address
+ <literal>ports at FreeBSD.org</literal>, which is just the general
+ ports mailing list, so sending mail there
probably will not help in this case.</para>
- <para>If the maintainer asks you to do the upgrade or the maintainer
- is <literal>ports at FreeBSD.org</literal>,
- please make the upgrade and save the result of the
+ <para>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 <command>diff</command> 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.</para>
+ <para>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
+ <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">
+ MAINTAINER on Makefiles</ulink> section.)</para>
+
<para> The best way to
send us the diff is by including it via &man.send-pr.1; (category
- <literal>ports</literal>). If you are going to be the maintainer for the port,
+ <literal>ports</literal>). If you are volunteering to maintain the
+ port,
be sure to put <literal>[maintainer update]</literal> at the beginning
- of your synopsis line and/or set the <quote>Class</quote> of your PR
- to <literal>maintainer-update</literal>. Please mention any added or
+ of your synopsis line and set the <quote>Class</quote> of your PR
+ to <literal>maintainer-update</literal>. Otherwise, the
+ <quote>Class</quote> of your PR should be
+ <literal>change-request</literal>. 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.</para>
- <para>Finally, please see the
+ <para>Before you &man.send-pr.1;, you should review the
<ulink url="../../articles/problem-reports/pr-writing.html">
Writing the problem report</ulink> 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.</para>
<important>
@@ -4837,6 +5070,10 @@
<para>Once again, please use &man.diff.1; and not &man.shar.1; to send
updates to existing ports!</para>
</note>
+
+ <para>Now that you have done all that, you will want to read about
+ how to keep up-to-date in <xref linkend="keeping-up">.</para>
+
</chapter>
<chapter id="porting-dads">
@@ -6896,22 +7133,125 @@
package list automatically.</para>
</chapter>
- <chapter id="changes">
- <title>Changes to this document and the ports system</title>
+ <chapter id="keeping-up">
+ <title>Keeping Up</title>
+
+ <para>The &os; Ports Collection is constantly changing. Here is
+ some information on how to keep up.</para>
+
+ <sect1>
+ <title>FreshPorts</title>
+
+ <para>On of the easiest ways to learn about updates that have
+ already been committed is by subscribing to
+ <ulink url="http://www.FreshPorts.org/">FreshPorts</ulink>.
+ 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.)</para>
+
+ <para>If you wish to use FreshPorts, all you need is an
+ account. If your registered email address is
+ <literal>@FreeBSD.org</literal>, 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 <literal>@FreeBSD.org</literal> email address,
+ just change your email to <literal>@FreeBSD.org</literal>, subscribe,
+ then change it back again.</para>
+
+ <para>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.</para>
+ </sect1>
+
+ <sect1>
+ <title>The Web Interface to the Source Repository</title>
+
+ <para>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
+ <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES">
+ CHANGES</ulink> file. Changes that affect individual ports
+ are now documented in the
+ <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING">
+ UPDATING</ulink> file. However, the definitive answer to any
+ question is undoubtedly to read the source code of <ulink
+ url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk">
+ bsd.port.mk</ulink>, and associated files.</para>
+
+ </sect1>
+
+ <sect1>
+ <title>The &os; Ports Mailing List</title>
+
+ <para>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 <filename>CHANGES</filename>.</para>
+
+ </sect1>
+
+ <sect1>
+ <title>The &os; Port Building Cluster</title>
+
+ <para>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
+ <ulink url="http://bento.FreeBSD.org/">package building logs
+ and errors</ulink>.</para>
+
+ </sect1>
+
+ <sect1>
+ <title>The &os; Port Distfile Survey</title>
+
+ <para>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 <ulink
+ url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
+ Ports distfiles survey</ulink> 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.</para>
+
+ </sect1>
+
+ <sect1>
+
+ <title>The &os; Ports Monitoring System</title>
+
+ <para>Another handy resource is the
+ <ulink URL="http://portsmon.firepipe.net">
+ FreeBSD Ports Monitoring System</ulink> (also known as
+ <literal>portsmon</literal>). 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.</para>
+
+ <para>To get started, you can view all information about a
+ particular port by using the
+ <ulink URL="http://portsmon.firepipe.net/portoverview.py">
+ Overview of One Port</ulink>.</para>
+
+ </sect1>
- <para>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 <ulink
- url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk"> the
- bsd.port.mk CVS log</ulink>.</para>
-
- <para>Other resources to assist port maintainers include a list of
- <ulink url="http://bento.FreeBSD.org/">package building logs and
- errors</ulink> hosted on the <literal>bento cluster</literal>,
- and also the <ulink
- url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
- Ports distfiles survey</ulink>.</para>
</chapter>
</book>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list