Bug-Bustin' (A phpBugTracker Primer)

Use phpBugTracker to design a defect-correction workflow that finds and squashes bugs.

A Bug's Life

Bugs are the bane of every developer's life.

I'm not talking about the squishy ones, the ones that buzz around you all day and make you want to reach for the nearest magazine. I'm talking about the ones that cause stressful days and sleepless nights for software developers. I'm talking about the mistakes and defects that creep into software during the development phase because of unrealistic deadlines, overbearing project managers, unreasonable customers, nit-picking QA teams...or all of the above.

Jokes aside, the process of quality assurance plays a vital role in the process of developing "good" software. And an important component of this process is so-called bug-tracking software, which allows the development and QA teams to work together in harmony to identify, analyze and correct software bugs in a streamlined manner.

Typically, bug-tracking software allows a QA team to record the bugs encountered during the testing process, and generate reports which can then be forwarded to the development team. It also allows the development team to view bug reports, to assign each bug to the concerned engineer, and to resolve them in a systematic manner. And as development teams become fragmented across geographical locations, Web-based bug-tracking applications, which let developers collaborate with each other to resolve bugs online, are rapidly coming to the fore...

That's where phpBugTracker comes in.

The Big Picture

According to its developer, Benjamin Curtis, phpBugTracker is "a replacement for Bugzilla...this project grew out of the frustrations I experienced in installing and using Bugzilla". It provides a simple, user-friendly repository for bug reports, allowing developers to track bugs on multiple projects simultaneously. Built around a MySQL database, phpBugTracker supports multi-user access, making it possible to restrict users (or groups of users) to specific projects.

As a collaborative tool, phpBugTracker allows developers to discuss each bug using an online comments system; this discussion thread (together with the entire activity history on the bug) is archived with each bug, and is available to any developer who needs it. One of the package's more useful features is the ability to upload and attach a file to a bug report - very useful if, for example, you're tracking user interface bugs, because the tester reporting the bug can now simply attach a screenshot of the defective screen to the bug report.

phpBugTracker also includes a search engine, which allows developers to search the bug report archive with specific keywords, or to retrieve previous bug reports using the bug ID. Users designated as project managers can assign bugs to specific developers, and alter the status of a bug as it is analyzed and resolved. Reports containing statistics on the total number of bugs reported, resolved and under analysis can be generated on demand, and the application can even create graphs and pie charts of this data if you configure it to use the add-on JpGraph component.

One of the things I liked most about phpBugTracker is its use of templates and database abstraction. Since the entire application interface is built using the Smarty template engine, it's fairly easy to integrate it into an existing Web site, and even the colour scheme can be easily changed by editing the application's CSS rules. The use of a database abstraction layer also means that you're not restricted to using MySQL only - the application also works with PostgreSQL and Oracle 8.

If you're a developer with customers in different countries, or part of a development team that's geographically scattered, you're going to want to install phpBugTracker on your Web server, so that you have a central place to manage and share bug reports and change requests. The application is fairly easy to install and use, and is well-suited to small- and medium-size software projects with small development teams. If you've never used a tool like this before, you might think it unnecessary - but use it for a couple of projects, and you'll quickly come to appreciate its value.

Start Me Up

