Section 3.4. Issue Tracking

3.4. Issue Tracking

, often called bug tracking (and sometimes request tracking), is the process of keeping track of your open development issues. Bug tracking is a misleading term in many ways and obviously depends on your definition of bug. "Issue" is a broad enough term to describe most of the kinds of tasks you might need to track when developing a web application, and so drives our choice of terminology here.

A good issue-tracking system is the key to smooth development of any large application. As time goes by and you pass the point where everything about the application easily fits into the head of one developer, you're going to need to keep track of everything that needs to be done. For a small application or a very small number of developers, keeping this sort of information on Post-it notes cluttered around your monitor is usually the natural way to handle keeping track of minor tasks (I'd be lying if I said my desk wasn't covered in scribbled notes). When you start to have more than 20 or so notes, or more than a couple of developers, this approach quickly breaks down. There's no way to get a good tactical view of everything that needs doing, swap tasks between developers, assign priorities, and track milestones.

Bringing in software to fill this role is a fairly logical step, and has clearly occurred to people beforehence the proliferation of available software. Since we're developing a web application and need some kind of multiuser tools, a web-based solution seems to fit the billmultiple simultaneous users, a single central data store, and no special client software. This is especially useful when you have a development team who use different operating systems.

3.4.1. The Minimal Feature Set

So what is it that we want to get out of our issue-tracking software? After we've defined what we want, we can look at a few available alternatives that fulfill our needs. We've already said that we're probably interested in a web-based tool.

