pjs/webtools/bonsai/README

This is Bonsai.  See <http://www.mozilla.org/bonsai.html>.


	==========
	DISCLAIMER
	==========

This is not very well packaged code.  It's not packaged at all.  Don't
come here expecting something you plop in a directory, twiddle a few
things, and you're off and using it.  Much work has to be done to get
there.  We'd like to get there, but it wasn't clear when that would be,
and so we decided to let people see it first.

Don't believe for a minute that you can use this stuff without first
understanding most of the code.

Check out the INSTALL file for some guidance on getting started.
Many, many thanks to Artem Belevich <abelevic@ctron.com> for
trailblazing his way through this and writing down all the problems he
had.


	============================
	Configuration files you need
	============================

Lots of configuration files need to be placed in the data subdir.
This is also where bonsai keeps its running state.  These two things
ought to be split into different directories, but that hasn't happened
yet.

Some of these files are:
treeconfig.pl: 	some Perl source that defines @::TreeList, a list of trees you
		want to track, and %::TreeInfo, information about each of those
		trees. 

params:	This file contains many operating parameters.  This can be 
	edited using the editparams.cgi webpage; you should probably
	not edit it directory.

	The ./configure script will make a guess at the parameters
	that control paths for scripts to execute, and create an
	initial params file for you.  It looks for things on your
	PATH, so if it complains, add the directories in which these
	commands reside to your PATH, or override the path check, for
	example:

		setenv PERL /usr/local/lib/perl5
		./configure

	or for the Bourne shell:

		PERL=/usr/local/lib/perl5 ./configure


hidelist:	A list of regexps that define filenames that we don't want
		to let people see via the bonsai pages.  A common use is to
		just have one line that says "CVSROOT". Note that the files
		and directories will actually be visible, this just prevents
		people from looking at their contents.

legaldirs:	A list of directories to traverse when rebuilding the
		history of the repository.  This file is required to exist
		for each module before you can start populating that module
		with existing cvs data.
		

	=================================
	What's What in the Bonsai sources:
	=================================

This is a rough first pass at cataloging and documenting the Bonsai
sources.  Many hands have been in this code over the years, and it has
accreted wildly.  There is probably quite a lot of dead code in here.

Makefile.in:		"make install" lets you specify where you store
			perl and bonsai on your system.

addcheckin.pl		Perl. Add a checkin to a Bonsai hook. Determines
			if the tree was open or closed at the time, shunts
			checkin to proper tree.

admin.cgi		Perl.  Select from various administrative tasks 
			(which require a password.)

			Called by: toplevel.cgi

			Calls:
				doadmin.cgi password=<text> treeid=<text>
					command=[open|close]
					closetimestamp=<time-text>
					lastgood=<time-text>
					doclear=<checkbox>

				doadmin.cgi password=<text> treeid=<text>
					command=tweaktimes
					lastgood=<time-text>
					lastclose=<time-text>

				doadmin.cgi password=<text> treeid=<text>
					command=editmotd
					origmotd=<text>
					motd=<text>

				editmessage.cgi treeid=<text>
					msgname=[openmessage|closemessage|
						 treeopened|treeopenedsamehook|
						 treeclosed]
				    #### note: no password?

				repophook.cgi password=<text> treeid=<text>
					command=repophook
					startfrom=<time-text>

				rebuildcvshistory.cgi password=<text>
					treeid=<text>
					command=rebuildcvs
					startfrom=<time-text>
					firstfile=<time-text>
					subdir=<time-text>

				doadmin.cgi password=<text> treeid=<text>
					command=changepassword
					password=<text>
					newpassword=<text>
					newpassword2=<text>
					doglobal=<radio>

adminfuncs.pl		Perl. Collection of functions to administrate a Bonsai
			hook.

adminmail.pl		Perl. Set of routines for opening and closing the
			Bonsai hook based on receipt of e-mail.

bonsai.gif		a bonsai tree.

