Bugzilla at the Westminster Public Library

This page last updated: October 21, 2008

What is Bugzilla and why did we customize it?: Bugzilla is an industrial-strength bug tracking system. Bug tracking systems allow developers to keep track of outstanding bugs in their products effectively. Most commercial defect-tracking software is expensive. Despite being "free", Bugzilla has many features its expensive counterparts lack. Consequently, it has quickly become a favorite of hundreds of organizations across the globe. As of September 2006, 571 known companies and organizations worldwide use Bugzilla, including: Mozilla (Netscape & Mozilla browsers), Linux kernel developers, NASA and Id Software. Once we had decided on Bugzilla, our first thought was, "Wow, Bugzilla really has a lot of fields to be filled in. There's no way staff will use it in out-of-the-can form." Bugzilla has a lot of features and we knew that we wouldn't need many of them. We didn't want to mandate a new method for requesting IT support that was so complex no one would use it. Although some might argue that we removed too many features in our quest to simplify Bugzilla for our needs, others may find it a good place to start. Since no changes have been made to the underlying database or default templates, adding additional features back in shouldn't be that difficult. For more information about Bugzilla at the library, click here.

Configuring products, components & versions:: As with any database, initial configuration goes a long way toward determining the overall usefulness of the product. Making good decisions at the beginning will generally increase the products usefulness, lifespan and overall user satisfaction. Bad decisions often make you wish you'd never installed the product to begin with! Bugzilla uses products, groups and versions to categorize tickets. We began by writing down all the different types of requests we'd received and then grouping them by similarity. From this we created a number of products and then added components. We only use versions for a few major products: Horizon (library software) and Horizon Information Portal (the online catalog). Most products are visible to all staff, but a few are for internal use by Automation Services. We periodically review existing products & components to see if anything new should be added or merged. Some of our current products & components are:

Horizon (our integrated library system):
- Cataloging
- Circulation
- Searching
Computers:
- Staff
- Public
- Network printers
Network services:
- Bugzilla
- E-mail
- File storage
- Internet connectivity
Don't Panic!:
- Use this when you don't know how to categorize the ticket. We attempt to categorize these if possible, adding a new product/component if necessary.

Adding & removing custom templates:: Bugzilla is designed with customization in mind, so adding a custom template is as easy as dropping the template file in the proper directory and running the checksetup.pl script. To return to the default template, remove or rename the file and run checksetup.pl again. NOTE: Running checksetup.pl will disrupt Bugzilla's operation, but on most systems it shouldn't take long to run - typically less than 20 seconds for our installation. Symptoms that checksetup.pl is running or needs to be run include incomprehensible error messages and the inability to post updates - add a ticket, search for tickets, modify an existing ticket, etc. For staff attempting to load a page or add/update a ticket, reloading the page or using the browser's back button and resubmitting the ticket should solve the problem. Changes take effect once checksetup.pl has completed successfully, no restart of Apache or rebooting of the server is necessary.

Default & custom template directory structure:: The base directory for default templates is '[path-to-bugzilla-install]/template/en/default/'. For Linux installations running only Bugzilla, this is typically '[webserver-document-root]/template/en/default/'. The base directory for custom templates is '[path-to-bugzilla-install]/template/en/custom/'. For Linux installations running only Bugzilla, this is typically '[webserver-document-root]/template/en/custom/'. The file & directory structure must mirror the default template directory structure in order for Bugzilla to use custom templates, so you'll need to create the 'custom' directory and other directories as necessary. Be sure to set ownership & permissions correctly or Bugzilla may have trouble reading the template files.

Using custom Perl modules & scripts:: The base directory for Perl modules & scripts is '[path-to-bugzilla-install]/'. For Linux installations running only Bugzilla, this is typically '[webserver-document-root]'. Before replacing the original files with our customized versions, please make a backup copy! Be sure to set ownership & permissions correctly or Bugzilla may have trouble reading / executing the Perl scripts. Changes take effect once checksetup.pl has completed successfully, no restart of Apache or rebooting of the server is necessary.

Tested versions:: These customizations have been tested with the Bugzilla 2.18.x tree, specifically 2.18.3 and 2.18.4. Future releases within the 2.18.x tree will be tested and updated as necessary. Releases newer than 2.18 will be tested when we feel the need to upgrade.

