From 8ccdccd2563ce1bd573a8b40afd0530a7d3d3bc9 Mon Sep 17 00:00:00 2001 From: "travis%sedsystems.ca" <> Date: Sat, 12 Feb 2005 06:24:54 +0000 Subject: Bug 256654 : Improve/Add to the upgrade instructions Patch by Shane H. W. Travis r=colin.ogilvie --- docs/xml/administration.xml | 385 +++++++++++++++++++++++++++++--------------- 1 file changed, 257 insertions(+), 128 deletions(-) (limited to 'docs') diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml index 3b84f40c8..772e4abf0 100644 --- a/docs/xml/administration.xml +++ b/docs/xml/administration.xml @@ -1436,204 +1436,333 @@ Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
Upgrading to New Releases - - 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. - - - - 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. + + 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 + + If the new version is a revision or a new point release + - How many, if any, local changes have been made + + How many local changes (if any) have been made + - There are also three different methods to upgrade your installation. - +
+ Version Definitions - - - Using CVS () - - - Downloading a new tarball () - - - Applying the relevant patches () - - + + Bugzilla displays the version you are using at the top of most + pages you load. It will look something like '2.16.7' or '2.18rc3' + or '2.19.1+'. The first number in this series is the Major Version. + This does not change very often (that is to say, almost never); + 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. If/When the major version + is changed to 3.x.x, it will signify a significant structural change + and will be accompanied by much fanfare and many instructions on + how to upgrade, including a revision to this page. :) + - Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - + + 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.14, 2.16, 2.18, 2.20, etc.) + represents a stable version, while an odd number (2.17, 2.19, 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. + - Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.6 was released, it was a revision to 2.16.5. - + + The third number in the Bugzilla version represents a bugfix version. + Bugfix Revisions are normally released only to address security + vulnerabilities; in the future, it is likely that the Bugzilla + development team will back-port bugfixes in a new point release to + the old point release for a limited period. Once enough of these + bugfixes have accumulated (or a new security vulnerability is + identified and closed), a bugfix release will be made. As an + example, 2.16.6 was a bugfix release, and improved on 2.16.5. + - Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.18.0 is a newer point - release than 2.16.5. - + + + When reading version numbers, everything separated by a point ('.') + should be read as a single number. It is not + the same as decimal. 2.14 is newer than 2.8 because minor version + 14 is greater than minor version 8. 2.24.11 would be newer than + 2.24.9 (because bugfix 11 is greater than bugfix 9. This is + confusing to some people who aren't used to dealing with software. + + +
- The examples in this section are written as if you were updating - to version 2.18.1. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - +
+ Upgrading - Methods and Procedure + + There are three different ways to upgrade your installation. + - These examples also assume that your Bugzilla installation is at - /var/www/html/bugzilla. If that is not the case, - simply substitute the proper paths where appropriate. - + + + + 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.18 to 2.18.1 should be fairly painless even if + you are heavily customized, but going from 2.14 to 2.18 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.18.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 revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. + + 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 do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. + + 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 +CVS password: ('anonymous', or just leave it blank) bash$ cvs -q update -r BUGZILLA-2_18_1 -dP P checksetup.pl P collectstats.pl P globals.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 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. + + 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. +
- - You also need to run ./checksetup.pl - before your Bugzilla upgrade will be complete. - - - - +
+ Upgrading using the tarball - - 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. + - If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. - + + 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 ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz -Output omitted +(Output omitted) bash$ tar xzvf bugzilla-2.18.1.tar.gz bugzilla-2.18.1/ bugzilla-2.18.1/.cvsignore bugzilla-2.18.1/1x1.gif -Output truncated +(Output truncated) bash$ cd bugzilla-2.18.1 bash$ cp ../bugzilla/localconfig* . bash$ cp -r ../bugzilla/data . bash$ cd .. bash$ mv bugzilla bugzilla.old bash$ mv bugzilla-2.18.1 bugzilla -bash$ cd bugzilla -bash$ ./checksetup.pl -Output omitted - + - - 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. Also, the period at the - beginning of the ./checksetup.pl is important and - can not be omitted. + + 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. - - You will now have to reapply any changes you have made to your - local installation manually. - - - - - - - Upgrading using patches - - The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in. - It is also theoretically possible to - scour the fixed bug list and pick and choose which patches to apply - from a point release, but this is not recommended either as what you'll - end up with is a hodge podge Bugzilla that isn't really any version. - This would also make it more difficult to upgrade in the future. - + + 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.16.6 to 2.16.7 + -- 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 ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz -Output omitted +(Output omitted) bash$ gunzip bugzilla-2.18.0-to-2.18.1.diff.gz bash$ patch -p1 < bugzilla-2.18.0-to-2.18.1.diff patching file checksetup.pl patching file collectstats.pl patching file globals.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 do this, beware that this doesn't change the entires in - your CVS directory so it may make - updates using CVS () more difficult in the - future. - - + 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.) - +
-- cgit v1.2.3-24-g4f1b