pjs/webtools/tinderbox2/Overview

Overview of the Tinderbox System
--------------------------------

Tinderbox is an information display system. It runs on a machine with
a webserver and will periodically write static HTML files to the disk
so that the webserver can serve these documents. Tinderbox is run out
of cron every five minutes.  It gathers up information from various
databases including: CVS Logs, Bonsai, and Perforce.  It will also
process mail which is sent to it. Mail is sent from Bug Ticketing
software and Build/Test Machines.  All this information is combined to
produce the HTML pages.


Since no two companies will structure their development processes the
same way, the tinderbox code has to be highly configurable to account
for most possible uses.  There is a main configuration file which
allows most of the major user configurable variables to be set.
Novice users can expect to edit only this file and get a working
tinderbox system.  Additionally each library has been broken into two
parts.  One part is the library specific configurations.  This file is
expected to need modifications in some installations.  I have put all
the library configurations into one directory to make it easy to find
the parts of tinderbox which are easy to modify.  Each configuration
library can be thought of as a table which might need to be edited or
extended for use at your company.  I have provided a working system
but the defaults may not suit your needs.  These tables can be easily
changed in small ways by simply looking at the file and making obvious
changes.  I have also allowed for the possibility of making complex
changes that only a competent perl programmer could define.  Changes
are not made to the files which I have provided.  Rather the changes
are made to copies of the files which are stored in a local
configuration directory.  This ensures that you can easily version the
Tinderbox code as it is provided to you from the official distribution
and you can separately version the local configurations which you
make.  It is also easy to see the local configurations since you have
both the original and the modified code on the same server and can
difference the two.  As an example you might need to change the
BuildStatus - I assume that you have the following possible build
outcomes (Build in progress, Build failed, Build succeded but tests
failed, Build and all tests were successful) You may have additional
outcomes to specify which kind of tests failed (unit test failed, not
enough unit test coverage, performance tests failed).  Similarly you
may have unusual requirements for how the filesystem should be laid
out.  I provide a outcomes to specify which kind of tests failed (unit
test failed, not enough unit test coverage, performance tests failed).
Similarly you may have unusual requirements for how the filesystem
should be laid out.  I suggest that you read through the files to see
how they are laid out and what types of changes are possible.


The build machines are not considered part of the tinderbox server.
They are clients just like Bug Ticketing systems and Version control
systems are clients.  Build machines mail their build logs to the
server in a special format.  This format specifies that name/value
pairs must appear at the top of the mail message followed by the
complete build log.  Scripts for setting up a tinderbox build client
can be found in the clientbin directory but you may have other build
needs and may use any build methods you choose.

The central concept of the Tinderbox system is the notion of a 'Tree'.
When several different groups are working out of the same version
control system often the files are partitioned into separate modules
with each group working on one or more disjoint modules.  Over time
the developers need to branch their code because several different
versions of the files are under development at the same time.  A tree
is a module/branch pair.  This corresponds to a set of files which can
be checked out and built.  Tinderbox makes one page for each tree and
displays what work is being done on that tree.  CVS has a notion of
branches and of modules but not of trees.  It is not possible to give
a branch/module pair a name.  The tinderbox TreeData provides the
mappings between treenames and branch/module pairs.  Tinderbox
displays the updates to bug tickets on the appropriate tree page.
This requires an easy mapping between bug tickets and trees. One
example of a complex function to determine tree name would be if each
of the product product types listed in the bug tracking data base
refers to one development project, except for a particular
feature/platform of one particular project which is being developed by
a separate group of developers.  So the version control notion of
trees (a set of modules on a branch) may not have a direct map into
the bug tracking database at all times.  In large projects it is
sometimes convenient to have a tree called 'ALL' which is used to
display all checkins performed on any trees and all bug tickets worked
on by any programmers.  It is not possible to build or test the 'ALL'
tree and neither the version control nor bug ticketing system knows of
its existence.


The Bug Tracking code was intended to be as general as possible.
Most bug ticketing systems send mail when tickets change state.  The
mail is often of the same form.  It is a name/value pair which the
separator being the string ": ".  Tinderbox will parse mail of this
form and display the interesting fields on the appropriate tree page.
The configuration of this module involves specifying which bug ticket
names are interesting and should be displayed.  Also you will need to
specify how to map a bug ticket into a a tree.  This could be very
simple if each bug ticket has a field which represents the tree it is
applicable to (in this case tree could equal project) or can be very
complex if the tree must be computed by the values of a set of fields.
Also tinderbox keeps track of which bugs are "reopened" and displays
them in a different column.  The idea is that some bugs are moving
backwards and creating duplicate work.  These tickets are particularly
troublesome and should be watched specially.  So possible all ticket
status are partitioned into "progress" or "slippage" categories.  You
will need to specify what status values are possible for your ticket
system and you will also need to specify the set of columns which you
would like to see on the status page.

The heart of the tinderbox system is the 'status table'.  This is an
HTML table which graphically shows how the changes made to the
development databases.  It will show what is going on in the version
control system, the bug tracking system, the build system, automatic
regression tests and provide a notice board for developers to inform
each other of current news.  By placing all this information in the
same table it is possible to correlate and cross check how different
types of changes effected each other and what was going on with the
whole project at different times in the day. The rows of the table
represent time with the most current events at the top of the page.
There are different sets of columns for each database which needs to
be displayed.  The sets of columns are managed by independent modules.
There is one module for each version control system and each bug
tracking system which tinderbox knows how to interface with.  It is
easy to port the system to new databases by just adding a new module
using the same style as the existing modules.  Modules never share or
peek at each others data all combining of data is done by the humans
who stare at the table and interpret what is going on.  The main
tinderbox system does not know how many columns the final table will
have. It only knows about a list of table modules.  Each module in the
list is called in turn to generate the complete row then the entire
row is displayed. The user must configure tinderbox with the list of
modules which are of important to their own environment.  There is no
restriction on the number of modules which may be configured, though
due to implementation details each module can only appear once in the
table.  There are many pop up windows embedded in the status table
these will provide extra level of detail when a mouse is placed over
the link.  By moving your mouse around the page you may effectively
drill down into an item of interest and learn more about it without
leaving the page.  Most of the links will click through to the
appropriate database.  Thus if you need more data about an item you
can click on the link and query the database directly.

Besides the status table there is one other feature of the status
page.  The page displays some information which is not correlated
through time and with other data.  This information is called status
table headers.  The main headers are the message of the day (MOTD),
and the Tree State though there are a few others headers of mainly
historical interest.  The important issue with the headers is that
they are not optional.  Tinderbox can render a table with as little or
as many columns in the status table as you wish but each of the
headers has a particular place on the status page and needs to be
rendered in a particular way (font size, font type, etc) thus the
tinderbox server must know where each header must go and how to
specify the appropriate html context for this header.  Users may set
null defaults for headers that they do not need but it is much harder
for a user to add new headers to the code in a modular fashion.