The core feature of any issue-tracking system is, you guessed it, tracking issues. So the system has to handle entities (which we're calling issues here) and associate a few properties with them. At the very minimum, an issue needs a title and description. As an issue is worked on, we'll need to add comments or notes to keep track of our progress and ideas. When somebody creates an issue, he needs to retain ownership of it, but also be able to assign it to other developers. When an issue is assigned to a developer, he needs to be notified of this action somehow (email is an obvious mechanism), and in the same way, the issue's owner should be notified when the issue is resolved. To know when the issue has been resolved, we need some kind of status for the issue. So we have a small grab bag of properties: title, description, notes, owner, assignee, and status.

3.4.2. Issue-Tracking Software

When you're starting development, reinventing the wheel when it comes to your tools should be the last thing on your mind. There are a large number of issue-tracking and management systems already available and being used by web application development teams, and there's almost certainly one that can meet your needs, or one flexible enough to be modified to meet them. If you select tools written in the same language as your application and you're storing their data in the same backend database, then customization and integration, if needed, will be more straightforward.

We'll examine a few of the popular available choices, both free and not, and compare the main features they offer. Commercial issue-tracking software can be very expensive (in the tens of thousands of dollars range), but we won't be looking at any of those systemswe're more interested in filling the role quickly and cheaply, allowing us to evolve into a more tightly integrated workflow later. Spending a lot of money up front on development tools is not always a great idea.

3.4.2.1. FogBugz

Created by Fog Creek Software, FogBugz (http://www.fogcreek.com/FogBugz/) is a very simple project management and issue-tracking tool. There are two versions available as of this writing, one for Windows servers using ASP and one for Windows/Unix/OS X using PHP. The Windows version can store its data using either Jet, MySQL, or SQL Server, while the Unix/OS X version stores its data using MySQL. FogBugz is the only issue-tracking software in our list that isn't free, but is included here because it's reasonably inexpensive ($100 per developer is usually a trivial cost next to paying your developers and buying hardware) and extremely effective.

Pros

Very, very simple to use.
Actively developed product with good support.
MySQL backend for storage allows easy integration with your own application.

Cons

Not free. For small teams it costs between $100 and $130 per developer.
Lacks advanced features (although this could easily be considered a pro).

3.4.2.2. Mantis Bug Tracker

The Mantis Bug Tracker (http://www.mantisbt.org/) is an open source issue-tracking application written in PHP that stores its issue data using MySQL, with experimental support for PostgreSQL. As of this writing, version 1.0 has not been released, but is expected very soon. The product is fairly young, but with a wide and active developer and user base.

Pros

Easy to installcomes with a simple install script.
Written in PHP and uses MySQL. Easy to modify and integrate with your application.
Active developer community.
Support for source control integration with CVS.

Cons

Not as many features as Bugzilla or RT.
Under-documented configuration files.

3.4.2.3. Request Tracker (RT)

Request Tracker (http://www.bestpractical.com/rt/), also known as RT, was created in 1996 by Best Practical Solutions. Written in Perl (and mod_perl compatible), RT stores issue data in either MySQL, PostgreSQL, or Oracle, with support for more databases in progress. RT was primarily designed to handle issues initiated by usersissues can be easily entered into the system via email, and the system acts as a log of email conversations between the user and the issue administrator.

Pros

Good email support for creating issues.
Can use a variety of database for storage, so is easy to integrate with your application.
Uses a simple templating system so the appearance can easily be modified to suit your tastes.

Cons

Email-oriented approach to creating issues works well for users reporting problems, but not so good for tracking development issues.
Overly complex issue viewing and management interface.
Interfaces designed by programmers provide a lot of features but are difficult to pick up and use.

3.4.2.4. Bugzilla

Bugzilla (http://www.bugzilla.org/) was created by the people at the Mozilla Foundation (creators of the Mozilla family of products, including the infamous browser) in 1998 to help them track issues during the development of Mozilla itself. Bugzilla is written in Perl and uses MySQL for its storage, although there is work in progress to allow storage using PostgreSQL. Bugzilla is a mature product with hundreds of features and a very active developer community.

Pros

Many, many features.
Uses MySQL for storage, allowing easy linkage directly into your application.
Well tested, with a very active developer base.

Cons

Too many features! The huge number of features and options make Bugzilla very difficult to configure and use.
Doesn't run under mod_perl, so you'll need to use Perl in CGI mode, which can be a little slow.
No way to add custom fields to issues.

3.4.2.5. Trac

Written in Python, Trac (http://www.edgewall.com/trac/) is an issue tracker with a few extra features thrown in. On top of all the usual issue-tracking features, it also includes a fairly good Wiki engine and a source control repository browser. Trac is written in Python and stores its issue-tracking data using SQLite. There's a branch of the code to support storage using PostgreSQL (and possibly other backends) and although the branch is currently incomplete there is work going on in this area. The repository browser built into Trac is for Subversion only.

Pros

Easy to installuses a single Python install script.
Very straightforward interface.

Cons

Stores data in SQLite or PostgreSQL, which probably isn't what you're using for your main application, so integration with the rest of your workflow can be tricky.
Only works with Subversion, and requires it.
Requires the ClearSilver templating engine.

3.4.3. What to Track

Once we have our shiny new issue-tracking system, what exactly should we be tracking with it? There are four main classes of items we're probably going to want to keep track of. We'll look at each of these and see how our issue-tracking system can help.

3.4.3.1. Bugs

Bugs are the bread and butter of developers everywhere. When a bug is discovered, immediately create a case for it, even if you're not going to work on it immediately. Bug work can be assigned to the relevant developer, prioritized, and worked on. As work on diagnosing and solving a case progresses, notes can be added to the case with details.

3.4.3.2. Features

As features are planned and work is assigned to developers, each task or subtask can be added to the issue tracker to allow progress to be monitored. Adding features into the same system as bugs allows developers to get a general sense of outstanding work assigned to them, and to easily do bug and feature work at the same time.

3.4.3.3. Operations

Any operations that won't be completed immediately are suitable for issue tracking. If you have a database schema change that other tasks are waiting for, creating an issue for it and linking it to the dependent issue allows developers to track when outstanding operations are completed.

Putting operations in issue tracking also means that any needed details can be added as notes, so all the information a developer might need about an issue is available in one place.

3.4.3.4. Support requests

Although not usually a candidate for integration your development issue tracker, customer support cases (assuming you have customers) eventually need to be tracked somewhere. Most issue-tracking systems allow the creation of new issues via email and can then track an email exchange between you and your users.

Support tracking is something you won't necessarily need from the start. When you launch an application at a small scale, managing a tracking system will be more labor-intensive than simply talking to your users via email. When a user issue comes in, the dialog can be continued, a bug case created in the main issue tracker (if the issue is in fact a bug), and then the cases can be resolved over email.

A good support case-tracking system will probably need to be integrated with your user account data and payment data (if your application includes any) but is outside the scope of this book.

3.4.4. Issue Management Strategy

There's a now-famous story about the development of the original version of Microsoft Word for Windows. Because of the pressure to quickly finish features on schedule, developers were forced to cut corners and tick tasks off their lists without enough time to complete them. The story goes that a developer working on the function to return the height of the current line in pixels just wrote return 12;, committed the code, and left it to the testing phase for the bug to be discovered and fixed (by somebody else), so he could keep on schedule. Predictably, the project shipped years overdue, and not just because of this single bug.

Microsoft called this sort of development the "infinite defects methodology": the model of turning feature requests quickly into outline implementations and lists of bugs, leaving a huge number of defects to be all dealt with later. In subsequent projects, Microsoft adopted the slightly amusingly named "zero defects methodology." Rather than just wishful thinking, this methodology proved to be very successful. The idea is very simplefix bugs before working on new features.

The premise of the "fix bugs first" approach is easy to graspthe smaller the gap between working on the feature and fixing the bugs with it, the quicker and cheaper the bug is to fix. This stems from the idea that developer context switching is one of the most expensive actions to perform. If a developer fixes bugs on the feature she's been working on immediately after working on the feature, then she's still going to have the work and the architecture fresh in her mind, and so is in the best position to fix it. The longer a bug is left, the more context switching is involved for the same developer to get back up to speed with what she had done. This applies to an even greater extent when one developer fixes another developer's bugs.

As well as saving time (and by extension, money) by fixing bugs as soon as possible, the strategy of fixing bugs early can have a positive impact on your schedule. It is much easier to accurately allocate time for new feature development than for bug fixing. If you ask a developer to estimate how long it will take to add a new preference to user accounts, he can probably give you a fairly accurate estimation, and you can use that to plan your development schedule. But if you ask the same developer to fix a bug causing the user's preferences to occasionally be reset, there's no way he can know how long the task will takefixing bugs in code you haven't visited for a while is a slow and meticulous process, and the larger your application grows, the longer it takes to track down each bug. With a lot of open bugs floating around, each without a definite timescale, it becomes impossible to accurately plan development time past your immediate tasks.

3.4.4.1. High-level categorization

It can be helpful to categorize pending bugs and issues into very high-level categories, even if you can't prioritize them down to a fine level. It's helpful to create three levels of priority or severity:

S1/High: S1 issues are issues that must be fixed right away. These are usually showstopper issues that are causing damage in deployed code or stalling all current development. When you assign an issue with S1 priority, you should be immediately assigning developer time to the problem, unless other S1 issues precede it in the queue. All feature development and less severe issue execution is paused until the issue is resolved.
S2/Medium: S2 covers issues that are important, but need not block the current tasks people are working on. These might include very important features and reasonably important bug fixes. When a developer comes to start a new task, she should work on any existing S2 issues she can before working on S3 or uncategorized issues. If you find an S2 issue can't be worked on for some reason, or becomes less of a priority, then downgrade it to an S3. Management of issues becomes difficult when you keep many open issues around with medium or high priorities. Keeping as few issues as possible with a high priority is essential in order to avoid your development team feeling overwhelmed.
S3/Low: The lowest categorization of issues, S3 should be used for new feature work and nonessential bug fixes. Work on issues in the S3 category should only be started when there are no issues assigned with either S1 or S2 priorities. Tasks in S3 can typically then be blocked out in planning sessions, as they tend to be estimatable.

3.4.5. CADT

In 2003, Jamie Zawinski of the Mozilla Organization (and previously one of the developers of Netscape Navigator) wrote a short, tongue-in-cheek article about a new software development paradigm that he labeled the CADT or "Cascade of Attention-Deficit Teenagers" model (http://www.jwz.org/doc/cadt.html).

The core tenet of the CADT model is to avoid fixing bugs and only add new features. When a feature has received enough filed bugs, simply rewrite the feature from scratch and close all of these bugs (and usually without actually having fixed them). Although nobody explicitly plans to work this way, this methodology can quickly be adopted by developer teams, especially when developers get the mindset that fixing bugs is too boring, and rewriting features is fun. The rewriting of features from scratch, especially when the aim is to fix bugs, is not a good strategy (even when you have test-driven development, which we'll discuss below). When the rewriting of features outstrips the fixing of bugs, you need to take a serious step back and look at your development practices.

This so-called CADT behavior is especially prevalent among large developer teams, where developers are reluctant to fix other people's bugs. This tendency can be partly battled by making developers take responsibility for their own features, and fixing their own bugs. But, again, the wider solution to stopping this sort of vicious circle from happening in the first place is to create a culture of "zero defects," in which all bugs are fixed before new features are developed.