Bug 256654 : Improve/Add to the upgrade instructions

Patch by Shane H. W. Travis <travis@sedsystems.ca>  r=colin.ogilvie

1 files changed, 257 insertions, 128 deletions

diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index 3b84f40c8..772e4abf0 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -1436,204 +1436,333 @@ Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
   <section id="upgrading">
     <title>Upgrading to New Releases</title>
 
-    <warning>
-      <para>Upgrading is a one-way process. You should backup your database
-      and current Bugzilla directory before attempting the upgrade. If you wish
-      to revert to the old Bugzilla version for any reason, you will have to
-      restore from these backups.
-      </para>
-    </warning>
-
-    <para>Upgrading Bugzilla is something we all want to do from time to time,
-    be it to get new features or pick up the latest security fix. How easy
-    it is to update depends on a few factors.
+    <para>
+      Upgrading Bugzilla is something we all want to do from time to time,
+      be it to get new features or pick up the latest security fix. How easy
+      it is to update depends on a few factors:
     </para>
 
     <itemizedlist>
       <listitem>
-        <para>If the new version is a revision or a new point release</para>
+        <para>
+          If the new version is a revision or a new point release
+        </para>
       </listitem>
       <listitem>
-        <para>How many, if any, local changes have been made</para>
+        <para>
+          How many local changes (if any) have been made
+        </para>
       </listitem>
     </itemizedlist>
 
-    <para>There are also three different methods to upgrade your installation.
-    </para>
+    <section id="upgrading-version-defns">
+      <title>Version Definitions</title>
 
-    <orderedlist>
-      <listitem>
-        <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para>
-      </listitem>
-      <listitem>
-        <para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para>
-      </listitem>
-      <listitem>
-        <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para>
-      </listitem>
-    </orderedlist>
+      <para>
+        Bugzilla displays the version you are using at the top of most
+        pages you load. It will look something like '2.16.7' or '2.18rc3'
+        or '2.19.1+'. The first number in this series is the Major Version.
+        This does not change very often (that is to say, almost never);
+        Bugzilla was 1.x.x when it was first created, and went to 2.x.x
+        when it was re-written in perl in Sept 1998. If/When the major version
+        is changed to 3.x.x, it will signify a significant structural change
+        and will be accompanied by much fanfare and many instructions on
+        how to upgrade, including a revision to this page. :)
+      </para>
 
-    <para>Which options are available to you may depend on how large a jump
-    you are making and/or your network configuration.
-    </para>
+      <para>
+        The second number in the version is called the 'minor number', and
+        a release that changes the minor number is called a 'point release'.
+        An even number in this position (2.14, 2.16, 2.18, 2.20, etc.)
+        represents a stable version, while an odd number (2.17, 2.19, etc.)
+        represents a development version. In the past, stable point releases
+        were feature-based, coming when certain enhancements had been
+        completed, or the Bugzilla development team felt that enough
+        progress had been made overall. As of version 2.18, however,
+        Bugzilla has moved to a time-based release schedule; current plans
+        are to create a stable point release every 6 months or so after
+        2.18 is deployed.
+      </para>
 
-    <para>Revisions are normally released to fix security vulnerabilities
-    and are distinguished by an increase in the third number. For example,
-    when 2.16.6 was released, it was a revision to 2.16.5.
-    </para>
+      <para>
+        The third number in the Bugzilla version represents a bugfix version.
+        Bugfix Revisions are normally released only to address security
+        vulnerabilities; in the future, it is likely that the Bugzilla
+        development team will back-port bugfixes in a new point release to
+        the old point release for a limited period. Once enough of these
+        bugfixes have accumulated (or a new security vulnerability is
+        identified and closed), a bugfix release will be made. As an 
+        example, 2.16.6 was a bugfix release, and improved on 2.16.5.
+      </para>
 
