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:
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:


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:
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:


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:
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:
comments.html.tmpl
This template displays the ticket's comments. Changes to this template fairly minor, and include:


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:


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:


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:


Global templates

banner.html.tmpl
This template is the Bugzilla banner, used by many forms. Changes to this template are fairly minor, and include:
field-descs.none.tmpl
This template sets the description used by various lists. Changes to this template are fairly minor, and include:
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:
variables.none.tmpl
This template is quite useful, allowing you to change many common terms without having to edit a bunch of template files.


List templates

edit-multiple.html.tmpl
This template is used when changing multiple tickets. Changes to this template are fairly minor, and include:
list.html.tmpl
This template is used for many of Bugzilla's lists. Changes to this template are fairly minor, and include:
table.html.tmpl
This template controls the column headers and width of Bugzilla lists. Changes to this template are fairly minor, and include:


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:
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:


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:


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:
process_bug.cgi
As the name would indicate, this Perl script processes changes to tickets (bugs). Changes to this script are minor, and include:
checksetup.pl
This script checks for necessary software & Perl modules, compiles templates, etc. Changes to this script are fairly minor, and include:
localconfig
This file holds some local configuration variables for Bugzilla. Changes to this file are fairly minor, and include:
BugMail.pm
This script generates e-mail notifications for new and changed tickets. Changes to this script are fairly minor, and include:
Config.pm
This file contains Bugzilla system variables and other configuration information. Changes to this script are fairly minor, and include: