May 27, 2011

Weekend Project: Manage Bugs with Mantis

All kinds of organizations need bug trackers. Whether it's software developers, Web site developers, or just organizations with significant IT needs, bugs must be tracked. (And, you know, fixed.) To that end, there are plenty of bug tracking tools available, but none that are open source and as easy to install and manage as Mantis Bug Tracker. This weekend, get started tracking bugs with Mantis!

Since the installation of Mantis is such an easy (and well documented) task, I want to focus on the management and flow of the work done within the tool. This means managing projects as well as reporting and managing the flow of reported bugs. The only assumption made will be that Mantis is already up and running.

Managing Projects

Before bugs can be reported, there must be a project to report bugs on. In order to manage projects log into Mantis as the administrative user and then click on the Manage link. From this new page (see Figure 1), click on the Manage Projects link.

Figure 1

Obviously, all Mantis management is tackled from this page, so make sure whoever has the key to this kingdom knows what they are doing — or should, anyway.

From within the Manage Projects page all that is necessary is to click the Create New Project button. From within the new page, the following information is necessary:

  • Project Name: Human Readable name for project. This is the only field that is required.
  • Status: Choose from development, release, stable, obsolete.
  • View Status: Choose from public or private.
  • Inherit Global Categories: On or off.
  • Upload File Path: Path for file upload. This path must be readable and writable by the web server and does not (nor should) need to be within the document root or the Mantis directory.
  • Description: Human readable description of project.

Below the Description there are other fields that can be filled out. Per-project categories can be created on this page. Per-project categories are very important and useful to make the flow of bugs easier to follow. Getting as granular as possible in the categorization will not only make it easier for developers and admins to follow the flow of information, it will also make it much easier for reporters to report bugs (and be more specific when doing so.) Use this only if there will be categories that are only related to this particular project. The main categories are global and can be used by all projects.

There is one small hiccup with creating the categories at this point. When a category is created, it's always smart to assign that category to a user. But if no users have been created, this isn't possible. To really make the most out of the system, each category should be assigned a lead so all notifications can be funneled to the proper person. So, instead of creating Categories next, migrate over to users and create the users that will serve as the heads of the various categories. Don't worry, the project can be modified later, after users have been created. Naturally, this won't be necessary on a Mantis installation that already contains the necessary users.

Managing Users

The managing of users is a fairly straight-forward task, but it's one that's quite important. When users are created they are assigned an access level which dictates their effective permissions within Mantis. So, it should go without saying, to pay close attention to the access level of a new user. To create said new user click on (from the Mantis home page) Manage > Manage Users. From the Manage Users page, click the Create New Account button and fill out the necessary information:

  • Username: The username the user will log in with.
  • Real Name: The human readable name of the user.
  • E-mail: E-mail address for the user.
  • Access Level: Choose from viewer, reporter, updater, developer, manager, or administrator.
  • Enabled: Check to enable to user. Uncheck to temporarily disable the user.
  • Protected: When an account is protected its attributes can not be changed.

With the users created, now it's possible to assign categories to those users to further refine how Mantis is used.

Global Categories

Go back to the Manage Projects page. From this page it is possible to create Global Categories. As mentioned earlier, Global Categories are available to all projects, so do not create categories here that relate to a specific project. To create a category simply type the category name in the field to the left of the Add Category button and click Add Category. This will add the category, but will not assign the category to a user. In order to assign a category to a user click the Edit button associated with the category, which will open that category up for editing (see Figure 2).

Figure 2

At this point the category name can also be changed.

To assign the category to a user, just select the user from the drop-down and then click Update Category. With the project, categories, and users created it is now possible for users to report bugs against the project.

Configuring Email Notifications

As crucial as categories are to the ability for reports and manages to work the flow of information, email alerts are, without a doubt, the single most important feature of Mantis for quick response to issues. These alerts make those who need to know aware when bugs are reported and/or have status changes. This feature, of course, requires a working SMTP server configured in the config_inc.php configuration file. With that in place, do the following:

  1. Go to the Mantis main page.
  2. Click on the Manage link.
  3. Click on the Manage Configuration link.
  4. Click on the E-mail Notifications link.
  5. Configure Access Levels for each user type (See Figure 3.)
  6. Click Update Configuration.

Figure 3Settings highlighted in green override all others. Settings in blue are project-specific.

Flow Of Bugs

The flow of bug tracking can range from the fairly simple to the very complex. This will be dictated on how detailed bugs become, how frequent bugs are reported, and how granularly those bugs are managed. Regardless of how complex your bug reporting can get, this is how Mantis manages the flow of bugs:

  1. User logs onto Mantis site.
  2. User reports issue for a particular project, making sure to select either a Global or Project-specific category.
  3. Notification is sent to Project Manager (or whoever is configured to receive notifications.)
  4. Manager (or administrator) of project confirms bug and assigns bug to developer.
  5. Developer resolves bug and sets bug status to resolved.
  6. Manager (or administrator) can then close bug when resolution is confirmed.

As is shown in Figure 4, it is very easy to access quite a large amount of information about a bug. Each blue link is clickable and will reveal different aspects about an individual but, a category, a user, a project, and more.

Figure 4

In this example there are two projects with a bug attached, Mobuntu and WidgetOne.

A user with the correct permissions could click on any of the listed bugs and view, edit, promote, demote, assign, and much more. Bugs can even have their status changed in batches by checking off all the bugs to be changed and then selecting the new status from the drop-down (below the bug listing window). Once the new status is selected, click the OK button to update. Depending the change, a new window may be opened for user interaction (such as with an assigning of bugs.)

Make It Work For You

Different companies will use Mantis differently. Some will be able to function with just the very basics, whereas others will depend upon a highly detailed usage. Regardless of how it is used, it is important to know that Mantis Bug Tracker offers numerous ways to manage the flow of bugs in and out of the system.

Click Here!