head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	2001.08.13.23.37.01;	author kmaples;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Updated the READMEs
@
text
@This is IssueZilla, and issue tracking system based on Bugzilla.
See <http://issuezilla.tigris.org> and <http://www.mozilla.org/bugs/>.

This README-IZ superceeds the README included with Bugzilla.

CONTENTS:

1.  ORIGINAL NOTES
  1.1   Source
  1.2   Changes
  1.3   Upgrading IZ against Bugzilla (deprectated)
  1.4   Files generated by installation
2.  SUMMARY
3.  DATABASE CREATION


1.  ORIGINAL NOTES:
  
1.1 Source:  

    This is IssueZilla, based on Bugzilla 2.11 straight outta CVS on 
    9/27/2000.  It has been *heavily* modified to work within a Tigris
    framework, and will not really function without it.  Original conversion
    performed by by Niels Mayer (npm@@collab.net)
    
1.2 Changes:
    
    Replaced use of sendmail with qmail
    Instances of "bugs" changed to "issues"
    Database field "issues.severity" changed to "issue_type":
    
         NPM Removed bugs db column 'severity' and replaced it with 
         'issue-type'.  Severity seems silly and it's confusing/redundant 
         with priority 'P1'-'P5'.  Some aspects of 'severity' are handled 
         by 'issue-type', e.g.  you distinguish between an enhancement, 
         feature, task, defect, or a patch.
        
1.3 Upgrading IZ against Bugzilla (deprectated):
    
    NOTE: included for posterity; the conflicts are legion:
        
    To do an upgrade against mozilla.org, move all directories 'CVS' to 'CVS.bak',
    e.g. (in tcsh):
  
        beral-5-.../sandbox/issuezilla> foreach i (`find . -name CVS`)
        foreach? mv $i $i.bak
        foreach? end
  
    Then move all 'CVS.mozilla' to 'CVS':
  
        beral-6-.../sandbox/issuezilla> foreach i (`find . -name CVS.mozilla`)
        foreach? mv $i `dirname $i`/CVS
        foreach? end
  
    Then to see what files might have changed, since this version was last
    updated, do:
  
        beral-7-.../sandbox/issuezilla> cvs -qn update
  
    Then you can either do 'cvs update' and be very careful to watch the output
    of cvs, noting any conflicts between the issuezilla edits and mozilla.org's
    edits... (prior to doing 'cvs update' beware of files marked w/ 'C' when
    you do 'cvs -qn update', as they'll definitely create non-working
    conflict-munged code that needs to be hand edited).

1.4 Files generated by installation:  
  
    Note the following files are generated by running tigris SANDBOX 
    initialization scripts (specifically, configure.pl, which is invoked by 
    several scripts):
  
        ./localconfig.in	    ---> ./localconfig    

2.  SUMMARY:

  Support for differentiating issuezilla databases on a per-project has been 
  implemented (this superceedes a previous implementation, which differentiated 
  databases by vhost). The file which controls this behavior is a '.in' file - 
  localconfig.in - which gets configured at installation.   At install time, the 
  file defines the following values, usually taken from env.sh:
  
      DATABASE_HOST
      DATABASE_PORT
      DATABASE_USER
      DATABASE_PASSWORD
  
  The file also defines IZ_DATABASE_NAME, which may be expanded to include project
  id depending on the value of the token IZ_MULTIPLE_PROJECT_DATABASES at 
  installation, and defines SANDBOX, which is used solely by the setup script 
  (checksetup.pl) to orient itself before performing its actions.  The following 
  are the translation rules that can apply:
  
  Assume:
  
      - in env.sh, an environmental IZ_DATABASE_NAME set to 'issues' 
      - a project id X
  
  The flag - '$::use_project_id_database' - will be set (via 
  IZ_MULTIPLE_PROJECT_DATABASES) to produce one of two states:
  
      [false] use database named 'issues'
      
      [true] use database named 'issues_X'
      
  Similarly, localconfig controls the definitions of the two other directories 
  that issuezilla uses to store per-db data on the filesystem - 'shadow' and 
  'data'.  It sets these as follows, using the same flag as above:
  
      [false] 
          $::data_dir    = "$SANDBOX/data/issuezilla/data/";
          $::shadow_dir  = "$SANDBOX/data/issuezilla/shadow/";
      [true]
          $::data_dir    = "$SANDBOX/data/issuezilla/data/$::db_name";
          $::shadow_dir  = "$SANDBOX/data/issuezilla/shadow/$::db_name";
  
  So that if the flag is set to use per-project databases, various data, paramter,
  and cache files are similarly segregated by project. 
  
  NOTE:  these settings control how a the database name is derived AT RUNTIME.  
  They have essentially nothing to do with the how a database by the (presumed) 
  matching name is created.  That process is covered below in DATABASE CREATION.

3.  DATABASE CREATION:

  Database creation is handled automatically through Helm upon project creation 
  (via servlet which calls resource scripts located in $SANDBOX/helm/perl/scripts)
  Using the settings described above, the resource scripts ultimately call two 
  scripts under IZ used for database initialization and database access.
  
  The two IZ scripts - checksetup.pl and checkdbuser.pl - should be run
  exclusively by Helm; nonetheless, it is possible to run them manually from the
  command line (as with all operations on the command line you should source 
  env.sh beforehand).  An arbitrary issues database name can be initialized by:
  
  cd $SANDBOX/issuezilla
  ./checksetup.pl --database={name_of_db} --user={dbuser} --password={dbpassword}
  
  Where 'dbuser' and 'dbpassword' are for a user with sufficient mysql priviliges 
  to create databases (usually root).  The script will exit if, at a minimum, 
  'dbuser' is not supplied.  Note that this does NOT set up the DATABASE_USER 
  permissions for the database - just the database itself.  A separate script 
  with identical arguments has been created to automate the updating of 
  permissions, and is called as follows:

  ./checkdbuser.pl --database={name_of_db} --user={dbuser} --password={dbpassword}
  

  NOTE:  here, 'dbuser' and 'dbpassword' MUST be a user with privileges to 
  update the mysql:db database, as well as run a 'mysqladmin reload' - 
  usually root.  In all likelihood, if you created a programmatic user to run 
  the first script (checksetup.pl), it will NOT have sufficient mysql privileges
  to run the second.



@
