Upgrading from Bugzilla 4.0 or older using CVS to Bugzilla 4.2 or newer using Bzr
There has been some complains these last few days on IRC and in the support mailing-list/newsgroup that admins couldn’t upgrade their Bugzilla installation to 4.2 due to the lack of a CVS mirror for this branch. As announced 3 years ago in the developers mailing-list and on b.m.o., and 1.5 years ago on the bugzilla.org website, the Bugzilla team switched from the old CVS to the more modern Bazaar (or bzr for short) VCS. If you use our tarballs to download Bugzilla, then you don’t really care about this change, and the process to upgrade won’t change for you. If you use CVS and you wonder how to upgrade using Bzr, here is how you can do it:
- For now, there is no need to shut down Bugzilla. We will do this when we start the upgrade process itself. If you made changes to the Bugzilla code itself (instead of using its extension system), you will have to port these changes to the new version, else they will be lost. If you made no changes, or all changes are contained into extensions, you can jump to step 2 directly. To generate a patch with all the changes you made, go into your bugzilla/ directory and run this command:
cvs diff -puN > patch.diff
The file patch.diff will contain all the changes you made to your current installation.
- Let’s download the new version of Bugzilla into a separate directory, to not mess with the current installation. Now you will need bzr. All Linux installations have it; have a look at your package manager. For instance, Fedora 16 has bzr-2.4.2-1.fc16.i686.rpm. On Windows, you can download it from canonical.com. The standalone application is recommended; for instance: bzr-2.4.2-1-setup.exe. Once bzr is installed, run this command to download Bugzilla 4.2:
bzr co bzr://bzr.mozilla.org/bugzilla/4.2 bugzilla42
Here, bzr co means "checkout", i.e. it’s the first download of 4.2 with bzr. Then you have the URL to our Bugzilla 4.2 repository, and finally you have the name of the local directory into which to dowload the source code. If you don’t like the name bugzilla42, feel free to choose another one. :)
- Now go into the new bugzilla42/ directory and run the following command:
The –check-modules part is important for two reasons. First of all, we didn’t copy the configuration files from the old bugzilla/ directory into the new one. The advantage to do so is to prevent Bugzilla 4.2 from finding where your DB is located and start interacting with it. Remember that we did no backup of your DB yet! :) And the second reason is that we first want to make sure that we have all the required Perl modules installed. Between major releases of Bugzilla, the requirements may change, either by requiring new Perl modules, or by requiring a newer version of an existing Perl module. If you have missing or too old Perl modules, you will have to install or upgrade them, ideally using your package manager. On Windows, ActivePerl 5.12 and newer have all the required modules available, so that’s not a problem. On Linux, only old distros may have some missing or too old Perl modules. If this happens, you can use the install-module.pl script which is in the same directory as checksetup.pl to install them. The commands you need to execute are given by checksetup.pl –check-modules itself. So open your eyes. :) Note that you don’t need to install all the optional Perl modules. The reason is that they are…. optional! Only install those which are relevant to your installation.
- If you made changes to your current Bugzilla installation, then you have to apply patch.diff you created at step 1 to your new installation. If you made no changes, you can jump to step 5 directly. If you are on Windows and you don’t have patch.exe, you can download it from sourceforge.net. Once downloaded, you must copy patch.exe into the Windows directory. At this point, it’s very likely that your changes will conflict with the new code, unless you are lucky or your changes are very minor. So we first check if there are conflicts or not. To do that, copy patch.diff into your new bugzilla42/ directory, and run this command from here:
patch -p0 –dry-run < patch.diff
–dry-run means that we made no changes to files; it was only a test. If all you get are messages such as "Hunk #1 succeeded at 79 (offset -26 lines)" or "Hunk #1 succeeded at 31 with fuzz 1 (offset 2 lines)", then you are fine. But if you get messages such as "Hunk #1 FAILED at 27" and "1 out of 2 hunks FAILED", then you are in trouble. And don’t blame the Bugzilla team and Bzr, you would get the same errors with CVS! If the conflicts are minor, you can easily fix them manually, else you probably will have to rewrite your changes directly into the new code. If you have no conflicts, you can drop the –dry-run argument and apply your patch for real:
patch -p0 < patch.diff
- Now we are ready to start the upgrade process itself. The first thing to do is to shut down Bugzilla, because the DB must not be accessed by anyone but you during the upgrade process. To do that, go to Administration > Parameters > General > shutdownhtml, and add some explanation of what’s happening. For instance: "This installation is being upgraded to Bugzilla 4.2. The downtime should last approximatively 2 hours.", and click the "Save Changes" button at the bottom of the page. I recommend that you don’t leave this page during the upgrade process, because all other pages will be deactivated besides this one. At this point, when someone tries to access Bugzilla during the downtime, this message will be displayed to them instead, so that you can upgrade your installation without having some users still interacting with it.
- Then, and this rule applies all the time when upgrading to a newer major version: do a backup of your database! The reason is that once you start the upgrade process (i.e. when you run checksetup.pl), there is NO way to downgrade later. So if the upgrade process fails for some reason (most of the time because someone hacked the source code or the DB schema) and you made no backup, you are lost. To backup your DB with MySQL, run the following command, where you must replace $db_user and $db_name by their value set in your bugzilla/localconfig file (by default: $db_user = bugs; $db_name = bugs):
mysqldump -u $db_user -p $db_name > db_backup.sql
- Copy the whole data/ directory and the localconfig file from your old bugzilla/ directory into the new bugzilla42/ one. data/ contains your parameters in the data/params file, your local attachments in data/attachments/ as well as data for Old Charts in data/mining/. And localconfig contains all the parameters to access the DB, including its password, the name of the web server group, and some other useful configuration information. If you wrote some extensions, now is a good time to also copy them into bugzilla42/extensions/. Only copy the ones you wrote, not the existing ones such as BmpConvert, Example, OldBugMove or Voting, which are maintained by the Bugzilla team.
- It’s now time to upgrade your DB to work with Bugzilla 4.2. From the bugzilla42/ directory, run ./checksetup.pl with no arguments (so no –check-modules anymore) and let it run the upgrade process for you. As you copied the configuration and parameters files, it knows where the DB is, its password, and everything else it should know about. Depending on the size of your DB and from which version you are upgrading, this may take from a few minutes to several hours. But typically, it’s of the order of a few tens of minutes for a DB with several tens of thousands of bugs. If everything went well, the last message displayed by checksetup.pl must be "checksetup.pl complete" displayed in green. Else this means something went wrong at some point. If half of the messages are in red, then there is no doubt about this. ;)
- The upgrade is now complete, and it’s time to let your users admire this new version. Replace your old bugzilla/ directory by the new one, and re-enable Bugzilla. To do that, you must remove the text you wrote for the shutdownhtml parameter. As we replaced the old directory by the new one, the URL pointing to Bugzilla remains unchanged. You now have a fully-working bzr-based Bugzilla installation. :)