In order to get started with phpBugTracker, you'll need a working PHP installation (I'm currently running PHP 4.2.3), a MySQL database server (I'm running MySQL 4.0.10), and a copy of the latest release (currently version 0.9.1) of the package; you can download a copy from http://phpbt.sourceforge.net/.

Setting up the package is pretty simple. The first step is to uncompress the source archive into a directory under your Web server (mine is called "medusa" here) root.

$ cd /usr/local/apache/htdocs/

$ tar -xzvf /tmp/phpbt-0.9.1.tar.gz

This should create a directory named "phpbt-0.9.1/", which contains the following files:

-rw-r--r--    1 medusa   www          8875 Jan  5  2003 CHANGELOG
-rw-r--r--    1 medusa   www         18009 Aug  9  2001 COPYING
-rw-r--r--    1 medusa   www           636 Mar  1  2002 INSTALL
-rw-r--r--    1 medusa   www          1172 Dec 16  2001 README
-rw-r--r--    1 medusa   www           361 Apr 12  2002 TODO
-rw-r--r--    1 medusa   www           599 Oct 20  2002 UPGRADING
drwxr-xr-x    2 medusa   www          4096 Jan  5  2003 admin
-rw-r--r--    1 medusa   www          5889 May 18  2002 attachment.php
drwxrwxrwx    2 medusa   www          4096 Jan  5  2003 attachments
-rw-r--r--    1 medusa   www         24296 Oct 18  2002 bug.php
drwxrwxrwx    2 medusa   www          4096 Jan  5  2003 c_templates
-rw-r--r--    1 medusa   www          3630 Oct 14  2002 config-dist.php
-rw-rw-rw-    1 medusa   www             0 Jan  5  2003 config.php
drwxr-xr-x    4 medusa   www          4096 Jan  5  2003 docs
drwxr-xr-x    5 medusa   www          4096 Jan  5  2003 inc
-rw-r--r--    1 medusa   www          8032 Oct 18  2002 include.php
-rw-r--r--    1 medusa   www          5056 Oct 22  2002 index.php
-rw-r--r--    1 medusa   www          9091 Oct 18  2002 install.php
drwxrwxrwx    2 medusa   www          4096 Jan  5  2003 jpgimages
drwxr-xr-x    3 medusa   www          4096 Jan  5  2003 languages
-rw-r--r--    1 medusa   www          9455 Dec 23  2000 logo.gif
-rw-r--r--    1 medusa   www          1188 Apr  3  2002 logout.php
-rw-r--r--    1 medusa   www          3261 May 19  2002 newaccount.php
-rw-r--r--    1 medusa   www         11256 Sep 24  2002 query.php
-rw-r--r--    1 medusa   www          5411 May 18  2002 report.php
drwxr-xr-x    3 medusa   www          4096 Jan  5  2003 schemas
drwxr-xr-x    2 medusa   www          4096 Jan  5  2003 styles
drwxr-xr-x    3 medusa   www          4096 Jan  5  2003 templates
-rw-r--r--    1 medusa   www          6463 Jan  5  2003 upgrade.php
-rw-r--r--    1 medusa   www          4597 Jun 18  2002 user.php

You can rename the directory to something more convenient if you like.

The next step is to create a database for your phpBugTracker data. Start up the MySQL command-line client, log into the database server, and create a database named "phpbt".

$ mysql

mysql> CREATE DATABASE phpbt;
Query OK, 1 row affected (0.03 sec)

You can check that the database has been created,

mysql> SHOW DATABASES;
+------------+
| Database   |
+------------+
| mysql      |
| phpbt      |
| test       |
+------------+
3 rows in set (0.08 sec)

and then you should also create a user for the phpBugTracker application, with permission to access this database:

mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON phpbt.* TO phpbt@localhost IDENTIFIED BY 'bugbuster';
Query OK, 0 rows affected (0.00 sec)

This will create a user in the MySQL context named "phpbt" with password "bugbuster", who has full access to all tables in the "phpbt" database created earlier.

All that's left now is to create the base tables for the application, configure it to talk to the database, and set an administrator password. phpBugTracker makes all this easy to accomplish via a single-click PHP script, which performs all these tasks for you automatically.

Make sure your Web server is running, and point your browser to the index page of your phpBugTracker installation. For example, if the application was installed to the root of the Web server, you would surf to "http://medusa/phpbt-0.9.1/index.php", where you'd see something like this:

This is the initial application configuration screen, which requires you to enter basic information about your system - the type of database server, credentials for the database server, a username and password for the application administrator, the prefix for the phpBugTracker tables, and an email address for administrator notifications.

Once you've entered all the required data, submit the form, and the installation script will go to work creating the tables for you. On successful completion, you should see a screen with a success message.

You can verify that the tables have indeed been created by going back to the MySQL command line and checking for yourself.

mysql> USE phpbt;
Database changed

mysql> SHOW TABLES;
+---------------------------+
| Tables_in_phpbt           |
+---------------------------+
| phpbt_attachment          |
| phpbt_auth_group          |
| phpbt_auth_group_seq      |
| phpbt_auth_perm           |
| phpbt_auth_user           |
| phpbt_auth_user_seq       |
| phpbt_bug                 |
| phpbt_bug_cc              |
| phpbt_bug_dependency      |
| phpbt_bug_group           |
| phpbt_bug_history         |
| phpbt_bug_vote            |
| phpbt_comment             |
| phpbt_component           |
| phpbt_configuration       |
| phpbt_database_server     |
| phpbt_database_server_seq |
| phpbt_group_perm          |
| phpbt_os                  |
| phpbt_os_seq              |
| phpbt_project             |
| phpbt_project_group       |
| phpbt_resolution          |
| phpbt_resolution_seq      |
| phpbt_saved_query         |
| phpbt_severity            |
| phpbt_severity_seq        |
| phpbt_site                |
| phpbt_site_seq            |
| phpbt_status              |
| phpbt_status_seq          |
| phpbt_user_group          |
| phpbt_user_perm           |
| phpbt_user_pref           |
| phpbt_version             |
+---------------------------+
35 rows in set (0.01 sec)

While you're at the command prompt, also alter the permissions on the application's configuration file, "config.php", so that other users cannot access it.

$ chmod og-w /usr/local/apache/htdocs/phpbt-0.9.1/config.php

And you should now be done! Pop open your Web browser again, and try navigating to the application's index page again. This time, you should see a screen which looks something like this:

This is the main control interface for the phpBugTracker tool. To learn more about it, read on.

Building Blocks

Before you can begin using the application, you need to perform some basic tasks - create users and groups, define projects, and so on. phpBugTracker allows you to do these things with its easy-to-use administration module, available via the "Admin Tools" link in the menu bar. Note that you need to be logged in with appropriate permissions to view this link; if you haven't already done so, log in now using the administrator credentials created during installation.

Inside the administration module, this is what you will see.

Of the various options available, four stand out:

  1. Users: These are the users of the application - developers, testers, project managers and management.

  2. Groups: It is not uncommon to divide teams into smaller groups for smoother project management. phpBugTracker lets you do this, and also comes with pre-defined groups like "Admin", "Developer" and "User". More on this in a moment.

  3. Projects: This is where you define the projects to be tracked by the application. Important project metadata - name, description and version - is required for each project you intend to track. If the project is a large one, you can streamline things by dividing it into smaller components, or project modules.

  4. Sites: It is normal for projects to maintain two versions of the source code, one which is continuously being worked on by developers, and the other which the QA team tests against for errors. This section is where you define the staging, production and development locations for your project (you can have as many as you like per project).

Apart from the ability to manage these four entities, the administration module also allows you to change a wide range of configuration parameters, including the templates, colours and date/time display formats of the application. As you'll see shortly, as a bug winds its way through the application, it acquires a different status at each stage; these status levels, as well as the various levels of bug severity and the application's internal list of operating systems and databases, can all be modified through this administration module.

My experience suggests that the default values provided by the tool are sufficient for any small- to medium-sized project. However, if your organization is writing software for custom platforms or clients, you can always update these values to reflect reality.

Sowing The Seeds

Now that you've seen the main components of the administration module, let's use it to set up some users, groups and projects.

I'll start with the groups. In phpBugTracker, access to different projects is defined on the basis of the groups created in the application. So, it's advisable to spend some time thinking about the groups you want to create, based on the hierarchy of your organization and the software development lifecycle that you adopt for your projects.

phpBugTracker comes with three pre-defined groups: "Admin", "Developer" and "User". These groups cannot be deleted from the application. The administrative user created in the installation process is automatically added to the "Admin" and "User" groups. I'll assume now that you want to add two additional groups: "Quality Assurance (QA) Engineer" and "Project Manager".

To add a group, select "Groups" from the administration module's main menu, and then select the "Add new Group" option - a little pop-up window will open up and ask you for the name of the group. Here's what it should look like:

Enter a value, and submit the form to create the group. You may want to prefix a project code before each group if you want to create separate groups for each project.

You should now see the group in the "Groups" page.

You can always delete a group that you have created with the "Delete" link in the "Groups" administration module; the application takes care of removing all references to the group's users.

That was pretty simple, wasn't it? How about adding some users?

To add a user, select "Users" from the administration module's main menu, and then select the "Add new User" option. Again, a pop-up window will ask you for basic user details. Here's what it should look like:

There are couple of other useful flags that can be set on this screen. The "active" flag enables the user account, while the "notify" flag tells the application to send emails to that user about bugs assigned to him or her.

Remember that all users added to the "Admin" group will have access to the administration module that you are currently viewing, so you need to be careful when assigning this group to a member of your development/testing team.

Once the user has been added, you should now see the account in the "Users" main page. Notice that when you first installed the application, the administrative user account was automatically created for you.

Finally, it's time to add the project(s) you plan to use the tool for. Select "Projects" from the administration module's main menu, and then select the "Add new Project" option. You should see something like this:

Once you have provided the name, description, version and owner (usually the project manager) of the project, you can also add information about the first component of the project. Once you submit this form, you'll be directed to a new page that allows you to define which groups have access to this project. You may optionally add new versions or new components to the project.

And that's about all you need to do to get things rolling. Sure, you can make other cosmetic changes, modify bug levels and so on - but this is all you really need to do to get up and running with phpBugTracker. Next, let's look at what happens when a bug is found.

Process Flow

Before I get into the nitty-gritty of adding and resolving bugs using phpBugTracker, I'll briefly discuss the process for tracking them to closure.

  1. A Developer completes the development of his or her module, moves it to the testing area and informs the QA team that they can begin testing it.

  2. A QA Engineer starts testing the module, using the test cases prepared during the initial study of the project.

  3. If the QA Engineer discovers an error in the module, it is recorded in phpBugTracker application, together with whatever information is available to help the developer reproduce and rectify it. By default, the status of the bug is set to "Unconfirmed".

  4. A Project Manager reviews the bugs added by the QA team and assigns bugs to each developer within the phpBugTracker application. The status of the bug now changes to "Assigned".

  5. A Developer reviews the bugs assigned to him or her and takes appropriate action. Once he/she is done, the status of the bug changes to "Resolved".

  6. A Project Manager review the resolution of the bug by the Developer, changes its status to "Verify" and re-assigns it back to the QA Engineer.

  7. The QA Engineer reviews the bug and its resolution and, if satisfied, changes its status to "Closed". If the bug persists, the bug report can be re-opened by changing its status to "Re-opened". The cycle repeats until the bug achieves "Closed" status.

The above workflow is just one example that you could follow. You can always tweak the roles and responsibilities in case of smaller teams, or even skip some steps if you don't want to overburden the team with processes. Just keep the goal in mind: bug-free code. Period.

Let's look at how this workflow can be implemented in the context of phpBugTracker.

Quality Control

Now, put yourself in the shoes of a QA Engineer. You've just been informed that a new release of the code has been placed in the testing area by the development team. You load it up and start testing. Before long, you encounter a bug. After doing a little victory jig around your desk to celebrate, you point your browser to phpBugTracker, log in and select the "Add a new Bug" command to see the following screen:

You will now be asked to enter both project-related information (version, component being tested, location where you encountered the bug) and bug-related information (operating system you were using, bug summary and description). If you're a good QA Engineer, you'll make it a point to provide as much information as possible here, to simplify the development team's task - one-line descriptions will not make you any Developer friends.

While you're at it, you should also set the severity and priority of the bug. The former indicates the nature of the bug and its implication at a very broad level, while the latter is used to indicate the importance of the bug. For example, if you cannot log into the software, you cannot proceed with testing and therefore you would log the error as a high-priority bug.

Passing The Parcel

The next step in the process is probably the most crucial one, and it's usually handled by the Project Manager. Put on your Project Manager hat and log in to the application, and the first thing you should see is a list of recent bugs.

Select the bug that was recently submitted by the QA Engineer, and you'll get a page with more information.

As indicated in the process flow, in an ideal software development life cycle, it is the responsibility of a Project Manager to review the bugs entered by the QA team and verify that they actually exist. If they do, they can be assigned to the concerned developers for correction, by selecting a user from the "Assigned to" drop-down list, and updating the status of the bug to "Assigned". When such an assignment is made, the named Developer will receive email informing him about the bug and urging him to fix it as soon as possible.

Of course, there are times when over-zealous QA engineers submit bug reports which, after review, turn out not really be valid. In such situations, the Project Manager can nip the problem in the bud, by altering the status to "Closed" and flagging the "Resolution" field with the "Not a bug" message.

The Project Manager can do a number of things on the bug report page as well. For example, he or she can alter the severity and priority of the bug, add notes that will help others involved in the process, state the version of the application which resolves the bug, or attach extra documents (including screenshots) to the bug report. phpBugTracker also allows a Project Manager to create dependencies between bugs, and to link problems together so that Developers can deal with them in a systematic manner.

Busting The Bug

Once the bug has been assigned to you, a Developer, by the Project Manager, you'll get a polite email notification with the details of the bug report. You can then log into phpBugTracker to view more complete information, including the comments posted by the participants in the process - you'll see this in the form of a simple discussion forum at the bottom of the bug report.

If needed, you can even use this discussion forum to request clarification on the bug, or post messages to the QA Engineer who originally reported the bug, or to the Project Manager who assigned it to you - simply type your message into the "Description" field, and phpBugTracker will take care of emailing it to all the concerned users.

Let's assume that after several rounds of verbal discussion, allegations and counter-allegations, you fix the bug and place a new release of the source tree into the test area. You can now change the "Status" field to "Resolved", and update the "Resolution" field to "Fixed", while simultaneously assigning it to the Project Manager for further perusal.

An interesting feature in phpBugTracker is the ability to vote for a bug. It is not uncommon in open-source projects for an application to be developed by a community of developers working across geographical boundaries. In such a situation, the number of bug reports are bound to be numerous, since there's a very large audience of users downloading the software, testing it and reporting problems. This will result in a large number of bugs with very few resources available to fix them.

So what's the solution? Democracy! phpBugTracker allows users to vote for the bugs that have been entered into the application. This allows developers to prioritize bug resolution on the basis of the number of votes generated by each bug.

Final Lap

Now, you (all of you) are in the final lap. As Project Manager, you can quickly review the changes implemented by the Developer and, if happy with the resolution, you can re-assign the bug to the QA Engineer with a status of "Verified".

As QA Engineer, when you receive notification from the Project Manager, you can load up the new source and test it. If you're satisfied that the bug has been rectified, you can officially close the bug report. If you're not, and the error still persists, you can reopen the bug report. And so the cycle continues...

Question Time

When project schedules are tough, and development and testing is happening simultaneously, it is not uncommon for a phpBugTracker installation to overflow with bugs, making it hard to locate specific bug reports. This is where the search feature of the application comes in handy.

If all you want is to quickly jump to a bug report and you know the bug number, you're in luck - just enter the bug ID in the text field at the top right corner of the application, and you'll be fast-tracked to the corresponding bug report.

But if you're not so fortunate, you can try the "Query Bugs" command, available in the application's main menu. This brings up a search engine, which allows you to search the database using parameters like project name, version, component, date and current status (very useful if, for example, you want to see a list of all bugs which are "Assigned" but not yet "Resolved")

To make things more convenient, you can also save useful queries for future use - just give them a meaningful name (I have one called "Bugs that make me go ouch!") and you can re-generate the results at any time by selecting the query from your list of saved queries.

The Report Card

Why stop there? If you're looking for raw data (say, if you want to review the efficiency of your developers or your processes), phpBugTracker also offers a convenient "View Reports" command. Select it, and you'll be provided with a list of bugs across your projects, together with statistics on the number of bugs assigned to, and resolved by, each user.

Want to see the report on a per-project basis? No sweat! Just select the name of the project from the drop-down list, and the report will filter down to details for just the selected project.

Closing Time

And that brings us to the end of this tutorial. In this article, I introduced you to phpBugTracker, an open-source bug-tracking tool, and explained how you can use it to track errors in your code through different phases of the software development cycle. This article discussed the process of installing the application, setting up its database and tables, and configuring it for service. I showed you how to create projects, add users, organize them into groups, and set up testing and production locations for your projects.

Next, I discussed one possible process for bug resolution in a small- to medium-sized project, explaining how the development and QA teams might interact with each other and illustrating the role of the project manager as arbitrator and intermediary. Putting on different hats to illustrate how each role functions, I took you through the process of adding a bug to the system, reviewing it, assigning it, fixing it, verifying it and closing it. I also showed you how to use the built-in search engine to search through the phpBugTracker database for previous bug reports, and how to generate reports of bug resolution activity on your projects.

While phpBugTracker is one of the better options available, there's certainly no shortage of alternatives when it comes to Web-based bug tracking tools. In case you're looking for alternatives, you should consider visiting the following links:

Bugzilla, at http://www.bugzilla.org/

JitterBug, at http://samba.anu.edu.au/jitterbug/

PEST, at http://sourceforge.net/projects/pest/

Anthill Bug Manager, at http://anthillbm.sourceforge.net/

Bugzero, at http://www.websina.com/bugzero/

Flyspray, at http://flyspray.rocks.cc/

bugtrack, at http://www.agstools.com/bugtrack/index.html

The official Web site for phpBugTracker is http://phpbt.sourceforge.net/ Now that you've seen a preview, drop by and get yourself a copy. And once you've got it running on your site, don't forget to drop me a line and tell me all about how it helped you. Until then...stay healthy!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!

This article was first published on 28 Nov 2003.