closemessage	 	HTML, text that gets sent to all people on the hook
			when the tree is closed.	

configure		Configure script (generated from configure.in)

configure.in		Configure.in script

contacthelp.html	HTML, explanation of how to change someone's contact info

countcheckins.cgi	Perl.  Draws a graph of checkins for the various
			Bonsai 'hooks'.
			Called by: toplevel.cgi
			Calls: nobody

createlegaldirs.pl	Use this to create the 'legaldirs' file for a module.
			Called by (via globals.pl LoadDirList):
				addcheckin.pl
				moduleanalyse.cgi
				rebuildcvshistory.cgi
				repophook.cgi
				rview.cgi

cvsblame.cgi		Runs through a CVS file and tells you who changed what.
			Calls:
				rview.cgi dir= cvsroot= rev= 
				cvsblame.cgi file= rev= root= mark=
				cvsblame.cgi set_line= (cookie magic?)
				cvsblame.cgi root= file= rev= use_html=
				cvsgraph.cgi file=
				cvsview2.cgi subdir= files= rev=
				cvsview2.cgi root= subdir= files= rev1= rev2=
				cvsqueryform.cgi
			Called by:
				cvsgraph.cgi
				cvsguess.cgi
				cvslog.cgi
				cvsview2.cgi
				moduleanalyse.cgi

cvsblame.pl		Runs through a CVS file and tells you who changed what.
			Called by:
				cvsblame.cgi
				cvslog.cgi
			Calls: nobody

cvsguess.cgi		Given a file name, try to figure out what directory 
			it's in.  then link to cvsblame.cgi.  parameters are
			the same.

			Seems to take an exact file name (sans directory),
			then do a redirect to cvsblame.cgi.  If there are
			more than one file of that name, it presents a list.
			This is (I think) redundant with LXR's file name 
			search.

			Calls:
				cvsblame.cgi file= rev= mark= #
			Called by: *tinderbox

cvsindex.pl		???  			DELETE

cvslog.cgi		Web interface to "cvs log".
			Calls:
				rview.cgi dir= cvsroot= rev=
				cvslog.cgi file= root= rev= 
					sort=[revision|date|author]
					author=
				cvsview2.cgi 
					command=DIFF_FRAMESET
					diff_mode=context
					whitespace_mode=show
					root= subdir= file=
					rev1= rev2=
				cvsview2.cgi
					command=DIRECTORY
					subdir= files= root= branch=

			Used to call:
				cvsblame.cgi file= rev= root=
			Called by:
				cvsgraph.cgi
				cvsblame.cgi
				cvslog.cgi

cvsmenu.pl		???				DELETE

cvsquery.cgi		Displays the results of a query entered in cvsqueryform
			Called by: 
				cvsqueryform.cgi
			Calls:
				cvsqueryform.cgi
				cvsview2 command=DIRECTORY
					subdir= files= branch= root=
				cvsview2.cgi command=DIFF_FRAMESET
					diff_mode=context 
					whitespace_mode=show
					subdir= file= rev1= rev2= root=
				multidiff.cgi name=allchanges cvsroot=
				cvsquery.cgi sortby=
				../registry/who.cgi email=
				http://scopus.mcom.com/bugsplat/show_bug.cgi

cvsquery.pl		Actual query functions used by cvsquery.cgi
			Called by: 
				cvsquery.cgi

cvsqueryform.cgi	Main screen to let you query the CVS database.
			Called by:
				cvsblame.cgi
				cvslog.cgi
				cvsquery.cgi
				toplevel.cgi
			Calls:
				cvsregexp.html
				cvsquery.cgi 
					module=[all|allrepositories|?]
					branch=
					branchtype=[match|regexp]
					directory=<text>
					file=<text>
					who=<text>
					whotype=[match|regexp]
					sortby=[Date|Who|File|Change Size]
					date=[hours|day|week|month|all|
						explicit]
					hours=
					mindate=
					maxdate=
					cvsroot=

