summaryrefslogtreecommitdiffstats
path: root/docs/en/xml
diff options
context:
space:
mode:
authormkanat%bugzilla.org <>2008-08-07 07:24:32 +0200
committermkanat%bugzilla.org <>2008-08-07 07:24:32 +0200
commitea961b9d8653947efc46e28e4c9c350f7871a748 (patch)
treeba2d5e6ffda2f6261f6c79849f0f7469a7959b78 /docs/en/xml
parent18d0e31a946e8e3d29eac2acda177d6c0af8a433 (diff)
downloadbugzilla-ea961b9d8653947efc46e28e4c9c350f7871a748.tar.gz
bugzilla-ea961b9d8653947efc46e28e4c9c350f7871a748.tar.xz
Bug 371020: Overhaul the "Upgrading to a New Release" section
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit
Diffstat (limited to 'docs/en/xml')
-rw-r--r--docs/en/xml/administration.xml344
-rw-r--r--docs/en/xml/installation.xml420
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