Bug 371020: Overhaul the "Upgrading to a New Release" section

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit

2 files changed, 419 insertions, 345 deletions

diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index 9924a742e..2ed037609 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -3045,7 +3045,6 @@ ReadOnly: ENTRY, NA/NA, CANEDIT
      </para>
 
     </section>
-
   </section>
 
   <section id="sanitycheck">
@@ -3086,349 +3085,6 @@ ReadOnly: ENTRY, NA/NA, CANEDIT
 
   </section>
 
-  <section id="upgrading">
-    <title>Upgrading to New Releases</title>
-
-    <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>
-      </listitem>
-      <listitem>
-        <para>
-          How many local changes (if any) have been made
-        </para>
-      </listitem>
-    </itemizedlist>
-
-    <section id="upgrading-version-defns">
-      <title>Version Definitions</title>
-
-      <para>
-        Bugzilla displays the version you are using at the top of the home
-        page <filename>index.cgi</filename>. It looks something like
-        '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is
-        the Major Version. This does not change very often;
-        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. The major version
-        3.x.x, released in early 2007, is pretty far from what the 2.x.x
-        series looked like, both about its UI and its code.
-      </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.18, 2.20, 2.22, 3.0, 3.2, etc.)
-        represents a stable version, while an odd number (2.19, 2.21, 2.23, 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>
-        The third number in the Bugzilla version represents a bugfix version.
-        Bugfix Revisions are released only to address security vulnerabilities
-        and, for a limited period, bug fixes. Once enough of these
-        bugfixes have accumulated (or a new security vulnerability is
-        identified and closed), a bugfix release is made. As an
-        example, 2.20.3 was a bugfix release, and improved on 2.20.2.
-      </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.22 is newer than 2.8 because minor version
-          22 is greater than minor version 8. The now unsupported release 2.16.11
-          was newer than 2.16.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>
-
-    <section id="upgrading-notifications">
-      <title>Upgrading - Notifications</title>
-
-      <para>
-        Bugzilla 3.0 introduces the ability to automatically notify
-        administrators when new releases are available, based on the
-        <literal>upgrade_notification</literal> parameter, see
-        <xref linkend="parameters"/>. Administrators will see these
-        notifications when they access the <filename>index.cgi</filename>
-        page, i.e. generally when logging in. Bugzilla will check once per
-        day for new releases, unless the parameter is set to
-        <quote>disabled</quote>. If you are behind a proxy, you may have to set
-        the <literal>proxy_url</literal> parameter accordingly. If the proxy
-        requires authentication, use the
-        <literal>http://user:pass@proxy_url/</literal> syntax.
-      </para>
-    </section>
-
-    <section id="upgrading-methods">
-    <title>Upgrading - Methods and Procedure</title>
-      <para>
-        There are three different ways to upgrade your installation.
-      </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>
-
-      <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.22 to 2.22.1 should be fairly painless even if
-        you are heavily customized, but going from 2.18 to 3.0 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.22.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 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, updating using CVS is probably the most painless
-            method, especially if you have a lot of local changes.
-          </para>
-        </tip>
-
-        <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: <emphasis>('anonymous', or just leave it blank)</emphasis>
-bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command>
-P checksetup.pl
-P collectstats.pl
-P docs/rel_notes.txt
-P template/en/default/list/quips.html.tmpl
-<emphasis>(etc.)</emphasis>
-        </programlisting>
-
-        <caution>
-          <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>
-
-      <section 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
-          url="http://www.bugzilla.org/download/">Download Page</ulink> and 
-          create a new Bugzilla installation from that.
-        </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>
-bash$ <command>cd /var/www/html</command>
-bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command>
-<emphasis>(Output omitted)</emphasis>
-bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command>
-bugzilla-2.22.1/
-bugzilla-2.22.1/.cvsignore
-<emphasis>(Output truncated)</emphasis>
-bash$ <command>cd bugzilla-2.22.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.22.1 bugzilla</command>
-        </programlisting>
-
-        <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. 
-          </para>
-        </warning>
-
-        <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>
-
-        <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.22 to 2.22.1
-          -- then you have the option of obtaining and applying a patch file
-          from the <ulink
-          url="http://www.bugzilla.org/download/">Download Page</ulink>.
-          This file is made available by the <ulink
-          url="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 http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command>
-<emphasis>(Output omitted)</emphasis>
-bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command>
-bash$ <command>patch -p1 &lt; bugzilla-2.22-to-2.22.1.diff</command>
-patching file checksetup.pl
-patching file collectstats.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>
-        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>
-
-    </section>
-  </section>
 
 </chapter>
 
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 78867e725..341dd42f6 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.157 2008/04/13 19:25:18 lpsolit%gmail.com Exp $ -->
+<!-- $Id: installation.xml,v 1.158 2008/08/07 00:24:32 mkanat%bugzilla.org Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -2017,6 +2017,424 @@ pid-file=/home/foo/mymysql/the.pid
     </section>
   </section>
 
+
+  <section id="upgrade">
+    <title>Upgrading to New Releases</title>
+    
+    <para>Upgrading to new Bugzilla releases is very simple. There is
+      a script included with Bugzilla that will automatically
+      do all of the database migration for you.</para>
+    
+    <para>The following sections explain how to upgrade from one
+      version of Bugzilla to another. Whether you are upgrading
+      from one bug-fix version to another (such as 3.0.1 to 3.0.2)
+      or from one major version to another (such as from 3.0 to 3.2),
+      the instructions are always the same.</para>
+
+    <note>
+      <para>
+        Any examples in the following sections are written as though the
+        user were updating to version 2.22.1, but the procedures are the
+        same no matter what version you're updating to. 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>
+    </note>
+
+    <section id="upgrade-before">
+      <title>Before You Upgrade</title>
+    
+      <para>Before you start your upgrade, there are a few important
+        steps to take:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>
+            Read the <ulink url="http://www.bugzilla.org/releases/">Release
+            Notes</ulink> of the version you're upgrading to,
+            particularly the "Notes for Upgraders" section.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            View the Sanity Check (<xref linkend="sanitycheck"/>) page
+            on your installation before upgrading. Attempt to fix all warnings
+            that the page produces before you go any further, or you may
+            experience problems  during your upgrade.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            Shut down your Bugzilla installation by putting some HTML or
+            text in the shutdownhtml parameter
+            (see <xref linkend="parameters"/>).
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            Make a backup of the Bugzilla database.
+            <emphasis>THIS IS VERY IMPORTANT</emphasis>. If
+            anything goes wrong during the upgrade, your installation
+            can be corrupted beyond recovery. Having a backup keeps you safe.
+          </para>
+
+          <warning>
+            <para>
+              Upgrading is a one-way process. You cannot "downgrade" an
+              upgraded Bugzilla. If you wish to revert to the old Bugzilla
+              version for any reason, you will have to restore your database
+              from this backup.
+            </para>
+          </warning>
+
+          <para>Here are some sample commands you could use to backup
+            your database, depending on what database system you're
+            using. You may have to modify these commands for your
+            particular setup.</para>
+          
+          <variablelist>
+            <varlistentry>
+              <term>MySQL:</term>
+              <listitem>
+                <para>
+                  <command>mysqldump --opt -u bugs -p bugs > bugs.sql</command>
+                </para>
+              </listitem>
+            </varlistentry>
+              
+            <varlistentry>
+              <term>PostgreSQL:</term>
+              <listitem>
+                <para>
+                  <command>pg_dump --no-privileges --no-owner -h localhost -U bugs
+                    > bugs.sql</command>
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </orderedlist>
+    </section>
+      
+    <section id="upgrade-files">
+      <title>Getting The New Bugzilla</title>
+      
+      <para>There are three ways to get the new version of Bugzilla.
+        We'll list them here briefly and then explain them
+        more later.</para>
+      
+      <variablelist>
+        <varlistentry>
+          <term>CVS (<xref linkend="upgrade-cvs"/>)</term>
+          <listitem>
+            <para>
+              If have <command>cvs</command> installed on your machine
+              and you have Internet access, this is the easiest way to
+              upgrade, particularly if you have made modifications
+              to the code or templates of Bugzilla.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>Download the tarball (<xref linkend="upgrade-tarball"/>)</term>
+          <listitem>
+            <para>
+              This is a very simple way to upgrade, and good if you
+              haven't made many (or any) modifications to the code or
+              templates of your Bugzilla.
+            </para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>Patches (<xref linkend="upgrade-patches"/>)</term>
+          <listitem>
+            <para>
+              If you have made modifications to your Bugzilla, and
+              you don't have Internet access or you don't want to use
+              cvs, then this is the best way to upgrade.
+            </para>
+            
+            <para>
+              You can only do minor upgrades (such as 3.0 to 3.0.1 or
+              3.0.1 to 3.0.2) with patches.
+            </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+        
+      <section id="upgrade-modified">
+        <title>If you have modified your Bugzilla</title>
+      
+        <para>
+          If you have modified the code or templates of your Bugzilla,
+          then upgrading requires a bit more thought and effort.
+          A 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 3.0 to 3.0.1 should be fairly painless even if
+          you are heavily customized, but going from 2.18 to 3.0 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>
+      </section>
+
+      <section id="upgrade-cvs">
+        <title>Upgrading using CVS</title>
+
+        <para>
+          This requires that you have cvs installed (most Unix machines do),
+          and requires that you are able to access cvs-mirror.mozilla.org
+          on port 2401, which may not be an option if you are behind a
+          highly restrictive firewall or don't have Internet access.
+        </para>
+
+        <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: <emphasis>('anonymous', or just leave it blank)</emphasis>
+bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command>
+P checksetup.pl
+P collectstats.pl
+P docs/rel_notes.txt
+P template/en/default/list/quips.html.tmpl
+<emphasis>(etc.)</emphasis>
+        </programlisting>
+
+        <caution>
+          <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>
+
+      <section 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
+          url="http://www.bugzilla.org/download/">Download Page</ulink> and 
+          create a new Bugzilla installation from that.
+        </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>
+bash$ <command>cd /var/www/html</command>
+bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command>
+<emphasis>(Output omitted)</emphasis>
+bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command>
+bugzilla-2.22.1/
+bugzilla-2.22.1/.cvsignore
+<emphasis>(Output truncated)</emphasis>
+bash$ <command>cd bugzilla-2.22.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.22.1 bugzilla</command>
+        </programlisting>
+
+        <warning>
+          <para>
+            The <command>cp</command> commands both end with periods which
+            is a very important detail--it means that the destination
+            directory is the current working directory.
+          </para>
+        </warning>
+
+        <para>
+          This upgrade method will give you a clean install of Bugzilla.
+          That's fine if you don't have any local customizations that you
+          want to maintain. If you do have customizations, then you will 
+          need to reapply them by hand to the appropriate files.
+        </para>
+      </section>
+
+      <section id="upgrade-patches">
+        <title>Upgrading using patches</title>
+
+        <para>
+          A patch is a collection of all the bug fixes that have been made
+          since the last bug-fix release.
+        </para>
+        
+        <para>
+          If you are doing a bug-fix upgrade&mdash;that is, one where only the 
+          last number of the revision changes, such as from 2.22 to
+          2.22.1&mdash;then you have the option of obtaining and applying a
+          patch file from the <ulink
+          url="http://www.bugzilla.org/download/">Download Page</ulink>.
+        </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 http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command>
+<emphasis>(Output omitted)</emphasis>
+bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command>
+bash$ <command>patch -p1 &lt; bugzilla-2.22-to-2.22.1.diff</command>
+patching file checksetup.pl
+patching file collectstats.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="upgrade-completion">
+      <title>Completing Your Upgrade</title>
+
+      <para>
+        Now that you have the new Bugzilla code, there are a few final
+        steps to complete your upgrade.
+      </para>
+      
+      <orderedlist>
+        <listitem>
+          <para>
+            If your new Bugzilla installation is in a different
+            directory or on a different machine than your old Bugzilla
+            installation, make sure that you have copied the
+            <filename>data</filename> directory and the
+            <filename>localconfig</filename> file from your old Bugzilla
+            installation. (If you followed the tarball instructions
+            above, this has already happened.)
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            If this is a major update, check that the configuration
+            (<xref linkend="configuration"/>) for your new Bugzilla is
+            up-to-date. Sometimes the configuration requirements change
+            between major versions.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            If you didn't do it as part of the above configuration step,
+            now you need to run <command>checksetup.pl</command>, which
+            will do everything required to convert your existing database
+            and settings for the new version:
+          </para>
+
+          <programlisting>
+bash$ <command>cd /var/www/html/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>
+          
+          <caution>
+            <para>
+              If this is a major upgrade (say, 2.22 to 3.0 or similar),
+              running <command>checksetup.pl</command> on a large
+              installation (75,000 or more bugs) can take a long time,
+              possibly several hours.
+            </para>
+          </caution>
+        </listitem>
+
+        <listitem>
+          <para>
+            Clear any HTML or text that you put into the shutdownhtml
+            parameter, to re-activate Bugzilla.
+          </para> 
+        </listitem>
+
+        <listitem>
+          <para>
+            View the Sanity Check (<xref linkend="sanitycheck"/>) page in your
+            upgraded Bugzilla.
+          </para>
+          <para>
+            It is recommended that, if possible, you fix any problems
+            you see, immediately. Failure to do this may mean that Bugzilla
+            will not work correctly. Be aware that if the sanity check page
+            contains more errors after an upgrade, it doesn't necessarily
+            mean there are more errors in your database than there were
+            before, as additional tests are added to the sanity check over
+            time, and it is possible that those errors weren't being
+            checked for in the old version.
+          </para>
+        </listitem>
+      </orderedlist>
+
+    </section>
+    
+    <section id="upgrade-notifications">
+      <title>Automatic Notifications of New Releases</title>
+
+      <para>
+        Bugzilla 3.0 introduced the ability to automatically notify
+        administrators when new releases are available, based on the
+        <literal>upgrade_notification</literal> parameter, see
+        <xref linkend="parameters"/>. Administrators will see these
+        notifications when they access the <filename>index.cgi</filename>
+        page, i.e. generally when logging in. Bugzilla will check once per
+        day for new releases, unless the parameter is set to
+        <quote>disabled</quote>. If you are behind a proxy, you may have to set
+        the <literal>proxy_url</literal> parameter accordingly. If the proxy
+        requires authentication, use the
+        <literal>http://user:pass@proxy_url/</literal> syntax.
+      </para>
+    </section>
+  </section>
+
 </chapter>
 
 <!-- Keep this comment at the end of the file