3.11.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.
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.
3.11.1.1. Before You Upgrade¶
Before you start your upgrade, there are a few important steps to take:
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.
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.
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.11.1.2. Starting the Upgrade¶
When you are ready to go:
Shut down your Bugzilla installation by putting some explanatory text in the shutdownhtml parameter.
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.11.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 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.
3.11.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.plon 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.11.1.5. Finishing The Upgrade¶
Reactivate Bugzilla by clear the text that you put into the shutdownhtml parameter.
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.
