3.9.1. 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.

3.9.1.1. 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.

3.9.1.2. 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.

3.9.1.3. 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 bugzilla-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.

3.9.1.4. 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.

3.9.1.5. 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.