cvsregexp.html		Description of MySQL regular expression syntax

cvsview2.cgi		Lets you view CVS diffs.
			Called by:
				cvsblame.cgi
				cvslog.cgi
				cvsquery.cgi
				show2.cgi
				showcheckins.cgi
			Calls:
				rview.cgi dir= cvsroot= rev=
				cvsview2.cgi subdir= command=DIFF
					root= file= rev1= rev2=
				cvsview2.cgi subdir= command=DIFF_LINKS
					root= file= rev1= rev2=
				cvsview2.cgi subdir= command=DIFF
					root= file= rev1= rev2= #
				cvsview2.cgi subdir= command=DIFF_FRAMESET
					root= file= rev1= rev2=
				cvsview2.cgi subdir= command=DIRECTORY
					root= files= branch= skip=
				cvsview2.cgi subdir= command=LOG
					root= file= rev=

doadmin.cgi		Perl.  Executes admin things asked for in admin.cgi
			Called by:
				admin.cgi
			Calls:
				mailto:clienteng

doeditcheckin.cgi	Perl.  Edits a checkin on the hook.
			Called by:
				editcheckin.cgi
			Calls:
				nobody

doeditmessage.cgi	Perl.  Edits one of the email messages that bonsai sends
			people.
			Called by:
				editmessage.cgi
			Calls:
				nobody

doeditprofile.cgi	Perl.  Edit peoples contact info.  Left-over code from
			before we started getting this info from LDAP.
			Called by:
				editprofile.cgi
			Calls:
				nobody

doeditwhiteboard.cgi	Perl.  Edits the free-for-all whiteboard.
			Called by:
				editwhiteboard.cgi
			Calls:
				nobody

dolog.pl		Perl.  Magic file that causes CVS to send mail to
			Bonsai whenever someone makes a change.  Please read
			the comments towards the beginning for more clues.

dotweak.cgi		Perl.  Tweaks a bunch of checkins in ahook at once.
			Called by:
				show2.cgi
				showcheckins.cgi
			Calls:
				nobody

editcheckin.cgi		Perl.  Edits a checkin on the hook.
			Called by:
				show2.cgi
				showcheckins.cgi
			Calls:
				doeditcheckin.cgi

editmessage.cgi		Perl.  Edits one of the email messages that bonsai sends
			people.
			Called by:
				admin.cgi
			Calls:
				doeditmessage.cgi

editprofile.cgi		Perl.  Edit peoples contact info.  Left-over code from
			before we started getting this info from LDAP.
			Called by:
				localprofile.cgi
			Calls:
				doeditprofile.cgi

editwhiteboard.cgi	Perl.  Edits the free-for-all whiteboard.
			Called by:
				toplevel.cgi
			Calls:
				doeditwhiteboard.cgi

get_line.pl		Provides line parsing function, get_line
			Calls: nobody
			Called by:
				cvsquery.pl
				modules.pl

globals.pl		Common functions used by various scripts.

handleAdminMail.pl 	Perl. Mail is piped to this script and parsed.  
			Calls:
				adminfuncs.pl	

handleCheckinMail.pl	Perl. Mail is piped to this script and parsed. It
			then adds a checkin to a Bonsai hook.

header.pl		???				DELETE

index.html		loads cvsqueryform.cgi

indextest.pl		???				DELETE

lloydcgi.pl		parses CGI args from $QUERY_STRING and leaves them
			in $form{$key}; and puts cookies in %cookie_jar.
			Calls: nobody
			Called by: whohastouchedwhat.cgi

maketables.sh		Creates sql database & tables used by bonsai.
			Called by:
				nobody

moduleanalyse.cgi	Shows the directories in a module.
			Called by:
				nobody
			Calls:
				moduleanalyse.cgi module=[all|?] cvsroot=
				rview.cgi dir= cvsroot=
				cvsblame.cgi file= root=

