We propose the YakTrack utility, which is really a set of tools used to create and maintain a simple text-based repository for tracking various types of issues. The database uses simple XML templates to define issue types (see the "Other Issues" section on what we mean by simple), and stores each report as a separate XML file in a repository; the issue-tracking repository is implemented in a subdirectory of the main development repository, and thus falls under the same configuration managament as the rest of the development effort. Because different aspects of the system satisfy different user classes, YakTrack presents a "layered" architecture; immediate tools and commands represent features available to those having their own "copy" of the issue-tracking database; email gateway tools and commands represent features available to remote users of the system who will be accessing YakTrack through an email address; web gateway tools and commands represent features available to remote users who will be accessing the system via a web interface.
To avoid dependency on external tools, to keep the implementation fairly simple, and to keep the repository integrity robust, issues will be stored as separate XML files in a directory tree beneath the main development; a typical repository might look something like this (directories are noted with an asterisk):
[vputz@yak_prime yak4]$ ls -R *CVS *src *yaktrack-repository yaktrack-repository: *CVS *templates *awaiting-review *issue-reports *yaktrack-options yaktrack-repository/templates *CVS defect.dtd use-case.dtd yaktrack-repository/awaiting-review 1.xml yaktrack-repository/issue-reports *CVS *defect *use-case yaktrack-repository/issue-reports/defect *CVS 1.xml 2.xml *2.xml.attachments yaktrack-repository/issue-reports/defect/2.xml.attachments *CVS screenshot.png yaktrack-repository/issue-reports/use-case *CVS 1.xml 2.xml 3.xml yaktrack-repository/yaktrack-options (various files for scripting YakTrack)
In the example repository, the templates subdirectory contains DTDs which define the possible issues which this repository can handle. In this case, the repository can handle both defect reports and use cases.
The awaiting-review subdirectory contains submitted issues which have not been filed. If a filed report is invalid (does not use one of the existing DTDs, uses it incorrectly, or has other errors), it is filed in the awaiting-review directory until the issue-tracking administrator can deal with it. If YakTrack is configured so that all reports must pass through the administrator, then all submissions will be placed here to await review.
The issue-reports directory holds all the submitted and maintained reports; a separate subdirectory (matching a DTD in the templates directory) contains all the issue reports using that DTD, each maintained in a separate XML file. If any attachments are associated with an issue report, they are stored in a directory using the name of the report suffixed with .attachments. In the sample repository above, the defects/1.xml report has a screenshot attachment in PNG format. The filenames are the unique identifiers of the submitted reports; usually, YakTrack itself will create these identifiers (above, the reports are simply assigned numbers in a serial fashion). If all reports pass through the administrator, they can decide identifiers in a more usable fashion (for example, "defects.user-interface.helpbutton.xml"). The identifier is also stored in the file itself once assigned by YakTrack (in the form of an element or XML comment -- this is to be determined), so that if a report is retrieved, edited, and resubmitted, it will replace the original submission (not as alarming as it sounds, since the repository is under configuration management, which reduces the risk of catastrophic data loss and provides a mechanism to show the history of an issue's changes).
Finally, the yaktrack-options directory contains files which modify or augment the behaviour of YakTrack. This could include different logic for assigning identifiers, logic for workflow if necessary, utilities for generating documents or metrics from the database, additional information on checking files into and out of configuration managament, etc. The YakTrack suite is primarily scripted through the use of Python, although since it can be used via the command line, a great deal of scripting can be done through system-specific scripting languages.
While this sort of straightforward arrangement is not particularly efficient, it maintains a strong mapping between the user's conceptual model of an issue repository (containers of issue reports with attachments) and the physical model on disk (directories of issue reports with attachments in subdirectories), which helps understanding considerably and is easier to muck around with and comprehend than a faceless database.