freebsd-update and ports

[Warren Block]

Looking for some feedback from someone more familiar with 
freebsd-update(8) and ports.

In reference to this PR:
http://www.freebsd.org/cgi/query-pr.cgi?pr=175069

This sentence has never made sense to me:

   Most users will want to run a test build using the following command:
   # portupgrade -af

I also think that the section is incorrect in stating that all ports 
must be rebuilt even after minor version upgrades.  Another problem is 
that the difference between minor and major upgrades are never defined.

Difficulty: I have not used freebsd-update(8).

This patch makes these changes:

   Define minor and major version upgrades at the start of the section.
   Say that installed applications will generally still run after a minor
   upgrade.
   Move the initial portupgrade instructions into a warning, and make it
   specific to major upgrades.
   Change the final portupgrade instructions to only be required after a
   major upgrade.

Index: cutting-edge/chapter.xml
===================================================================
--- cutting-edge/chapter.xml	(revision 40586)
+++ cutting-edge/chapter.xml	(working copy)
@@ -354,82 +354,94 @@
      <sect2 id="freebsdupdate-upgrade">
        <title>Major and Minor Upgrades</title>

-      <para>This process will remove old object files and
-	libraries which will break most third party applications.
-	It is recommended that all installed ports either be removed
-	and re-installed or upgraded later using the
-	<filename role="package">ports-mgmt/portupgrade</filename>
-	utility.  Most users will want to run a test build using
-	the following command:</para>
+      <para>Upgrades from one minor version of &os; to another, like
+	from &os;-9.0 to &os;-9.1, are called
+	<emphasis>minor</emphasis> upgrades.  Generally, installed
+	applications will continue to work without problems after
+	minor upgrades.</para>

-      <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
+      <para><emphasis>Major</emphasis> upgrades are when &os is
+	upgraded from one major version of &os; to another, like from
+	&os;-8.x to &os;-9.x.</para>

-      <para>This will ensure everything will be re-installed
-	correctly.  Note that setting the
-	<makevar>BATCH</makevar> environment variable to
-	<literal>yes</literal> will answer <literal>yes</literal> to
-	any prompts during this process, removing the need for
-	manual intervention during the build process.</para>
+      <warning>
+	<para>Major upgrades will remove old object files and
+	  libraries which will break most third party applications.
+	  It is recommended that all installed ports either be removed
+	  and re-installed or upgraded after a major upgrade by using the
+	  <filename role="package">ports-mgmt/portupgrade</filename>
+	  utility.  A brute-force rebuild of all installed
+	  applications can be accomplished with this command:</para>

-      <para>If a custom kernel is in use, the upgrade process is
-	slightly more involved.  A copy of the
-	<filename>GENERIC</filename> kernel is needed, and it should
-	be placed in
-	<filename class="directory">/boot/GENERIC</filename>.  If the
-	<filename>GENERIC</filename> kernel is not already present in
-	the system, it may be obtained using one of the following
-	methods:</para>
+	<screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>

-      <itemizedlist>
-	<listitem>
-	  <para>If a custom kernel has only been built once, the
-	    kernel in
-	    <filename class="directory">/boot/kernel.old</filename> is
-	    actually the <filename>GENERIC</filename> one.  Simply
-	    rename this directory to <filename
-	      class="directory">/boot/GENERIC</filename>.</para>
-	</listitem>
+	<para>This will ensure everything will be re-installed
+	  correctly.  Note that setting the
+	  <makevar>BATCH</makevar> environment variable to
+	  <literal>yes</literal> will answer <literal>yes</literal> to
+	  any prompts during this process, removing the need for
+	  manual intervention during the build process.</para>

-	<listitem>
-	  <para>Assuming physical access to the machine is possible, a
-	    copy of the <filename>GENERIC</filename> kernel can be
-	    installed from the CD-ROM media.  Insert your installation
-	    disc and use the following commands:</para>
+	<para>If a custom kernel is in use, the upgrade process is
+	  slightly more involved.  A copy of the
+	  <filename>GENERIC</filename> kernel is needed, and it should
+	  be placed in
+	  <filename class="directory">/boot/GENERIC</filename>.  If the
+	  <filename>GENERIC</filename> kernel is not already present in
+	  the system, it may be obtained using one of the following
+	  methods:</para>

-	  <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+	<itemizedlist>
+	  <listitem>
+	    <para>If a custom kernel has only been built once, the
+	      kernel in
+	      <filename class="directory">/boot/kernel.old</filename> is
+	      actually the <filename>GENERIC</filename> one.  Simply
+	      rename this directory to <filename
+		class="directory">/boot/GENERIC</filename>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Assuming physical access to the machine is possible, a
+	      copy of the <filename>GENERIC</filename> kernel can be
+	      installed from the CD-ROM media.  Insert your installation
+	      disc and use the following commands:</para>
+
+	    <screen>&prompt.root; <userinput>mount /cdrom</userinput>
  &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
  &prompt.root; <userinput>./install.sh GENERIC</userinput></screen>

