                How to upgrade Bugzero to a new version or edition

For the impatient:

The Upgrade includes two things: 

  1) The application files: copy existing configuration files, jdbc driver etc. 
  2) the database schema: update database schema (checkdb.sh or checkdb.bat)

The script upgrade.sh (or upgrade.bat) does both. That is, it copies over your
current configuration files, jdbc driver, and then updates the database schema
(checkdb).

If you have customized any files, you need merge them manually.
These files may include jsp files, javascript files etc.


Now the detail instruction:

First, download and unzip bugzero.zip to a temp directory, and then find the 
version (build) number for both the old and the new bugzero (the number is
on the first line in the file bugzero/WEB-INF/release.txt).

If you are upgrading from a lower Edition to an higher Edition (i.e., Try,
Five-user, Standard, and Enterprise Edition) of the same version/build number,
the only thing you need to do is to add or replace the license.lic file.

If you are upgrading from a different version (build) number and your installed
version is 2.7 or later,  you need do the following (for earlier versions, please
read the second part of this file).

IMPORTANT: 
          If you choose to do the upgrade by coping files from the new version
          to the installed one, you must make sure all the changed files are 
          copied over. In particular, all the sql files must be copied over. In
          fact, except for a few properties files, all files should be copied
          over.

0. It is always a good idea to backup your existing installation, that includes
   the bugzero folder under the servlet container as well as the database tables.

1. Make sure you are working on this new bugzero that you have unzipped (in
   the temp directory). This new bugzero will be deployed at step 5 below 
   (by replacing the old one).

2. (Required) Run upgrade
   This script is located under directory /WEB-INF/misc/upgrade, it takes in
   an argument which is the installed running bugzero home path.

   This script does two things, one is to copy certain configuration files from
   the installed Bugzero to the new one (this is why you need specify the old
   Bugzero home), and the other one is to update the database schema (checkdb).
   Files copied are: 

      1) db.properties
      2) mail.properties
      3) system.properties
      4) email_subject
      5) email_body
      6) JDBC jar files (if applicable)

   You can manually copy these files and then run the script 'checkdb'.


3. Merge files:

   1) label.properties
   2) messages.properties

     If you've made any changes inside these files in your existing Bugzero, then
     you should include these changes to the corresponding new files (they are in 
     WEB-INF/classes/conf).   
  
   3) JSP files.
     If you've modified the jsp pages, you need merge the old ones with the new ones.

   4) Javascript files
     If you changed the date time valiadtion function, you need merge them with the
     new files.


4. (Required) Re-deploy Bugzero.
   You need move the new bugzero folder to your servlet engine's
   applications (webapps) folder. You should remove the existing one there first,
   and perhaps remove the compiled jsp code. For example, for Tomcat,
   the compiled files are located under tomcat's work/.../bugzero directory.

   You need restart your servlet engine.

   For some app servers, such as Websphere and iPlanet (SunOne),
   you need re-package bugzero into bugzero.war, un-deploy the old one, and then
   deploy the new war.


Go to IMPORTANT NOTE near the end if you are ugrading from version 2.7 or later.


Upgrading from version 2.6.x or earlier:
---------------------------------------

The group.properties file is no longer used after version 2.7. If you are upgrading
from version 2.6.x or earlier, however, you need copy the file to WEB-INF/classes/conf
before running the upgrade script. Also note that, for versions 2.4.x or earlier,
you need change the line format by moving the group name (code) to the left hand side
from the right hand side. For versions 2.5 or earlier, make all the group code
lower case. Here is an example of the correct format:
      group.admin=Administrator
      group.dev=Developer


Upgrading from version 2.2.1 or earlier:
---------------------------------------

The software was completely re-packaged since version 2.2.2. If you are upgrading
from versions earlier than that, you need do some cleanup:

1. Roll back the CLASSPATH modifications. For example, for Tomcat, edit file 
   setclasspath.bat (or .sh) and remove all the BUGZERO_HOME, JDBC_DRIVER entries
   there. They are no longer needed.
2. Remove bugzero.war in the servlet engine's applications (webapps) folder.  
3. Remove the compiled jsp code.
4. Instead of running the 'upgrade' script on step 2, you need manually merge the
   old files data/conf/*.properties and data/template/email_* to the new new ones 
   in WEB-INF/classes/
   and then run 'checkdb'.
   Note, you need need modify group.properties as described in 2.6.x above.
   Note, for db.properties, you just need set the current url/username/password to the
   new file. The same for mail.properties. You may not need to merge the label.properties.
    

Upgrading from version 1.3.2:
----------------------------

If you are upgrading from version 1.3.2 or earlier, then you need modify Bugzero's
database schema. Specifically, you have to drop the column 'project_area' in the 
'project' table; and add a column 'area_order' of type int to the 'assignment'
table. Manually fill this new column with numbers from 0 up for each 'project_id'
and 'project_area'.


Upgrading from version 1.3:
--------------------------

If you are upgrading from version 1.3 or earlier, then you need modify Bugzero's
database schema. Specifically, you have to rename all the 
$PROJECT_constraints tables to $PROJECT_filter, and rename the two columns, 
constraint_name and constraint_value to filter_name and filter_value respectively.


IMPORTANT NOTE:

0. If you got any errors from running upgrade, stop! You have to fix the problem
   before continue.

1. On Linux (Unix) OS, it is very often that an old java command is in your path.
   Make sure you are using the right java (using java -version to find out).

2. It is very often that, after upgrade, when you login, the pages are not displayed
   properly. One cause of such a problem is that the jsp files are not re-compiled.
   In such a case, you can either remove all the compiled jsp files, or use 'touch' to
   update the timestamp of these files so that they can be re-compiled.
   For example, in the case of Tomcat, the compiled jsp files are located under
   the work dir (or sub dir), remove them and restart Tomcat.


-------------------------------------------------
Bugzero homepage: http://www.websina.com/bugzero/
For questions:    mailto: dev@websina.com