Modifications to Bugzilla's MySQL database:: NO changes have been made to Bugzilla's underlying database, so upgrading Bugzilla shouldn't present a problem. This also means if you later decide to add a field back to the forms, the necessary program logic and database field(s) are still available.

Upgrading via CVS: Upgrading via the CVS (Concurrent Version System) method is recommended. Custom templates are unaffected and CVS has been able to successfuly merge changes to Perl modules & scripts thus far. See the Bugzilla documentation for details about upgrading via CVS and other means. Always, always, always backup your Bugzilla directory and database before upgrading!

Availability of custom templates & other files:: Our customized templates & other files are freely available, but we'd like to hear from you, so send an e-mail to Eric Sisler (esisler@cityofwestminster.us) and we'll set you up with access to the download area. Thanks!

Standard disclaimer:: Although Bugzilla has been tested & used extensively at our site without issue, no warranty or suitability for your environment is guaranteed, implied or hinted at - you decide for yourself! ;-)

Bugzilla homepage templates

[Default page] | [WPL customized page]

index.html.tmpl: This template controls the main Bugzilla index page. Changes to this template are pretty minor, and include:

Add wording for the library environment. Default wording is designed to be customized, we wanted it to indicate the use of Bugzilla for reporting problems and entering general work requests.
Add link to Automation Services pager guidelines. You will want to remove this link or point it at your own pager guidelines.
Add link to revised ticket writing guidelines.
Remove ugly "Godzilla-ed" ant picture!

New ticket form templates

[Default page] | [WPL customized page]

create.html.tmpl: This template controls the form to submit a new ticket. Changes to this template are fairly significant, and include:

Remove unused fields & reorganize remaining form elements. This greatly simplifies ticket entry, as there are only two drop-down fields, two required fields and one optional field.
Change "Severity" label to "Ticket Type". Severity & Priority seemed redundant for our purposes, so we decided to make better use of the severity field.
Change "Reporter" value from account name (e-mail address) to real name.
Remove "Assign To" field. Tickets are initially assigned to a generic account for notification purposes, Automation Services staff determine who will take the ticket.
Remove link to description of component field.
Add link to staff e-mail group information pages.
Add "NOTE: Separate e-mail addresses with a space." under "Add CC:" box.
Remove checkbox to make the initial description private.
Remove dependency/blocks section.
Change label of "Commit" button to "Continue".
Remove "Remember values as bookmarkable template" button.
Send new ticket e-mail notification to a generic account, Automation Services staff determine who will take the ticket.
Add code to set required fields not included on the form.

user-message.html.tmpl: This template controls the user message at the top of a new ticket. Changes to this template are fairly minor, and include:

Update "ticket writing guidelines" link to open in a new browser.
Remove link to the most frequently reported tickets. This link searches for tickets reported in a short time-frame that are marked as duplicates, which doesn't happen at WPL very often.

Edit ticket form templates

[Default page] | [WPL customized page]

edit.html.tmpl: This template controls the form to update an existing ticket. Changes to this template are fairly significant, and include:

Remove unused fields & reorganize remaining form elements.
Remove link to current ticket, which seems redundant.
Add "Opened:" and "Updated:" fields.
Change "Severity" label to "Ticket Type".
Change "Reporter" & "Assigned To" values from e-mail address & real name to real name only.
Add link to staff e-mail group information pages.
Add "NOTE: Separate e-mail addresses with a space." under "Add CC:" box.
The "Priority" field is only available to members of the "admin" group. Regular staff may not change a ticket's priority.
Remove dependency/blocks section.
Move "Additional Comments" section to bottom of form, which seemed a more logical place for it.
Remove "Users in the roles selected below..." section & set boxes to checked.
Add an additional "Commit" button after the "Additional Comments" box to make updating tickets easier.

knob.html.tmpl: This template controls the "knobs" to assign a ticket, change a ticket's status, etc. Although changes to the template are minor, this set of controls is only available to members of the "admin" group. Regular staff are not allowed to assign tickets, change a ticket's status, etc. Specific changes include:

Display controls only to members of the "admin" group.
Display "View Ticket Activity" and "Format For Printing" links only to members of the "admin" group.
Change "Reassign ticket to" from a blank fill-in-the-box to a drop-down with Automation Services staff member's names.

comments.html.tmpl: This template displays the ticket's comments. Changes to this template fairly minor, and include:

Remove [reply] link from comments section. This link creates a new comment which includes quoted text from the original comment. We found this hard to read in some cases, and since Bugzilla displays all the comments in order, unnecessary. Some staff were also confused about whether to use the [reply] link or the "Additional Comments" box.
Remove mailto link from commenter name. The whole idea of Bugzilla is for staff to add their comments to the ticket for all to see, not send private e-mail.
Remove "Opened:" field from initial description, since opened & updated fields are at the top of the ticket.

New attachment templates

create.html.tmpl: This template controls the form to add an attachment to a ticket. Changes to this template are fairly minor, and include:

Remove the "patch" type attachment, since we're not using patches in the Bugzilla sense of the word.
Remove the radio button to choose the attachment type, always use autodetect. Bugzilla is pretty good at automatically detecting attachment types, and most staff won't know what to put here anyway. The attachment type can be changed later if necessary.
Remove the "Reassignment" checkbox that allows the user to assign the ticket to themself. Only Automation Services staff may assign tickets.

Edit attachment templates

edit.html.tmpl: This template controls the form to edit an existing attachment to a ticket. Changes to this template are fairly minor, and include:

Remove the "patch" type attachment, since we're not using patches in the Bugzilla sense of the word.
Remove the radio button to choose the attachment type, always use autodetect. Bugzilla is pretty good at automatically detecting attachment types, and most staff won't know what to put here anyway. The attachment type can be changed later if necessary.

List attachment templates

list.html.tmpl: This template is actually used by the Edit ticket form, which shows existing attachments and a link to add a new attachment. Changes to this template are fairly minor, and include:

Change the wording after "Create a New Attachment" from "proposed patch, testcase, etc." to "screenshot, document, sample, etc.".

Global templates

banner.html.tmpl: This template is the Bugzilla banner, used by many forms. Changes to this template are fairly minor, and include:

Remove "This is" before the term for Bugzilla.

field-descs.none.tmpl: This template sets the description used by various lists. Changes to this template are fairly minor, and include:

Change the description for bug_severity from "Severity" to "Ticket Type", as we are using this field for a somewhat different purpose.

useful-links.html.tmpl: This template controls the navigation box appearing at the bottom of most Bugzilla pages. Changes to this template are fairly minor, and include:

Remove the "My Requests" link. A pre-defined "My Tickets" link is provided which includes tickets entered by the user and tickets where the user is on the cc: list.
Remove the "Reports" link for regular users. Only Automation Services staff may view reports.

variables.none.tmpl: This template is quite useful, allowing you to change many common terms without having to edit a bunch of template files.

Change all forms of "bug" to "ticket". Unfortunately this does NOT change Bugzilla's auto-linkification feature, which automatically creates a URL for "ticket 5" or "ticket 18, comment 3" within comments. This is controlled by the globals.pl Perl script (discussed later).
Change "Bugzilla" to "Automation Services Bugzilla".

List templates

edit-multiple.html.tmpl: This template is used when changing multiple tickets. Changes to this template are fairly minor, and include:

Change "Reassign to" from a blank fill-in-the-box to a drop-down with Automation Services staff member's names.

list.html.tmpl: This template is used for many of Bugzilla's lists. Changes to this template are fairly minor, and include:

Remove display of long format & other options (CSV, iCalendar, etc.) for regular staff.

table.html.tmpl: This template controls the column headers and width of Bugzilla lists. Changes to this template are fairly minor, and include:

Change label of the bug_severity field from "Sev" to "Type" as we are using it for a different purpose.

Pages templates

[Default page] | [WPL customized page]

bug-writing.html.tmpl: This template is the ticket writing guidelines page. This template was completely re-written for use at the library, and changes include:

Open the guidelines in a new browser.
See the above samples for details.

group-email.html.tmpl: This template was added to Bugzilla and a link to it is included on pages where the cc: list box appears. It opens in a new browser window and includes:

