Attachment 42957 Details for Bug 66855 – file.diff

[patch] file.diff

file.diff (text/plain), 12.61 KB, created by Mark Linimon on 2004-05-19 03:10:12 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Mark Linimon

Created: 2004-05-19 03:10:12 UTC

Size: 12.61 KB

patch

obsolete

>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@FreeBSD.org</literal>; mail to that address
>+	<literal>ports@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@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&mdash;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>

Actions: View | Diff

Attachments on bug 66855: 42957