3.11.2. Migrating from Bazaar¶
The procedure to migrate to Git is as follows. The idea is to switch version control systems without changing the version of Bugzilla you are using, to minimise the risk of conflict or problems. Any upgrade can then happen as a separate step.
The old bzr.mozilla.org server has been decommissioned. This may not be a problem but, in some cases, running some of the commands below will make bzr attempt to contact the server and time out. If and only if that happens to you, you will need to switch to the new server, as follows. Enter your Bugzilla directory and run:
bzr info
and look at the Location: section of the output. If it says “light checkout root” then run:
bzr -Ossl.cert_reqs=none switch https://bzr.bugzilla.org/bugzilla/$VERSION
Alternatively, if it says “branch root” or “checkout root” then run:
bzr -Ossl.cert_reqs=none pull --remember https://bzr.bugzilla.org/bugzilla/$VERSION
Replace $VERSION with the two-digit version number of your current Bugzilla, e.g. “4.2” (see below for how to find that).
3.11.2.1. Download Code from Git¶
First, you need to find what version of Bugzilla you are using. It should be
in the top right corner of the front page but, if not, open the file
Bugzilla/Constants.pm in your Bugzilla directory and search for
BUGZILLA_VERSION.
Then, you need to download an additional copy of your current version of
Bugzilla from the git repository, and place it in a separate directory
alongside your existing Bugzilla installation (which we will assume is in a
directory called bugzilla).
To do this, you will need a copy of the git program. All Linux distributions have it; search your package manager for “git”. On Windows or Mac OS X, you can download the official build.
Once git is installed, run these commands to pull a copy of Bugzilla:
git clone https://github.com/bugzilla/bugzilla bugzilla-new
cd bugzilla-new
git checkout release-$VERSION
Replace $VERSION with the three-digit version number of your current Bugzilla, e.g. “4.2.2”. (If the the final digit would have been a 0, omit it - so use “4.4” for the first release in the 4.4 series.)
You will get a message about a ‘detached HEAD’. Don’t worry; your head is still firmly attached to your shoulders.
3.11.2.2. Save Any Local Customizations¶
Go into your original Bugzilla directory and run this command:
bzr diff > patch.diff
If you have made customizations to your Bugzilla, and you made them by
changing the Bugzilla code itself (rather than using the Extension system),
then patch.diff will have significant content. You will want to keep a copy
of those changes by keeping a copy of this file and any files referenced in it
by “Only in” lines. If the file has zero size or only insignificant content,
you haven’t made any local customizations of this sort.
3.11.2.3. Shut Down Bugzilla¶
At this point, you should shut down Bugzilla to make sure nothing changes while you make the switch. Go into the administrative interface and put an appropriate message into the shutdownhtml parameter, which is in the “General” section of the administration parameters. As the name implies, HTML is allowed.
This would be a good time to make Backups. We shouldn’t be affecting the database, but you can’t be too careful.
3.11.2.4. 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. The command bzr status extensions/ should help you work out what you added, if anything.
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. Because your two versions of Bugzilla are the same, this should all work fine.
3.11.2.5. Reapply Local Customizations¶
If your patch.diff file was zero sized, you can
jump to the next step. Otherwise, you have to apply the patch to your new
installation. If you are on Windows and you don’t have the patch
program, you can download it from
GNUWin. Once
downloaded, you must copy patch.exe into the Windows directory.
Copy patch.diff into the bugzilla-new directory and then do:
patch -p0 --dry-run < patch.diff
The patch should apply cleanly because you have exactly the same version of Bugzilla in both directories. If it does, remove the --dry-run and rerun the command to apply it for real. If it does not apply cleanly, it is likely that you have managed to get a Bugzilla version mismatch between the two directories.
3.11.2.6. Swap The New Version In¶
Now we swap the directories over, and run checksetup.pl to confirm that all
is well. From the directory containing the bugzilla and
bugzilla-new directories, run:
mv bugzilla bugzilla-old
mv bugzilla-new bugzilla
cd bugzilla
./checksetup.pl
Running checksetup.pl should not result in any changes to your database at
the end of the run. If it does, then it’s most likely that the two versions
of Bugzilla you have are not, in fact, the same.
3.11.2.7. Re-enable Bugzilla¶
Go into the administrative interface and clear the contents of the shutdownhtml parameter.
3.11.2.8. Test Bugzilla¶
Use your Bugzilla for several days to check that the switch has had no detrimental effects. Then, if necessary, follow the instructions in Upgrading with Git to upgrade to the latest version of Bugzilla.
3.11.2.9. Rolling Back¶
If something goes wrong at any stage of the switching process (e.g. your patch doesn’t apply, or checksetup doesn’t complete), you can always just switch the directories back (if you’ve got that far) and re-enable Bugzilla (if you disabled it) and then seek help. Even if you have re-enabled Bugzilla, and find a problem a little while down the road, you are still using the same version so there would be few side effects to switching the directories back a day or three later.
This documentation undoubtedly has bugs; if you find some, please file them here.
