Remove ambiguities about how to submit a new port vs. how to submit an

update to an existing port.  This has tripped up several people who are
new readers of this document over the years.

Based on work by:	Jason Helfman <jhelfman at e-e dot com>

1 files changed, 34 insertions, 15 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 80df8801a2..1c1dc2ed39 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -56,7 +56,7 @@
     </chapter>
 
     <chapter id="own-port">
-      <title>Making a port yourself</title>
+      <title>Making a new port yourself</title>
 
       <para>So, you are interested in making your own port or
 	upgrading an existing one?  Great!</para>
@@ -91,7 +91,7 @@
     <chapter id="quick-porting">
       <title>Quick Porting</title>
 
-      <para>This section tells you how to do a quick port.  In many cases, it
+      <para>This section tells you how to quickly create a new port.  In many cases, it
 	is not sufficient, so you will have to read further on into
 	the document.</para>
 
@@ -363,9 +363,9 @@ PLIST_DIRS=     lib/X11/oneko</programlisting>
       </sect1>
 
       <sect1 id="porting-submitting">
-	<title>Submitting the port</title>
+	<title>Submitting the new port</title>
 
-	<para>First, make sure you have read the <link
+	<para>Before you submit the new port, make sure you have read the <link
 	    linkend="porting-dads">DOs and DON'Ts</link> section.</para>
 
 	<para>Now that you are happy with your port, the only thing remaining
@@ -386,7 +386,8 @@ PLIST_DIRS=     lib/X11/oneko</programlisting>
 	  <literal>change-request</literal>  (Do not mark the report
 	  <literal>confidential</literal>!).
 	  Also add a short description of the program you ported
-	  to the <quote>Description</quote> field of the PR and
+	  to the <quote>Description</quote> field of the PR (e.g.
+	  perhaps a short version of the <makevar>COMMENT</makevar>), and add
 	  the shar file to the <quote>Fix</quote> field.</para>
 
 	<note>
@@ -394,23 +395,23 @@ PLIST_DIRS=     lib/X11/oneko</programlisting>
 	    description in the synopsis of the problem report.
 	    We prefer something like
 	    <quote>New port: &lt;category&gt;/&lt;portname&gt;
-	    &lt;short description of the port&gt;</quote> for new ports and
-	    <quote>Update port: &lt;category&gt;/&lt;portname&gt;
-	    &lt;short description of the update&gt;</quote> for port updates.
+	    &lt;short description of the port&gt;</quote> for new ports.
 	    If you stick to this scheme, the chance that someone will take a
 	    look at your PR soon is much better.</para>
 	</note>
 
 	<para>One more time, <emphasis>do not include the original source
 	    distfile, the <filename>work</filename> directory, or the package
-	    you built with <command>make package</command></emphasis>.</para>
+	    you built with <command>make package</command></emphasis>;
+	    and, do use &man.shar.1; for new ports, not &man.diff.1;.
+	    </para>
 
 	<para>After you have submitted your port, please be patient.
 	  Sometimes it can take a few months before a port is included
 	  in &os;, although it might only take a few days.  You can
 	  view the list of <ulink
 	  url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports
-	  waiting to be committed to &os;</ulink>.</para>
+	  PRs waiting to be committed to &os;</ulink>.</para>
 
 	<para>Once we have looked at your port, we will get back to you if necessary, and put
 	  it in the tree.  Your name will also appear in the list of
@@ -9301,7 +9302,7 @@ as .putsy.conf and edit it.</programlisting>
   </chapter>
 
     <chapter id="port-upgrading">
-      <title>Upgrading</title>
+      <title>Upgrading an individual port</title>
 
       <para>When you notice that a port is out of date compared to the latest
 	version from the original authors, you should first ensure that you
@@ -9346,9 +9347,22 @@ as .putsy.conf and edit it.</programlisting>
 
       <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
+	preparing the update yourself!  Please do this by using the
+	&man.diff.1; command in the base system.</para>
+
+      <para>To create a suitable <command>diff</command> for a single patch, copy
+	the file that needs patching to <replaceable>something.orig</replaceable>,
+	save your changes to <replaceable>something</replaceable> and then create
+	your patch:</para>
+
+      <informalexample>
+	<screen>&prompt.user; <userinput>/usr/bin/diff something.orig something > something.diff</userinput></screen>
+      </informalexample>
+
+      <para>Otherwise, you should copy the contents of the port to an entire
+	different directory and use
 	the result of the
-	recursive <command>diff</command> output
+	recursive &man.diff.1; output
 	of the new and old
 	ports directories (e.g., if your modified port directory is
 	called <filename>superedit</filename> and the original is in our tree
@@ -9359,7 +9373,11 @@ as .putsy.conf and edit it.</programlisting>
 	option&mdash;this is the accepted way to force diff to properly
 	deal with the case of new files being added or old files being
 	deleted.  Before sending us the diff, please examine the
-	output to make sure all the changes make sense.  To
+	output to make sure all the changes make sense.  (In particular,
+	make sure you first clean out the work directories with
+	<command>make clean</command>).</para>
+
+     <para>To
 	simplify common operations with patch files, you can use
 	<filename>/usr/ports/Tools/scripts/patchtool.py</filename>.
 	Before using it, please read
@@ -9405,7 +9423,8 @@ as .putsy.conf and edit it.</programlisting>
 
       <note>
 	<para>Once again, please use &man.diff.1; and not &man.shar.1; to send
-	  updates to existing ports!</para>
+	  updates to existing ports!  This helps ports committers understand
+	  exactly what is being changed.</para>
       </note>
 
       <para>Now that you have done all that, you will want to read about