Upgrading with a Tarball
************************

If you are unable (or unwilling) to use Git, another option is to
obtain a tarball of the latest version from our website and upgrade
your Bugzilla installation using that.

Without a source code management system to help you, the process may
be trickier.


Before You Upgrade
==================

Before you start your upgrade, there are a few important steps to
take:

1. Read the Release Notes of the version you're upgrading to and
   all intermediate versions, particularly the "Notes for Upgraders"
   sections, if present. They may make you aware of additional
   considerations.

2. Run the Sanity Check on your installation. Attempt to fix all
   warnings that the page produces before you start, or it's possible
   that you may experience problems during your upgrade.

3. Work out how to back up your Bugzilla entirely, and how to
   restore from a backup if need be.


Customized Bugzilla?
--------------------

If you have modified the code or templates of your Bugzilla, then
upgrading requires a bit more thought and effort than the simple
process below. See Choosing a Customization Method for a discussion of
the various methods of code customization that may have been used.

The larger the jump you are trying to make, the more difficult it is
going to be to upgrade if you have made local code customizations.
Upgrading from 4.2 to 4.2.1 should be fairly painless even if you are
heavily customized, but going from 2.18 to 4.2 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.

If you have made customizations, you should do the upgrade on a test
system with the same configuration and make sure all your
customizations still work. If not, port and test them so you have them
ready to reapply once you do the upgrade for real.

As you are using a tarball and not an SCM, it's not at all easy to see
if you've made local code customizations. You may have to use
institutional knowledge, or download a fresh copy of your *current*
version of Bugzilla and compare the two directories. If you find that
you have, you'll need to turn them into a patch file, perhaps by
diffing the two directories, and then reapply that patch file later.
If you are customizing Bugzilla locally, please consider rebasing your
install on top of git.


Getting The New Bugzilla
========================

Download a copy of the latest version of Bugzilla from the Download
Page into a separate directory (which we will call "bugzilla-new")
alongside your existing Bugzilla installation (which we will assume is
in a directory called "bugzilla").


Copy Across Data and Modules
============================

Copy the contents of the following directories from your current
installation of Bugzilla into the corresponding directory in
"bugzilla-new/":

   lib/
   data/
   template/en/custom (may or may not exist)

You also need to copy any extensions you have written or installed,
which are in the "extensions/" directory. Bugzilla ships with some
extensions, so again if you want to know if any of the installed
extensions are yours, you may have to compare with a clean copy of
your current version. You can disregard any which have a "disabled"
file - those are not enabled.

Lastly, copy the following file from your current installation of
Bugzilla into the corresponding place in "bugzilla-new/":

   localconfig

This file contains your database password and access details.


Swap The New Version In
=======================

Now we swap the directories over. From the directory containing the
"bugzilla" and "bugzilla-new" directories, run:

**mv bugzilla bugzilla-old**

**mv bugzilla-new bugzilla**

**cd bugzilla**


Upgrading the Database
======================

Run "checksetup.pl". This will do everything required to convert your
existing database and settings to the new version.

**cd $BUGZILLA_HOME**

**./checksetup.pl**

   Warning: For some upgrades, running "checksetup.pl" on a large
     installation (75,000 or more bugs) can take a long time, possibly
     several hours, if e.g. indexes need to be rebuilt. If this length
     of downtime would be a problem for you, you can determine timings
     for your particular situation by doing a test upgrade on a
     development server with the production data.

"checksetup.pl" may also tell you that you need some additional Perl
modules, or newer versions of the ones you have. You will need to
install these, either system-wide or using the "install-module.pl"
script that "checksetup.pl" recommends.


Finishing The Upgrade
=====================

1. Reactivate Bugzilla by clear the text that you put into the
   shutdownhtml parameter.

2. Run another Sanity Check on your upgraded Bugzilla. It is
   recommended that you fix any problems you see immediately. Failure
   to do this may mean that Bugzilla may not work entirely correctly.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.