This README file is for Kamikaze-QSCM a source control query tool for
the Subversion (http://subversion.tigris.org) tool. 

For best viewing,set your tab width to 4.

== Table of Contents ==
	[1] Introduction
	[2] Requirements
	[3] Getting Kamikaze-QSCM
	[4] Installation
	[5] Usage
	[6] Reporting problems and getting help

To jumpt to a specific heading, just search for "[#]" where 
number is the topic number.

== [1] Introduction ==
	Kamikaze-QSCM is a tool that allows developers and CM related 
	personnel to query the commits made to one or more source control 
	repositories. It is very similar to Mozilla's bonsai tool. 
	Kamikaze-QSCM currently works with Subversion, but a modular 
	approach is planned for other SCM systems.
	
	Kamikaze for Subversion currently consists of a PERL back-end hook 
	for inserting commit information into a MySQL database. 
	(In the future, a modular approach to data storage is planned - 
	allowing the use of many different data storage implementations. ) 
	A PHP front-end is used to perform repository queries and display 
	results. (In the future a web service API (XML-RPC and/or SOAP) 
	will be provided to access the same information for incorporation 
	into other tools.)
	
	For the latest news and information visit: http://kamikaze-QSCM.tigris.org.

== [2] Requirements ==
	* PHP with MySQL support
	* Perl::DBI with MySQL support

== [3] Getting Kamikaze-QSCM ==
	Kamikaze can be downloaded from the Kamikaze project site: 
	http://kamikaze-QSCM.tigris.org
	
	If you have CVS access you can download the latest versions from here:
	http://kamikaze-QSCM.tigris.org/source/browse/kamikaze-QSCM/src/
	
	Otherwise you can get the latest official releases here:
	http://kamikaze-QSCM.tigris.org/servlets/ProjectDocumentList?folderID=3549
	
	Releases are packaged in tarball form and compressed using gzip.  
	Winzip, and other gzip utilizes usually support extracting files from 
	the tar format as well.  In the GNU world you can type the 
	following from a command prompt:
	tar -zxvf kamikaze-qscm.v0_1.tgz
	
	This will create a folder called kamikaze-qscm in the current 
	working directory.  

== [4] Installation ==
	This section assumes that you successfully got the latest version as
	described in [3].  You should have a folder called kamikaze-QSCM in a 
	temporary folder.  You should see directory contents similar to the 
	following:
	
	* README.txt - this file
	* RELNOTES.txt - release notes
	* db/ - sql files for creating the necessary MySQL tables.
	* hooks/ - PERL back-end scripts for hooking into Subversion commit information
	* html/ - PHP front for performing queries on commits
	
	Perform the following steps:
	
	1) Create MySQL Database and Tables
	You must have a working MySQL database and a valid user(s) that can 
	perform the necessary operations:
	* During Installation: CREATE DATABASE, CREATE TABLE
	* To use Kamikaze-QSCM: INSERT, UPDATE, SELECT
	
	For security reasons you may wish to use separate users - one for 
	installing the database and tables, another for populating it with 
	data.
	
		1.1) Create the database and tables by changing directory to 
		db/ and execute the MySQL SQL code in createdb.sql as follows:
		
		mysql < createdb.sql
		
		depending on your mysql set-up you may need to specify 
		the user and password:
		
		mysql -u username -p < createdb.sql
		
		Confirm that a database called svncommits now exists in MySQL and
		that the following tables exist:
		* author
		* repository
		* revision
		* resource
	
	2) Install the web interface
	
		2.1) Copy the html directory to a location that is accessible 
		to your web server. Your web server must support PHP 
		(with MySQL support).  
		e.g. On 'NIX platforms:
		
			cp html /var/www/html/kamikaze
			cd /var/www/html
		
		2.2) Change ownership of the kamikaze directory accordingly:
		e.g. On 'NIX platforms:
		
			chown -R apache:apache /var/www/html/kamikaze
			chmod ug+rwX /var/www/html/kamikaze
		
		2.3) View the page in your browser
		Visit the Kamikaze web interface in your web browser.
		e.g. 
			http://your-host/kamikaze
			
		You should see a query form with no entries for Repository 
		or User except "**ALL**".  This will change as commits are 
		captured from Subversion.  
	
	3) To get the commit information, Kamikaze requires that you
	install a post-commit hook that will populate the tables.  
	You must do this for every repository that wish to query.  
	Change directory to hooks/
	
		3.1) Edit commit2db.pl
		
			3.1.1) On the very first line:
			#!/usr/bin/PERL -w
			Change "/usr/bin/PERL" to the path to your PERL 
			executable if your path is different.
			
			3.1.2) Edit the "# Kamikaze DB information" section to 
			match your database settings:
			Set $host to the hostname that hosts your database:
			my $host = 'localhost'; 
	
			Set $db to the name of the kamikaze database that was created 
			- svncommits was the default - you shouldn't have to change 
			this:
			my $db = 'svncommits';
			
			Set $db_user and $db_password to the database user and 
			password that has, at the very least, SELECT privileges 
			on MySQL db $db:
			my $db_user = 'svnuser';
			my $db_password = 'svnuser';
			
			
			3.1.3) Edit the "# Svnlook path" section:
			Set $tmp_dir to a location that the web server user may write 
			temporary data:
			my $tmp_dir = '/tmp';
			
			Set $svnlook to be the full path to the svnlook 
			Subversion utility:
			my $svnlook = "/usr/bin/svnlook";
		
		3.2) Test commit2db.pl by calling it manually:
		PERL ./commit2db.pl /path/to/repository 1
		This command *should* insert the very first revision info 
		for the repository at /path/to/repository

		e.g.
                $ PERL ./commit2db.pl /home/svnroot/repos1 1
		Repos:/home/svnroot/repos1, rev:1
		New repository /home/svnroot/repos1 with id 1.
		Created new author jduprey with id 1.
		
		If you refresh the Kamikaze query web page you will see that
		the repository has been added to Repository and the relevant 
		user for revision 1 has been added as well.  Click 
		"Since the beginning of time" in the "Date Options" section of
		the query form and you should see the commit information for
		rev 1.
		
		3.3) Install the post-commit hook for each repository 
		you wish to monitor.  Refer to the subversion 
		documentation for how to install hooks:
		* http://svnbook.red-bean.com/
		* Specifically (Subversion 1.1) http://svnbook.red-bean.com/svnbook-1.1/svn-book.html#svn-ch-5-sect-2.1
		
		If you have not already created a post-commit hook, you 
		*should* be able to simply copy commit2db.pl 
		to /path/to/repository/hooks/post-commit
		Change its permissions accordingly - giving it execute 
		permissions for the subversion user user.
		
		Alternatively you can call commit2db.pl from within an 
		existing post-commit script as follows:
		/usr/bin/PERL /home/svnroot/repos1/hooks/commit2db.pl $REPOS $REV
		
		The above example assumes that the post-commit script has defined the 
		repository and revision for the variables $REPOS and $REV respectively.  
		(It also assumes that commit2db.pl was copied to the hooks 
		directory.  A symbolic link could also be used to avoid 
		multiple copies as long as the permissions were appropriate.)
		
		If you can, test the Kamikaze hook by, committing something 
		to the repository.
		
		3.4) You may, optionally, back-fill commit information for each 
		repository by calling commit2db.pl with 0 as the revision.
		e.g.
			perl ./commit2db.pl /path/to/revision 0
		
		This will collect all commits since the first revision 1.  
		For repositories with a large revision history, it can 
		take a while to populate.

== [5] Usage ==
	You're on your own for now.  ;)

== [6] Reporting problems and getting help ==
	== BUGS ==
	If you think you've found a bug, please first check the RELNOTES.txt 
	file. This may explain any known issues with the software.  
	Second, check the open issues with Kamikaze here:
	http://kamikaze-QSCM.tigris.org/servlets/ProjectIssues
	
	== Help ==
	If you are having problems installing or using Kamikaze, check the 
	mailing list archives:
	http://kamikaze-QSCM.tigris.org/servlets/ProjectMailingListList
	If you don't find anything useful there, join the appropriate list 
	and ask.
	
	NOTE: Please make use of these resources *before* e-mailing me directly.  
	Using a mailing list is the appropriate medium for help and the discussion 
	is saved for posterity.  It could help another person in the future.
	
	Lastly, if you still have not resolved your issue, please do contact me.
	
	I hope you find the software useful and not a waste of bits.  ;>
	
	Sincerely,
	
	John Duprey
	jduprey@tigris.org