modules.pl		Populates $::modules{} with list of CVS modules 
			from $cvsroot/CVSROOT/modules.			
			Called by:
				cvsqueryform.cgi

multidiff.cgi		Implements the "Show me ALL the Diffs" button
			Called by:
				cvsquery.cgi
				show2.cgi
				showcheckins.cgi
			Calls:
				nobody

openmessage	 	Mail template that gets sent to people when they first
			check into the tree

processqueue.pl		Pipes data/queue files to dolog.pl.	DELETE

rebuildcvshistory.cgi	Perl.  Admin script to go rebuild the bonsai database 
			from CVS.
			Called by:
				admin.cgi
			Calls:
				nobody

repophook.cgi		Perl.  Rebuilds a bonsai hook from the bonsai database.
			Called by:
				admin.cgi
			Calls:
				nobody

reposfiles.pl		Generates a list of all files in the repository.
			DELETE

rview.cgi		Lets you browse a directory in a CVS repository.
			Called by:
				cvsblame.cgi
				cvslog.cgi
				cvsview2.cgi
				moduleanalyse.cgi
			Calls:
				rview.cgi dir= cvsroot= rev=
				rview.cgi dir= cvsroot= rev= ?=chdir
				rview.cgi dir= cvsroot= rev= ?=Set Branch
				&make_cgi_args ???
				../registry/file.cgi cvsroot= file= dir=

showcheckins.cgi	Perl.  Shows some set of checkins in a bonsai hook.
			Called by:
				admin.cgi
				show2.cgi
				toplevel.cgi
			Calls:
				dotweak.cgi
				showcheckins.cgi [various funky args]
				editcheckin.cgi id= [various funky args]w
				http://phonebook/ds/dosearch/phonebook/...
				cvsview2.cgi root= subdir= files= 
					command=DIRECTORY branch=
				http://w3/cgi/cvsview2.cgi subdir= files=
					command=DIRECTORY
				multidiff.cgi allchanges=

switchtree.cgi		Perl.  Lets you choose a different bonsai branch.
			Called by:
				toplevel.cgi
			Calls:
				nobody

testlock.pl		Tests the Un/Lock functionality of utils.pl. DELETE

toplevel.cgi		Perl.  Main interface to the bonsai hook.
			Called by:
				CGI.pl
				contacthelp.html
				index.html
				sheriff2.html
				switchtree.cgi
				toplevel.cgi
				viewold.cgi
			Calls:
				editwhiteboard.cgi [...]
				http://phonebook/ds/dosearch/phonebook/...
				showcheckins.cgi
				http://warp/tinderbox/showbuilds.cgi
				switchtree.cgi [...]
				news:mcom.dev.client.build.busted
				http://phonebook/
				viewold.cgi [...]
				countcheckins.cgi [...]
				admin.cgi [...]
				index.html
				http://warp/client/dogbert/tree.html
				contacthelp.html
				http://warp/client/dogbert/buildlore/index.html

trapdoor		Runs crypt on passwd

utils.pl		Ancient globals.pl. 			DELETE
			Called by: testlock.pl  whohastouchedwhat.cgi

viewold.cgi		Perl.  Lets you choose an old bonsai hook to view.
			Called by:
				toplevel.cgi
			Calls:
				toplevel.cgi treeid=


	=================
	Glossary of terms
	=================

Here are some funky terms you may find here and there:

Hook			The 'hook' is actually the oldest part of the Bonsai
			code.  The idea is, every so often (at Netscape, it was
			every day), some build engineers will close the tree
			and make sure that everything still builds properly.
			If it doesn't, then the build engineers want to have a
			list of people they can go beat up, this being the list
			of people who changed the tree since the last time they
			successfully built the tree.  Those people are "on the
			hook"; they are held responsible for any probs that
			arise.

			So, it works out to: the list of people who have
			checked in since the tree was last closed.


	==========
	Maintainer
	==========

The current primary maintainer of Bonsai is Tara Hernandez <tara@tequilarista.org