From ea961b9d8653947efc46e28e4c9c350f7871a748 Mon Sep 17 00:00:00 2001 From: "mkanat%bugzilla.org" <> Date: Thu, 7 Aug 2008 05:24:32 +0000 Subject: Bug 371020: Overhaul the "Upgrading to a New Release" section Patch By Max Kanat-Alexander r=LpSolit --- docs/en/xml/administration.xml | 344 --------------------------------- docs/en/xml/installation.xml | 420 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 419 insertions(+), 345 deletions(-) (limited to 'docs') diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index 9924a742e..2ed037609 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -3045,7 +3045,6 @@ ReadOnly: ENTRY, NA/NA, CANEDIT -
@@ -3086,349 +3085,6 @@ ReadOnly: ENTRY, NA/NA, CANEDIT
-
- Upgrading to New Releases - - - Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors: - - - - - - If the new version is a revision or a new point release - - - - - How many local changes (if any) have been made - - - - -
- Version Definitions - - - Bugzilla displays the version you are using at the top of the home - page index.cgi. It looks something like - '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is - the Major Version. This does not change very often; - Bugzilla was 1.x.x when it was first created, and went to 2.x.x - when it was re-written in perl in Sept 1998. The major version - 3.x.x, released in early 2007, is pretty far from what the 2.x.x - series looked like, both about its UI and its code. - - - - The second number in the version is called the 'minor number', and - a release that changes the minor number is called a 'point release'. - An even number in this position (2.18, 2.20, 2.22, 3.0, 3.2, etc.) - represents a stable version, while an odd number (2.19, 2.21, 2.23, etc.) - represents a development version. In the past, stable point releases - were feature-based, coming when certain enhancements had been - completed, or the Bugzilla development team felt that enough - progress had been made overall. As of version 2.18, however, - Bugzilla has moved to a time-based release schedule; current plans - are to create a stable point release every 6 months or so after - 2.18 is deployed. - - - - The third number in the Bugzilla version represents a bugfix version. - Bugfix Revisions are released only to address security vulnerabilities - and, for a limited period, bug fixes. Once enough of these - bugfixes have accumulated (or a new security vulnerability is - identified and closed), a bugfix release is made. As an - example, 2.20.3 was a bugfix release, and improved on 2.20.2. - - - - - When reading version numbers, everything separated by a point ('.') - should be read as a single number. It is not - the same as decimal. 2.22 is newer than 2.8 because minor version - 22 is greater than minor version 8. The now unsupported release 2.16.11 - was newer than 2.16.9 (because bugfix 11 is greater than bugfix 9. This is - confusing to some people who aren't used to dealing with software. - - -
- -
- Upgrading - Notifications - - - Bugzilla 3.0 introduces the ability to automatically notify - administrators when new releases are available, based on the - upgrade_notification parameter, see - . Administrators will see these - notifications when they access the index.cgi - page, i.e. generally when logging in. Bugzilla will check once per - day for new releases, unless the parameter is set to - disabled. If you are behind a proxy, you may have to set - the proxy_url parameter accordingly. If the proxy - requires authentication, use the - http://user:pass@proxy_url/ syntax. - -
- -
- Upgrading - Methods and Procedure - - There are three different ways to upgrade your installation. - - - - - - Using CVS () - - - - - Downloading a new tarball () - - - - - Applying the relevant patches () - - - - - - Each of these options has its own pros and cons; the one that's - right for you depends on how long it has been since you last - installed, the degree to which you have customized your installation, - and/or your network configuration. (Some discussion of the various - methods of updating compared with degree and methods of local - customization can be found in .) - - - - The larger the jump you are trying to make, the more difficult it - is going to be to upgrade if you have made local customizations. - Upgrading from 2.22 to 2.22.1 should be fairly painless even if - you are heavily customized, but going from 2.18 to 3.0 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. - - - - - Upgrading is a one-way process. You should backup your database - and current Bugzilla directory before attempting the upgrade. If - you wish to revert to the old Bugzilla version for any reason, you - will have to restore from these backups. - - - - - The examples in the following sections are written as though the - user were updating to version 2.22.1, but the procedures are the - same regardless of whether one is updating to a new point release - or simply trying to obtain a new bugfix release. Also, in the - examples the user's Bugzilla installation is found at - /var/www/html/bugzilla. If that is not the - same as the location of your Bugzilla installation, simply - substitute the proper paths where appropriate. - - -
- Upgrading using CVS - - - Every release of Bugzilla, whether it is a point release or a bugfix, - is tagged in CVS. Also, every tarball that has been distributed since - version 2.12 has been created in such a way that it can be used with - CVS once it is unpacked. Doing so, however, requires that you are able - to access cvs-mirror.mozilla.org on port 2401, which may not be an - option or a possibility for some users, especially those behind a - highly restrictive firewall. - - - - - If you can, updating using CVS is probably the most painless - method, especially if you have a lot of local changes. - - - - - The following shows the sequence of commands needed to update a - Bugzilla installation via CVS, and a typical series of results. - - - -bash$ cd /var/www/html/bugzilla -bash$ cvs login -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: ('anonymous', or just leave it blank) -bash$ cvs -q update -r BUGZILLA-2_22_1 -dP -P checksetup.pl -P collectstats.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl -(etc.) - - - - - If a line in the output from cvs update begins - with a C, then that represents a - file with local changes that CVS was unable to properly merge. You - need to resolve these conflicts manually before Bugzilla (or at - least the portion using that file) will be usable. - - -
- -
- Upgrading using the tarball - - - If you are unable (or unwilling) to use CVS, another option that's - always available is to obtain the latest tarball from the Download Page and - create a new Bugzilla installation from that. - - - - This sequence of commands shows how to get the tarball from the - command-line; it is also possible to download it from the site - directly in a web browser. If you go that route, save the file - to the /var/www/html - directory (or its equivalent, if you use something else) and - omit the first three lines of the example. - - - -bash$ cd /var/www/html -bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz -(Output omitted) -bash$ tar xzvf bugzilla-2.22.1.tar.gz -bugzilla-2.22.1/ -bugzilla-2.22.1/.cvsignore -(Output truncated) -bash$ cd bugzilla-2.22.1 -bash$ cp ../bugzilla/localconfig* . -bash$ cp -r ../bugzilla/data . -bash$ cd .. -bash$ mv bugzilla bugzilla.old -bash$ mv bugzilla-2.22.1 bugzilla - - - - - The cp commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. - - - - - This upgrade method will give you a clean install of Bugzilla with the - same version as the tarball. That's fine if you don't have any local - customizations that you want to maintain, but if you do then you will - need to reapply them by hand to the appropriate files. - - - - It's worth noting that since 2.12, the Bugzilla tarballs come - CVS-ready, so if you decide at a later date that you'd rather use - CVS as an upgrade method, your code will already be set up for it. - -
- -
- Upgrading using patches - - - If you are doing a bugfix upgrade -- that is, one where only the - last number of the revision changes, such as from 2.22 to 2.22.1 - -- then you have the option of obtaining and applying a patch file - from the Download Page. - This file is made available by the Bugzilla - Development Team, and is a collection of all the bug fixes - and security patches that have been made since the last bugfix - release. If you are planning to upgrade via patches, it is safer - to grab this developer-made patch file than to read the patch - notes and apply all (or even just some of) the patches oneself, - as sometimes patches on bugs get changed before they get checked in. - - - - As above, this example starts with obtaining the file via the - command line. If you have already downloaded it, you can omit the - first two commands. - - - -bash$ cd /var/www/html/bugzilla -bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz -(Output omitted) -bash$ gunzip bugzilla-2.22-to-2.22.1.diff.gz -bash$ patch -p1 < bugzilla-2.22-to-2.22.1.diff -patching file checksetup.pl -patching file collectstats.pl -(etc.) - - - - - Be aware that upgrading from a patch file does not change the - entries in your CVS directory. - This could make it more difficult to upgrade using CVS - () in the future. - - - -
-
- -
- Completing Your Upgrade - - - Regardless of which upgrade method you choose, you will need to - run ./checksetup.pl before your Bugzilla - upgrade will be complete. - - - -bash$ cd bugzilla -bash$ ./checksetup.pl - - - - - The period at the beginning of the command - ./checksetup.pl is important and can not - be omitted. - - - - - If you have done a lot of local modifications, it wouldn't hurt - to run the Bugzilla Testing suite. This is not a required step, - but it isn't going to hurt anything, and might help point out - some areas that could be improved. (More information on the - test suite can be had by following this link to the appropriate - section in the Developers' - Guide.) - - -
-
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 78867e725..341dd42f6 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,5 +1,5 @@ - + Installing Bugzilla @@ -2017,6 +2017,424 @@ pid-file=/home/foo/mymysql/the.pid + +
+ Upgrading to New Releases + + Upgrading to new Bugzilla releases is very simple. There is + a script included with Bugzilla that will automatically + do all of the database migration for you. + + The following sections explain how to upgrade from one + version of Bugzilla to another. Whether you are upgrading + from one bug-fix version to another (such as 3.0.1 to 3.0.2) + or from one major version to another (such as from 3.0 to 3.2), + the instructions are always the same. + + + + Any examples in the following sections are written as though the + user were updating to version 2.22.1, but the procedures are the + same no matter what version you're updating to. Also, in the + examples, the user's Bugzilla installation is found at + /var/www/html/bugzilla. If that is not the + same as the location of your Bugzilla installation, simply + substitute the proper paths where appropriate. + + + +
+ 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, + particularly the "Notes for Upgraders" section. + + + + + + View the Sanity Check () page + on your installation before upgrading. Attempt to fix all warnings + that the page produces before you go any further, or you may + experience problems during your upgrade. + + + + + + Shut down your Bugzilla installation by putting some HTML or + text in the shutdownhtml parameter + (see ). + + + + + + Make a backup of the Bugzilla database. + THIS IS VERY IMPORTANT. If + anything goes wrong during the upgrade, your installation + can be corrupted beyond recovery. Having a backup keeps you safe. + + + + + Upgrading is a one-way process. You cannot "downgrade" an + upgraded Bugzilla. If you wish to revert to the old Bugzilla + version for any reason, you will have to restore your database + from this backup. + + + + Here are some sample commands you could use to backup + your database, depending on what database system you're + using. You may have to modify these commands for your + particular setup. + + + + MySQL: + + + mysqldump --opt -u bugs -p bugs > bugs.sql + + + + + + PostgreSQL: + + + pg_dump --no-privileges --no-owner -h localhost -U bugs + > bugs.sql + + + + + + +
+ +
+ Getting The New Bugzilla + + There are three ways to get the new version of Bugzilla. + We'll list them here briefly and then explain them + more later. + + + + CVS () + + + If have cvs installed on your machine + and you have Internet access, this is the easiest way to + upgrade, particularly if you have made modifications + to the code or templates of Bugzilla. + + + + + + Download the tarball () + + + This is a very simple way to upgrade, and good if you + haven't made many (or any) modifications to the code or + templates of your Bugzilla. + + + + + + Patches () + + + If you have made modifications to your Bugzilla, and + you don't have Internet access or you don't want to use + cvs, then this is the best way to upgrade. + + + + You can only do minor upgrades (such as 3.0 to 3.0.1 or + 3.0.1 to 3.0.2) with patches. + + + + + +
+ If you have modified your Bugzilla + + + If you have modified the code or templates of your Bugzilla, + then upgrading requires a bit more thought and effort. + A discussion of the various methods of updating compared with + degree and methods of local customization can be found in + . + + + + The larger the jump you are trying to make, the more difficult it + is going to be to upgrade if you have made local customizations. + Upgrading from 3.0 to 3.0.1 should be fairly painless even if + you are heavily customized, but going from 2.18 to 3.0 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. + +
+ +
+ Upgrading using CVS + + + This requires that you have cvs installed (most Unix machines do), + and requires that you are able to access cvs-mirror.mozilla.org + on port 2401, which may not be an option if you are behind a + highly restrictive firewall or don't have Internet access. + + + + The following shows the sequence of commands needed to update a + Bugzilla installation via CVS, and a typical series of results. + + + +bash$ cd /var/www/html/bugzilla +bash$ cvs login +Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot +CVS password: ('anonymous', or just leave it blank) +bash$ cvs -q update -r BUGZILLA-2_22_1 -dP +P checksetup.pl +P collectstats.pl +P docs/rel_notes.txt +P template/en/default/list/quips.html.tmpl +(etc.) + + + + + If a line in the output from cvs update begins + with a C, then that represents a + file with local changes that CVS was unable to properly merge. You + need to resolve these conflicts manually before Bugzilla (or at + least the portion using that file) will be usable. + + +
+ +
+ Upgrading using the tarball + + + If you are unable (or unwilling) to use CVS, another option that's + always available is to obtain the latest tarball from the Download Page and + create a new Bugzilla installation from that. + + + + This sequence of commands shows how to get the tarball from the + command-line; it is also possible to download it from the site + directly in a web browser. If you go that route, save the file + to the /var/www/html + directory (or its equivalent, if you use something else) and + omit the first three lines of the example. + + + +bash$ cd /var/www/html +bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz +(Output omitted) +bash$ tar xzvf bugzilla-2.22.1.tar.gz +bugzilla-2.22.1/ +bugzilla-2.22.1/.cvsignore +(Output truncated) +bash$ cd bugzilla-2.22.1 +bash$ cp ../bugzilla/localconfig* . +bash$ cp -r ../bugzilla/data . +bash$ cd .. +bash$ mv bugzilla bugzilla.old +bash$ mv bugzilla-2.22.1 bugzilla + + + + + The cp commands both end with periods which + is a very important detail--it means that the destination + directory is the current working directory. + + + + + This upgrade method will give you a clean install of Bugzilla. + That's fine if you don't have any local customizations that you + want to maintain. If you do have customizations, then you will + need to reapply them by hand to the appropriate files. + +
+ +
+ Upgrading using patches + + + A patch is a collection of all the bug fixes that have been made + since the last bug-fix release. + + + + If you are doing a bug-fix upgrade—that is, one where only the + last number of the revision changes, such as from 2.22 to + 2.22.1—then you have the option of obtaining and applying a + patch file from the Download Page. + + + + As above, this example starts with obtaining the file via the + command line. If you have already downloaded it, you can omit the + first two commands. + + + +bash$ cd /var/www/html/bugzilla +bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz +(Output omitted) +bash$ gunzip bugzilla-2.22-to-2.22.1.diff.gz +bash$ patch -p1 < bugzilla-2.22-to-2.22.1.diff +patching file checksetup.pl +patching file collectstats.pl +(etc.) + + + + + Be aware that upgrading from a patch file does not change the + entries in your CVS directory. + This could make it more difficult to upgrade using CVS + () in the future. + + + +
+
+ +
+ Completing Your Upgrade + + + Now that you have the new Bugzilla code, there are a few final + steps to complete your upgrade. + + + + + + If your new Bugzilla installation is in a different + directory or on a different machine than your old Bugzilla + installation, make sure that you have copied the + data directory and the + localconfig file from your old Bugzilla + installation. (If you followed the tarball instructions + above, this has already happened.) + + + + + + If this is a major update, check that the configuration + () for your new Bugzilla is + up-to-date. Sometimes the configuration requirements change + between major versions. + + + + + + If you didn't do it as part of the above configuration step, + now you need to run checksetup.pl, which + will do everything required to convert your existing database + and settings for the new version: + + + +bash$ cd /var/www/html/bugzilla +bash$ ./checksetup.pl + + + + + The period at the beginning of the command + ./checksetup.pl is important and can not + be omitted. + + + + + + If this is a major upgrade (say, 2.22 to 3.0 or similar), + running checksetup.pl on a large + installation (75,000 or more bugs) can take a long time, + possibly several hours. + + + + + + + Clear any HTML or text that you put into the shutdownhtml + parameter, to re-activate Bugzilla. + + + + + + View the Sanity Check () page in your + upgraded Bugzilla. + + + It is recommended that, if possible, you fix any problems + you see, immediately. Failure to do this may mean that Bugzilla + will not work correctly. Be aware that if the sanity check page + contains more errors after an upgrade, it doesn't necessarily + mean there are more errors in your database than there were + before, as additional tests are added to the sanity check over + time, and it is possible that those errors weren't being + checked for in the old version. + + + + +
+ +
+ Automatic Notifications of New Releases + + + Bugzilla 3.0 introduced the ability to automatically notify + administrators when new releases are available, based on the + upgrade_notification parameter, see + . Administrators will see these + notifications when they access the index.cgi + page, i.e. generally when logging in. Bugzilla will check once per + day for new releases, unless the parameter is set to + disabled. If you are behind a proxy, you may have to set + the proxy_url parameter accordingly. If the proxy + requires authentication, use the + http://user:pass@proxy_url/ syntax. + +
+
+