-	  <para>Replace <filename
-	      class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
-	    with the actual version of the release you are using.  The
-	    <filename>GENERIC</filename> kernel will be installed in
-	    <filename class="directory">/boot/GENERIC</filename> by
-	    default.</para>
-	</listitem>
+	    <para>Replace <filename
+	        class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
+	      with the actual version of the release you are using.  The
+	      <filename>GENERIC</filename> kernel will be installed in
+	      <filename class="directory">/boot/GENERIC</filename> by
+	      default.</para>
+	  </listitem>

-	<listitem>
-	  <para>Failing all the above, the
-	    <filename>GENERIC</filename> kernel may be rebuilt and
-	    installed from the sources:</para>
+	  <listitem>
+	    <para>Failing all the above, the
+	      <filename>GENERIC</filename> kernel may be rebuilt and
+	      installed from the sources:</para>

-	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+	    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
  &prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel</userinput>
  &prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
  &prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>

-	  <para>For this kernel to be picked up as
-	    <filename>GENERIC</filename>
-	    by <command>freebsd-update</command>, the
-	    <filename>GENERIC</filename> configuration file must not
-	    have been modified in any way.  It is also suggested that
-	    it is built without any other special options (preferably
-	    with an empty <filename>/etc/make.conf</filename>).</para>
-	</listitem>
-      </itemizedlist>
+	    <para>For this kernel to be picked up as
+	      <filename>GENERIC</filename>
+	      by <command>freebsd-update</command>, the
+	      <filename>GENERIC</filename> configuration file must not
+	      have been modified in any way.  It is also suggested that
+	      it is built without any other special options (preferably
+	      with an empty <filename>/etc/make.conf</filename>).</para>
+	  </listitem>
+	</itemizedlist>

-      <para>Rebooting to the <filename>GENERIC</filename> kernel is
-	not required at this stage.</para>
+	<para>Rebooting to the <filename>GENERIC</filename> kernel is
+	  not required at this stage.</para>
+      </warning>

        <para>Major and minor version updates may be performed by
  	providing <command>freebsd-update</command> with a release
@@ -552,7 +564,7 @@
  	  three.</para>
        </note>

-      <para>All third party software will now need to be rebuilt and
+      <para>After a major upgrade, all third party software will now need to be rebuilt and
  	re-installed.  This is required as installed software may
  	depend on libraries which have been removed during the upgrade
  	process.  The
-------------- next part --------------
Index: cutting-edge/chapter.xml
===================================================================
--- cutting-edge/chapter.xml	(revision 40586)
+++ cutting-edge/chapter.xml	(working copy)
@@ -354,82 +354,94 @@
     <sect2 id="freebsdupdate-upgrade">
       <title>Major and Minor Upgrades</title>
 
-      <para>This process will remove old object files and
-	libraries which will break most third party applications.
-	It is recommended that all installed ports either be removed
-	and re-installed or upgraded later using the
-	<filename role="package">ports-mgmt/portupgrade</filename>
-	utility.  Most users will want to run a test build using
-	the following command:</para>
+      <para>Upgrades from one minor version of &os; to another, like
+	from &os;-9.0 to &os;-9.1, are called
+	<emphasis>minor</emphasis> upgrades.  Generally, installed
+	applications will continue to work without problems after
+	minor upgrades.</para>
 
-      <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
+      <para><emphasis>Major</emphasis> upgrades are when &os is
+	upgraded from one major version of &os; to another, like from
+	&os;-8.x to &os;-9.x.</para>
 
-      <para>This will ensure everything will be re-installed
-	correctly.  Note that setting the
-	<makevar>BATCH</makevar> environment variable to
-	<literal>yes</literal> will answer <literal>yes</literal> to
-	any prompts during this process, removing the need for
-	manual intervention during the build process.</para>
+      <warning>
+	<para>Major upgrades will remove old object files and
+	  libraries which will break most third party applications.
+	  It is recommended that all installed ports either be removed
+	  and re-installed or upgraded after a major upgrade by using the
+	  <filename role="package">ports-mgmt/portupgrade</filename>
+	  utility.  A brute-force rebuild of all installed
+	  applications can be accomplished with this command:</para>
 