E-mail address basics (e-mail address for the City & College differ.)
Staff e-mail groups in an easy to copy & paste format.
To call this page or any other page you wish to add to Bugzilla, simply pass the page name as an argument to the page.cgi script in a normal HTML "a href" tag like so:
```
<a href="page.cgi?id=[PAGENAME].html" target="_blank">[LINK TEXT]</a>

<a href="page.cgi?id=group-email.html" target="_blank">
Click here for staff group e-mail information</a>
```
Since Bugzilla templates are a combination of HTML and text processed by template toolkit, it is necessary to use blockquote tags. See this template or the ticket writing template for syntax examples. The target="_blank" option causes the page to load in a new browser window for easy copy & paste.

Search templates

[Default page] | [WPL customized page]

form.html.tmpl: This template controls the "Find a Specific Ticket" and "Advanced Search" pages. Changes to this template are fairly minor, and include:

Remove accesskey controls, which allow the use of "Alt+[key]" to move between form elements.
Remove link to description of component field.
Remove unused fields, including URL, Hardware & OS.
Change "Severity" label to "Type".

Perl scripts & other files

globals.pl: This Perl script contains some global variables and routines used throughout Bugzilla. Changes to this script are minor, and include:

Change "bug" to "ticket" in the phrase "This bug has been marked as a duplicate..."
Change "bug" to "ticket" in the section of code that handles Bugzilla's auto-linkification feature, which automatically creates a URL for text like "ticket 5" or "ticket 18, comment 3" within comments.
Please see the Using custom Perl scripts and Upgrading via CVS sections before installing this script!

process_bug.cgi: As the name would indicate, this Perl script processes changes to tickets (bugs). Changes to this script are minor, and include:

Change "bug" to "ticket" to provide correct terminology.
Please see the Using custom Perl scripts and Upgrading via CVS sections before installing this script!

checksetup.pl: This script checks for necessary software & Perl modules, compiles templates, etc. Changes to this script are fairly minor, and include:

Add custom resolutions 'CANTFIX', 'FRCCIT'.
Remove default resolutions 'INVALID', 'LATER', 'REMIND' & 'WORKSFORME'.
To avoid possible database consistency problems, please make sure no tickets are using a resolution before deleting it.
Please see the Using custom Perl scripts and Upgrading via CVS sections before installing this script!

localconfig: This file holds some local configuration variables for Bugzilla. Changes to this file are fairly minor, and include:

Add custom severities (used as ticket type) "Fix Me! (bug)", "Request" & "Information".
Remove default severities "blocker", "critical", "major", "normal", "minor", "trivial" & "enhancement".
Add custom priorities "1-Critical (pager)", "2-High", "3-Medium", "4-Low" & "5-Ultralow".
Remove default priorities "P1", "P2", "P3", "P4", "P5"
Add custom operating system "unspecified".
Remove all default operating systems.
Add custom platform "unspecified".
Remove all default platforms.

BugMail.pm: This script generates e-mail notifications for new and changed tickets. Changes to this script are fairly minor, and include:

Change "bug" to "ticket" to provide correct terminology.
Please see the Using custom Perl scripts and Upgrading via CVS sections before installing this script!

Config.pm: This file contains Bugzilla system variables and other configuration information. Changes to this script are fairly minor, and include:

Add "(Customized by WPL)" to the Bugzilla version, including a link to this page.
IMPORTANT: If you use this template or modify the "$Bugzilla::Config::VERSION" variable for your environment, CVS will issue a warning when merging this file because the line has already been modified. This is easy to fix but must be fixed or checksetup.pl will throw an error. CVS will mark the section of the file it was unable to merge like so:
```
     <<<<<<< Config.pm
     $Bugzilla::Config::VERSION = "2.18.3 (Customized by WPL)";
     =======
     $Bugzilla::Config::VERSION = "2.18.4";
     >>>>>>> 1.21.2.9
```
Lines between "<<<<<<< Config.pm" and "=======" were already in the file, lines between "=======" and ">>>>>>> [file version]" are lines added by the CVS upgrade. To fix the CVS merge conflict, remove the CVS notation lines, the "extra" version line and modify the remaining version line for your environment:
```
     $Bugzilla::Config::VERSION = "2.18.4 (Customized by WPL)";
```
Run checksetup.pl and you're done!