Overview

CVSTrac is a Web-based issue tracking tool that integrates with the CVS version control system, popular among Mac OS X and Unix users. An “issue” can be anything you want: a bug report, a feature request, a technical support incident, a to-do item, or simply a chunk of text that means something to you. CVSTrac is designed for software developers, but it’s also useful for tracking information in other domains. Developers can think of it as a lightweight product that combines the basic features of Bugzilla and CVSweb. Non-developers can think of it as a Web-based information management and collaboration tool along the lines of Inspiration, Slacker ToDo Lists, and ToDo X.

Installation and Setup

Although there are some stand-alone commercial issue tracking tools, most of the free ones are Web-based. To use them, all you have to do is type the URL into your Web browser. Setting them up, however, is another matter. Even the simpler products typically require a series of steps:

• Set up a Web server and configure it to use a scripting language such as PHP.
• Install a database server such as MySQL or PostgreSQL and make sure it’s hooked up to the above scripting language.
• Install the files for the issue tracking tool, and possibly some libraries that it needs.
• Create an empty database and fill in the configuration information so that the issue tracking tool can access the database.
• Install a separate tool such as CVSweb or Bonsai if you want to access version control information.

CVSTrac, in contrast, is a single file that includes a built-in Web server and database engine. Although you can build your own copy of CVSTrac from its source code, it’s much easier to download a pre-built version for Linux or Mac OS X, the latter hosted by yours truly.

There are several different ways to install CVSTrac, depending on how you want to use it. First, you type a command into Terminal to create a new database. If you have administrative access to the machine that will be running CVSTrac, you can set it to respond on a particular port. If you’re running CVSTrac on your Web server, you can set it to run as a CGI script; this doesn’t require any special access to the server. Finally, you can run it on your own Mac using CVSTrac’s built-in Web server, by typing a command into Terminal.

A CVSTrac database is a single, ordinary file so it is easy to back up. There’s no need to use a special “dump” utility, as with fancier database servers. If you want to use CVSTrac on the road, all you have to do is copy the database file onto your PowerBook and run CVSTrac there. Of course, you can also run CVSTrac on an Internet-accessible server so that multiple users can access it, from around the globe.

Web Interface

Once you’ve created a database and started up CVSTrac, you can access it by typing a URL such as “http://localhost:8008/MyDatabase/index” into your browser. CVSTrac uses the user accounts you’ve set up in your CVS repository. You have to type a password to log in, but the HTTP connection is not encrypted. I’ve used CVSTrac from Safari, Internet Explorer, and iCab, but I couldn’t get the login function to work from Camino or Mozilla.

Some applications, such as e-mail, don’t work very well from Web-based interfaces in my experience. They feel clumsy. However, although I’ve occasionally wished for a real Mac interface, I’ve mostly found CVSTrac’s Web interface to be a plus. The information it presents is highly intertwined, so hyperlinks are natural. The Web browser is actually a very flexible interface. You can open several windows to look at different things simultaneously, or use a single window. Each screen has a permanent URL that you can bookmark. You can use the browser’s Find command to help navigate within a page, and with Safari each text field has built-in spell checking and auto-completion. Browser text fields do leave something to be desired, but since they’re just plain text it’s easy to copy and paste into BBEdit when you need fancy editing commands.

The Web interface is simple and clean compared to other systems I’ve used. The different fields and option are presented clearly, and often with some help text. The look of the Web interface is not very customizable; you can only adjust the header and footer. On the other hand, I was happy with the default look. Since CVSTrac is open-source, further customization is possible by editing its source code. However, this may be more difficult than with other products because the source is in C rather than in a scripting language like PHP or Perl.

Tickets

A ticket in CVSTrac is essentially a to-do item. It has a summary, a description, and various other pieces of information. Each ticket can be categorized as a bug report, an enhancement request, or as some other custom type. It can also be assigned a severity and a priority. The severity indicates how important the ticket is (does it represent a crashing bug, or a spelling mistake in a dialog box), and the priority indicates when the ticket should be resolved. The priority and severity are represented on a numeric scale, and CVSTrac explains what each number means next to its pop-up menu. This is a great help when there are multiple users, as it ensures that people assign the numbers based on the same scale.

CVSTrac tickets do not have as many fields as in similar products, and I see this as a plus. It has all the essential fields, plus five custom ones.