-      <para>If a custom kernel is in use, the upgrade process is
-	slightly more involved.  A copy of the
-	<filename>GENERIC</filename> kernel is needed, and it should
-	be placed in
-	<filename class="directory">/boot/GENERIC</filename>.  If the
-	<filename>GENERIC</filename> kernel is not already present in
-	the system, it may be obtained using one of the following
-	methods:</para>
+	<screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
 
-      <itemizedlist>
-	<listitem>
-	  <para>If a custom kernel has only been built once, the
-	    kernel in
-	    <filename class="directory">/boot/kernel.old</filename> is
-	    actually the <filename>GENERIC</filename> one.  Simply
-	    rename this directory to <filename
-	      class="directory">/boot/GENERIC</filename>.</para>
-	</listitem>
+	<para>This will ensure everything will be re-installed
+	  correctly.  Note that setting the
+	  <makevar>BATCH</makevar> environment variable to
+	  <literal>yes</literal> will answer <literal>yes</literal> to
+	  any prompts during this process, removing the need for
+	  manual intervention during the build process.</para>
 
-	<listitem>
-	  <para>Assuming physical access to the machine is possible, a
-	    copy of the <filename>GENERIC</filename> kernel can be
-	    installed from the CD-ROM media.  Insert your installation
-	    disc and use the following commands:</para>
+	<para>If a custom kernel is in use, the upgrade process is
+	  slightly more involved.  A copy of the
+	  <filename>GENERIC</filename> kernel is needed, and it should
+	  be placed in
+	  <filename class="directory">/boot/GENERIC</filename>.  If the
+	  <filename>GENERIC</filename> kernel is not already present in
+	  the system, it may be obtained using one of the following
+	  methods:</para>
 
-	  <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+	<itemizedlist>
+	  <listitem>
+	    <para>If a custom kernel has only been built once, the
+	      kernel in
+	      <filename class="directory">/boot/kernel.old</filename> is
+	      actually the <filename>GENERIC</filename> one.  Simply
+	      rename this directory to <filename
+		class="directory">/boot/GENERIC</filename>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Assuming physical access to the machine is possible, a
+	      copy of the <filename>GENERIC</filename> kernel can be
+	      installed from the CD-ROM media.  Insert your installation
+	      disc and use the following commands:</para>
+
+	    <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
 &prompt.root; <userinput>./install.sh GENERIC</userinput></screen>
 
-	  <para>Replace <filename
-	      class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
-	    with the actual version of the release you are using.  The
-	    <filename>GENERIC</filename> kernel will be installed in
-	    <filename class="directory">/boot/GENERIC</filename> by
-	    default.</para>
-	</listitem>
+	    <para>Replace <filename
+	        class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
+	      with the actual version of the release you are using.  The
+	      <filename>GENERIC</filename> kernel will be installed in
+	      <filename class="directory">/boot/GENERIC</filename> by
+	      default.</para>
+	  </listitem>
 
-	<listitem>
-	  <para>Failing all the above, the
-	    <filename>GENERIC</filename> kernel may be rebuilt and
-	    installed from the sources:</para>
+	  <listitem>
+	    <para>Failing all the above, the
+	      <filename>GENERIC</filename> kernel may be rebuilt and
+	      installed from the sources:</para>
 
-	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+	    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel</userinput>
 &prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
 &prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
 
-	  <para>For this kernel to be picked up as
-	    <filename>GENERIC</filename>
-	    by <command>freebsd-update</command>, the
-	    <filename>GENERIC</filename> configuration file must not
-	    have been modified in any way.  It is also suggested that
-	    it is built without any other special options (preferably
-	    with an empty <filename>/etc/make.conf</filename>).</para>
-	</listitem>
-      </itemizedlist>
+	    <para>For this kernel to be picked up as
+	      <filename>GENERIC</filename>
+	      by <command>freebsd-update</command>, the
+	      <filename>GENERIC</filename> configuration file must not
+	      have been modified in any way.  It is also suggested that
+	      it is built without any other special options (preferably
+	      with an empty <filename>/etc/make.conf</filename>).</para>
+	  </listitem>
+	</itemizedlist>
 
-      <para>Rebooting to the <filename>GENERIC</filename> kernel is
-	not required at this stage.</para>
+	<para>Rebooting to the <filename>GENERIC</filename> kernel is
+	  not required at this stage.</para>
+      </warning>
 
       <para>Major and minor version updates may be performed by
 	providing <command>freebsd-update</command> with a release
@@ -552,7 +564,7 @@
 	  three.</para>
       </note>
 
-      <para>All third party software will now need to be rebuilt and
+      <para>After a major upgrade, all third party software will now need to be rebuilt and
 	re-installed.  This is required as installed software may
 	depend on libraries which have been removed during the upgrade
 	process.  The