Upgrading with Git
******************
Upgrading to new Bugzilla releases is very simple, and you can upgrade
from any version to any later version in one go - there is no need for
intermediate steps. There is a script named "checksetup.pl" included
with Bugzilla that will automatically do all of the database migration
for you.
Bugzilla is now hosted on Github, but we used to be hosted on
git.mozilla.org. If you got the code from git.mozilla.org, you need to
point your checkout at Github instead. To find out, run:
**git remote -v**
If you see "git.mozilla.org" anywhere in the output, then run:
**git remote set-url origin https://github.com/bugzilla/bugzilla**
This change will only ever need to be done once.
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.
You can see if you have local code customizations using:
**git diff**
If that comes up empty, then run:
**git log | head**
and see if the last commit looks like one made by the Bugzilla team,
or by you. If it looks like it was made by us, then you have made no
local code customizations.
Starting the Upgrade
====================
When you are ready to go:
1. Shut down your Bugzilla installation by putting some explanatory
text in the shutdownhtml parameter.
2. Make all necessary backups. *THIS IS VERY IMPORTANT*. If
anything goes wrong during the upgrade, having a backup allows you
to roll back to a known good state.
Getting The New Bugzilla
========================
In the commands below, "$BUGZILLA_HOME" represents the directory in
which Bugzilla is installed. Assuming you followed the installation
instructions and your Bugzilla is a checkout of a stable branch, you
can get the latest point release of your current version by simply
doing:
**cd $BUGZILLA_HOME**
**git pull**
If you want to upgrade to a newer release of Bugzilla, then you will
additionally need to do:
**git checkout release-X.X-stable**
where "X.X" is the 2-digit version number of the stable version you
want to upgrade to (e.g. "4.4").
Note: Do not attempt to downgrade Bugzilla this way - it won't work.
If you have local code customizations, git will attempt to merge them.
If it fails, then you should implement the plan you came up with when
you detected these customizations in the step above, before you
started the upgrade.
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.