The description field of the ticket is plain text, but CVSTrac has some simple markup that you can use to add styles and links. Put asterisks around a phrase and it will be displayed in bold. Indent some text, and it’s displayed in a fixed width font. Start a series of lines with “*:” or “1:” to create bulleted or numbered lists. Create hyperlinks to other tickets or to CVS check-ins. You can also attach files and images to the ticket, and they will be stored in the database. Resource forks are not preserved, however. Images may be displayed inline. Clicking on the name of an attached file lets you save it to disk. CVSTrac remembers the name of each file, but for some reason it saves the files as “attach_get” by default.

After creating a new ticket, you can view it in a more compact form without all the text fields and pop-up menus. You can edit tickets as many times as you want, and CVSTrac remembers the complete change history.

CVS

CVSTrac includes a great CVS repository browser. Clicking on a file shows its revision history. You can easily see any version of the file, as well as a list of the other files associated with each check-in, and the differences between pairs of revisions. By default CVSTrac uses the rcsdiff program to compare revisions, and you can also customize the command that it uses. For instance, I set it to convert the output of rcsdiff to HTML. Normally, added lines are prefixed with “+” and deleted lines are prefixed by “-,” but with HTML I could make it so that the deleted lines were colored red and new ones were colored blue.

If the CVS commit message includes text like “#28”, CVSTrac will link the number to the corresponding ticket. I found CVSTrac’s repository browser easier to use than CVSweb, although CVSweb as a few more features such as the ability to make tarballs. My only complaint is that CVSTrac is not very flexible in letting you decide which modules of the repository to view. It either shows every module, or only those modules whose names start with a particular prefix.

Timeline

The timeline shows a chronological list of check-ins, tickets, and any other changes to the database. There are various options to control which events are displayed.

Reports

Reports let you display lists of tickets that meet particular criteria. For instance, you could have a report that lists open bugs in order of priority, or one that lists all the recent feature requests. CVSTrac comes with lots of reports that you can use. I didn’t like the colors it used to show the priorities of the tickets, but they were easy to customize. You can use the SQL database language to create your own custom reports. Unfortunately, there is no way to share custom report formats among different CVSTrac databases. Each time you start a new project you’ll have to paste in the SQL queries for all your favorite reports.

Wiki

In addition to tickets, CVSTrac lets you enter information in wiki form. A wiki is a collection of hypertext documents written in plain text. This doesn’t give you as much layout control as with HTML, but it makes it much easier to create and edit simple documents. (VoodooPad is a stand-alone Mac program that lets you create wikis.) CVSTrac wikis use the same simple markup language as tickets, and wiki pages can have links to tickets, check-ins, and Web pages, as well as other pages in the wiki. CVSTrac remembers all the changes you make to a wiki page, giving you a kind of unlimited undo.

Most issue tracking tools don’t have wikis, but I’ve found CVSTrac’s to be very useful. It’s great for recording ideas, notes, results of experiments, and other types of information that don’t fit the ticket mold.

Search

Searching is CVSTrac’s weakest feature. On the plus side, it’s very easy to use. You just type in a few words and specify whether CVSTrac should search the tickets, check-ins, or wiki pages. It then shows you a ranked list of results. The problem is that often times you get too many results back and there’s no way to winnow them down, as in tools like Bugzilla. All is not lost, though, as you can use CVSTrac’s custom report feature and some SQL to do complex searches.

Notification

Unlike some other systems, CVSTrac does not automatically send out e-mails when tickets are created or modified. However, it does let you run a custom shell command each time a ticket is modified; you could use this to roll your own e-mail notification system.

Conclusion

Larger teams might prefer a tool with more fine-grained access control for multiple users and one that integrates with their customer support ticketing system. However, I think CVSTrac is ideally suited for individuals and small teams. It’s a huge improvement over using low-tech “TODO” files, as many people do, and vastly superior to anything you’d make in FileMaker or Excel.

CVSTrac doesn’t have as many features as some competing products, but it’s easier to install and use, and the features it does have hang together well. I don’t know of any other product that integrates ticketing, repository browsing, and a wiki. CVSTrac does that and does it well. This is not the stereotypical open source project with an amalgam of geeky features. The developer has shown enormous restraint in keeping it simple, and the result is one of the most elegant pieces of open source software that I’ve seen.