Documentation Overview
There is a saying that the best software tends to be written as a response
to a programmers irritation with some problem. Buglet is a response
to the irritation of inadequate bug systems.
The Problem
At the time that Buglet was written(Nov 2000), there were approximately 60
different "Bug" systems available either in the open source community
or as proprietary solutions. All of these bug systems had severe
deficiencies. Some of the reasons include:
- Bug systems have a tradition of being written by the junior member
on a development team. Often, if the junior member shows promise,
the junior member is promoted and no longer supports the bug system.
This means that the normal life cycle of the bug system is almost always aborted before it even gets close to maturing.
- Bug systems have a strong bias either towards a database-centric view
or towards a front end GUI. Since most bug systems are begun by the
junior member of a development team, the code tends to lean either towards
the database or the GUI in proportion to the ability of the lead junior
member. If the bug system is database centric, then the User interface
ends up having so many items to fill in that it becomes a chore to enter
the data. If the GUI is prevalent, then the data tends to be stored in
a fashion that is not easily accessible.
- Many bug systems are reasonably good at storing lots of data about
bugs, but many seem to lack the ability to do any kind of statistical
analysis of the work. Many bug systems are stymied by the form of storage
that they have chosen. Its not enough to simply have the bugs, one needs to
be able to do statistical analysis on it. Managers need the numbers to
drool over; but more importantly for technical managers is to get a feel
for the rate of solution of products.
- Once a company chooses a bug system, they are stuck with it - it is
extremely rare that there is the chance to switch out bug systems, despite
the extreme need to do so in many cases. This is because every bug
system has a different database format. The efforts to define the most
important features of bugs seem to be so varied and to differ from system
to system in a way that is astounding. Bug systems are distinctly
incompatible between each other.
The Solution
The development of Buglet took a novel approach. Instead of focusing on
the database, or the user interface, buglet focused on an XML definition
for a bug. Given an XML definition of the information associated with a
bug, it is fairly simple to separate the labor required for a bug system
into parts:
- code that displays the XML in a User Interface
- code that maps the XML request to a database.
- code that maps e-mails to an XML definition.
The advantages of this scheme are numerous:
- Division of labor - its much easier to implement a piece of the
system because the interfaces are clearer and easier to address.
People with specialities can focus on the pieces that make it clear.
- The XML definition should allow bug systems to become compatible.
Clearly this ideal is dependent on the acceptance of the development
community at large to the concept of standardisation of bug information,
yet without a standard definition of the data required for a bug, its impossible to even dream about compatibility among bug systems.
- Multiple input paths are easier to implement. For example, its easy
to generate an e-mail in an XML format from a program that sends the stack trace automatically into the appropriate place in the bug system.
As long as the end result of the generation of a bug is an XML format message
in a standard format, it can be piped into the bug system.
Other Documentation
Javadocs
Technical Details
Buglet is named because of the servlet component web based GUI interface.
Buglet requires several other open source components to be in place in order to
run.
- The mysql database server must be installed. It requires a database named bugdb.
- The apache web server must be installed.
- A jsp/servlet engine must be installed. Buglet was designed and
implemented under Tomcat.
- Buglet was originally developed under the JDK 1.2. It is available
for linux from Blackdown
- Buglet depends on the xerces Java XML parser
Xerces
- Buglet needs a jdbc driver for the database being used.
It was initially written with the mm.mysql jdbc driver.
- Cocoon allows xsl transformations on XML. It is a convenient
tool for transforming XML into html. Cocoon runs on top of tomcat.
File structure of installation
The top level of the destribution has:
- com/bug58k - java source tree
- bugmail - classes to handle incoming e-mail.
- bugsystem - the core of the bug classes
- db - database creation scripts
- web/buglet - html/jsp interface
- web/buglet/docs - documentation for buglet.
Installation
There are two kinds of installations:
- First time installations
- Upgrades
At this writing, the first time installation is the only installation
mode described.
Installation involves three steps:
Get a distribution
- Download a distribution version or get the latest cvs version
Create and install the database
As mentioned earlier, buglet requires a database server running mysql.
If you have a database running, you will need to
- Create a user account named bugmeister
- Create a database named "bugdb"
- Run the installation script for the database schema. See
buglet/db/README for details of how to run installation script.
Install the software
- In the directory where the buglet application lives .e.g. /buglet on your
web server, untar the distribution.
Configure Tomcat
As mentioned earlier, buglet requires cocoon to be running on top of
tomcat.
- app.xml configuration
- web.xml configuration
Bug System Administration
There are number of configuration options that need to be set up
for the bug system to be useful.
XML definition
Here is the DTD for BugXML DTD
Here is an example of a bug in BugXML
bug.xml
Database Definition
All of the database definitions are under buglet/db.
The file buglet/db/README describes the way that the scripts
are to be applied. A utility perl script is provided that
will upgrade the database appropriatedly.
GUI
Tomcat Configuraton
You will need to define BUGLET_HOME in a shell script and then
pass it to the tomcat environment... (you will need to modify tomcat.sh)
java -DBUGLET_HOME=/export/web/docs/buglet org.apache.tomcat.startup.Tomcat
This is required so that buglet can find the conf directory
for buglet, i.e. /export/web/docs/buglet/conf.
The conf directory has different configuration options for the buglet system.
Obviously, you will need to adjust this depending on where your
installation of buglet is.
Initial Developers
Several people at 58k.com, inc. provided work for the product.
- Steve Brown, java coding and interface design.
- Thomas Riemer, inital XML definition, initial database design.
- Alvaro Muir, graphics.
General business users at 58k.com, inc. battle tested the code for six months.
TODO List
- Import and export utilities for bugs need to be written
- General web page configuration pages need to be written
- Customizable preferences for users when they first log
- Graphic for configuration page.