-    <para>Point releases are normally released when the Bugzilla team feels
-    that there has been a significant amount of progress made between the
-    last point release and the current time. These are often proceeded by a
-    stabilization period and release candidates, however the use of 
-    development versions or release candidates is beyond the scope of this
-    document. Point releases can be distinguished by an increase in the
-    second number, or minor version. For example, 2.18.0 is a newer point
-    release than 2.16.5.
-    </para>
+      <note>
+        <para>
+          When reading version numbers, everything separated by a point ('.')
+          should be read as a single number. It is <emphasis>not</emphasis>
+          the same as decimal. 2.14 is newer than 2.8 because minor version
+          14 is greater than minor version 8. 2.24.11 would be newer than
+          2.24.9 (because bugfix 11 is greater than bugfix 9. This is
+          confusing to some people who aren't used to dealing with software.
+        </para>
+      </note>
+    </section>
 
-    <para>The examples in this section are written as if you were updating
-    to version 2.18.1.  The procedures are the same regardless if you are
-    updating to a new point release or a new revision.  However, the chance
-    of running into trouble increases when upgrading to a new point release,
-    escpecially if you've made local changes.
-    </para>
+    <section id="upgrading-methods">
+    <title>Upgrading - Methods and Procedure</title>
+      <para>
+        There are three different ways to upgrade your installation.
+      </para>
 
-    <para>These examples also assume that your Bugzilla installation is at
-    <filename>/var/www/html/bugzilla</filename>. If that is not the case,
-    simply substitute the proper paths where appropriate.
-    </para>
+      <orderedlist>
+        <listitem>
+          <para>
+            Using CVS (<xref linkend="upgrade-cvs"/>)
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Downloading a new tarball (<xref linkend="upgrade-tarball"/>)
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Applying the relevant patches (<xref linkend="upgrade-patches"/>)
+          </para>
+        </listitem>
+      </orderedlist>
 
-    <example id="upgrade-cvs">
+      <para>
+        Each of these options has its own pros and cons; the one that's
+        right for you depends on how long it has been since you last
+        installed, the degree to which you have customized your installation,
+        and/or your network configuration. (Some discussion of the various
+        methods of updating compared with degree and methods of local
+        customization can be found in <xref linkend="template-method"/>.)
+      </para>
+
+      <para>
+        The larger the jump you are trying to make, the more difficult it
+        is going to be to upgrade if you have made local customizations.
+        Upgrading from 2.18 to 2.18.1 should be fairly painless even if
+        you are heavily customized, but going from 2.14 to 2.18 is going
+        to mean a fair bit of work re-writing your local changes to use
+        the new files, logic, templates, etc. If you have done no local
+        changes at all, however, then upgrading should be approximately
+        the same amount of work regardless of how long it has been since
+        your version was released.
+      </para>
+
+      <warning>
+        <para>
+          Upgrading is a one-way process. You should backup your database
+          and current Bugzilla directory before attempting the upgrade. If
+          you wish to revert to the old Bugzilla version for any reason, you
+          will have to restore from these backups.
+        </para>
+      </warning>
+
+      <para>
+        The examples in the following sections are written as though the
+        user were updating to version 2.18.1, but the procedures are the
+        same regardless of whether one is updating to a new point release
+        or simply trying to obtain a new bugfix release. Also, in the
+        examples the user's Bugzilla installation is found at
+        <filename>/var/www/html/bugzilla</filename>. If that is not the
+        same as the location of your Bugzilla installation, simply
+        substitute the proper paths where appropriate.
+      </para>
+
+      <section id="upgrade-cvs">
       <title>Upgrading using CVS</title>
 
-      <para>Every release of Bugzilla, whether it is a revision or a point
-      release, is tagged in CVS.  Also, every tarball we have distributed
-      since version 2.12 has been primed for using CVS. This does, however,
-      require that you are able to access cvs-mirror.mozilla.org on port
-      2401.
+        <para>
+          Every release of Bugzilla, whether it is a point release or a bugfix,
+          is tagged in CVS.  Also, every tarball that has been distributed since
+          version 2.12 has been created in such a way that it can be used with
+          CVS once it is unpacked. Doing so, however, requires that you are able
+          to access cvs-mirror.mozilla.org on port 2401, which may not be an
+          option or a possibility for some users, especially those behind a
+          highly restrictive firewall.
+        </para>
 
         <tip>
-          <para>If you can do this, updating using CVS is probably the most
-          painless method, especially if you have a lot of local changes.
+          <para>
+            If you can, updating using CVS is probably the most painless
+            method, especially if you have a lot of local changes.
           </para>
         </tip>
-      </para>
 
-      <programlisting>
+        <para>
+          The following shows the sequence of commands needed to update a
+          Bugzilla installation via CVS, and a typical series of results.
+        </para>
+
+        <programlisting>
 bash$ <command>cd /var/www/html/bugzilla</command>
 bash$ <command>cvs login</command>
 Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
-CVS password: <command>anonymous</command>
+CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis>
 bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command>
 P checksetup.pl
 P collectstats.pl
 P globals.pl
 P docs/rel_notes.txt
 P template/en/default/list/quips.html.tmpl
-      </programlisting>
+<emphasis>(etc.)</emphasis>
+        </programlisting>
 
-      <para>
         <caution>
-          <para>If a line in the output from <command>cvs update</command>
-          begins with a <computeroutput>C</computeroutput> that represents a
-          file with local changes that CVS was unable to properly merge. You
-          need to resolve these conflicts manually before Bugzilla (or at
-          least the portion using that file) will be usable.
+          <para>
+            If a line in the output from <command>cvs update</command> begins
+            with a <computeroutput>C</computeroutput>, then that represents a
+            file with local changes that CVS was unable to properly merge. You
+            need to resolve these conflicts manually before Bugzilla (or at
+            least the portion using that file) will be usable.
           </para>
         </caution>
+      </section>
 
-        <note>
-          <para>You also need to run <command>./checksetup.pl</command>
-          before your Bugzilla upgrade will be complete.
-          </para>
-        </note>
-      </para>
-    </example>
+      <section id="upgrade-tarball">
+        <title>Upgrading using the tarball</title>
 
-    <example id="upgrade-tarball">
-      <title>Upgrading using the tarball</title>
+        <para>
+          If you are unable (or unwilling) to use CVS, another option that's
+          always available is to obtain the latest tarball from the <ulink
+          href="http://www.bugzilla.org/download/">Download Page</ulink> and 
+          create a new Bugzilla installation from that.
+        </para>
 
-      <para>If you are unable or unwilling to use CVS, another option that's
-      always available is to download the latest tarball. This is the most
-      difficult option to use, especially if you have local changes.
-      </para>
+        <para>
+          This sequence of commands shows how to get the tarball from the
+          command-line; it is also possible to download it from the site
+          directly in a web browser. If you go that route, save the file
+          to the <filename class="directory">/var/www/html</filename>
+          directory (or its equivalent, if you use something else) and 
+          omit the first three lines of the example.
+        </para>
 
-      <programlisting>
+        <programlisting>
 bash$ <command>cd /var/www/html</command>
 bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command>
-<emphasis>Output omitted</emphasis>
+<emphasis>(Output omitted)</emphasis>
 bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command>
 bugzilla-2.18.1/
 bugzilla-2.18.1/.cvsignore
 bugzilla-2.18.1/1x1.gif
-<emphasis>Output truncated</emphasis>
+<emphasis>(Output truncated)</emphasis>
 bash$ <command>cd bugzilla-2.18.1</command>
 bash$ <command>cp ../bugzilla/localconfig* .</command>
 bash$ <command>cp -r ../bugzilla/data .</command>
 bash$ <command>cd ..</command>
 bash$ <command>mv bugzilla bugzilla.old</command>
 bash$ <command>mv bugzilla-2.18.1 bugzilla</command>
-bash$ <command>cd bugzilla</command>
-bash$ <command>./checksetup.pl</command>
-<emphasis>Output omitted</emphasis>
-      </programlisting>
+        </programlisting>
 
-      <para>
         <warning>
-          <para>The <command>cp</command> commands both end with periods which
-          is a very important detail, it tells the shell that the destination
-          directory is the current working directory. Also, the period at the
-          beginning of the <command>./checksetup.pl</command> is important and
-          can not be omitted.
+          <para>
+            The <command>cp</command> commands both end with periods which
+            is a very important detail, it tells the shell that the destination
+            directory is the current working directory. 
           </para>
         </warning>
 
-        <note>
-          <para>You will now have to reapply any changes you have made to your
-          local installation manually.
-          </para>
-        </note>
-      </para>
-    </example>
-
-    <example id="upgrade-patches">
-      <title>Upgrading using patches</title>
-
-      <para>The Bugzilla team will normally make a patch file available for
-      revisions to go from the most recent revision to the new one. You could
-      also read the release notes and grab the patches attached to the
-      mentioned bug, but it is safer to use the released patch file as
-      sometimes patches get changed before they get checked in. 
-      It is also theoretically possible to
-      scour the fixed bug list and pick and choose which patches to apply
-      from a point release, but this is not recommended either as what you'll
-      end up with is a hodge podge Bugzilla that isn't really any version.
-      This would also make it more difficult to upgrade in the future.
-      </para>
+        <para>
+          This upgrade method will give you a clean install of Bugzilla with the 
+          same version as the tarball. That's fine if you don't have any local
+          customizations that you want to maintain, but if you do then you will 
+          need to reapply them by hand to the appropriate files. 
+        </para>
 
-      <programlisting>
+        <para>
+          It's worth noting that since 2.12, the Bugzilla tarballs come
+          CVS-ready, so if you decide at a later date that you'd rather use
+          CVS as an upgrade method, your code will already be set up for it.
+        </para>
+      </section>
+
+      <section id="upgrade-patches">
+        <title>Upgrading using patches</title>
+
+        <para>
+          If you are doing a bugfix upgrade -- that is, one where only the 
+          last number of the revision changes, such as from 2.16.6 to 2.16.7
+          -- then you have the option of obtaining and applying a patch file
+          from the <ulink
+          href="http://www.bugzilla.org/download/">Download Page</ulink>.
+          This file is made available by the <ulink
+          href="http://www.bugzilla.org/developers/profiles.html">Bugzilla
+          Development Team</ulink>, and is a collection of all the bug fixes
+          and security patches that have been made since the last bugfix
+          release. If you are planning to upgrade via patches, it is safer
+          to grab this developer-made patch file than to read the patch
+          notes and apply all (or even just some of) the patches oneself,
+          as sometimes patches on bugs get changed before they get checked in.
+        </para>
+
+        <para>
+          As above, this example starts with obtaining the file via the 
+          command line. If you have already downloaded it, you can omit the
+          first two commands.
+        </para>
+
+        <programlisting>
 bash$ <command>cd /var/www/html/bugzilla</command>
 bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command>
-<emphasis>Output omitted</emphasis>
+<emphasis>(Output omitted)</emphasis>
 bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command>
 bash$ <command>patch -p1 &lt; bugzilla-2.18.0-to-2.18.1.diff</command>
 patching file checksetup.pl
 patching file collectstats.pl
 patching file globals.pl
+<emphasis>(etc.)</emphasis>
+        </programlisting>
+
+        <warning>
+          <para>
+            Be aware that upgrading from a patch file does not change the
+            entries in your <filename class="directory">CVS</filename> directory.
+            This could make it more difficult to upgrade using CVS
+            (<xref linkend="upgrade-cvs"/>) in the future.
+          </para>
+        </warning>
+
+      </section>
+    </section>
+
+    <section id="upgrading-completion">
+    <title>Completing Your Upgrade</title>
+
+      <para>
+        Regardless of which upgrade method you choose, you will need to
+        run <command>./checksetup.pl</command> before your Bugzilla
+        upgrade will be complete.
+      </para>
+
+      <programlisting>
+bash$ <command>cd bugzilla</command>
+bash$ <command>./checksetup.pl</command>
       </programlisting>
 
+      <warning>
+        <para>
+          The period at the beginning of the command
+          <command>./checksetup.pl</command> is important and can not
+          be omitted.
+        </para>
+      </warning>
+          
       <para>
-        <caution>
-          <para>If you do this, beware that this doesn't change the entires in
-          your <filename id="dir">CVS</filename> directory so it may make
-          updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the
-          future.
-          </para>
-        </caution>
+        If you have done a lot of local modifications, it wouldn't hurt
+        to run the Bugzilla Testing suite. This is not a required step,
+        but it isn't going to hurt anything, and might help point out
+        some areas that could be improved. (More information on the
+        test suite can be had by following this link to the appropriate
+        section in the <ulink
+        url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers'
+        Guide</ulink>.)
       </para>
-    </example>
 
+    </section>
   </section>
 </chapter>