One of the large changes for 2.16 was the templatisation of the
+ entire user-facing UI, using the
+ Template Toolkit.
+ Administrators can now configure the look and feel of Bugzilla without
+ having to edit Perl files or face the nightmare of massive merge
+ conflicts when they upgrade to a newer version in the future.
+
Templatisation also makes localised versions of Bugzilla possible,
+ for the first time. In the future, a Bugzilla installation may
+ have templates installed for multiple localisations, and select
+ which ones to use based on the user's browser language setting.
+
There are several ways to take advantage of Bugzilla's templates,
+ and which you use depends on what you want to do. The Bugzilla
+ template directory structure is that there's a top level directory,
+ template, which contains a directory for
+ each installed localisation. The default English templates are
+ therefore in en. Underneath that, there
+ are two directories - default and
+ custom. The default
+ directory contains all the templates shipped with Bugzilla.
+
One method of making customisations is to directly edit the templates
+ in template/en/default. This is probably the
+ best method for small changes, because if you then execute a
+ cvs update, any template fixes will get
+ automagically merged into your modified versions.
+
The other method is to copy the templates into
+ template/en/custom. This method is better if
+ you are going to make major changes, because it is guaranteed that
+ the contents of this directory will not be touched during an upgrade,
+ and you can then decide whether to continue using your own templates,
+ or make the effort to merge your changes into the new versions by
+ hand.
+
The syntax of the Template Toolkit language is beyond the scope of
+ this guide. It's reasonably easy to pick up by looking at the current
+ templates; or, you can read the manual, available on the
+ Template Toolkit home
+ page .
+
There are a few templates you may be particularly interested in
+ customising for your installation.
+
global/header.html.tmpl and
+ global/footer.html.tmpl:
+ These define the header and footer that go on all Bugzilla pages.
+ Editing these is a way to quickly get a distinctive look and
+ feel for your Bugzilla installation.
+
Some CGIs have the ability to use more than one template. For
+ example, buglist.cgi can output bug lists as RDF or two
+ different forms of HTML (complex and simple). (Try this out
+ by appending &format=simple to a buglist.cgi
+ URL on your Bugzilla installation.) This
+ mechanism, called template 'formats', is extensible.
+
To see if a CGI supports multiple output formats, grep the
+ CGI for "ValidateOutputFormat". If it's not present, adding
+ multiple format support isn't too hard - see how it's done in
+ other CGIs.
+
To make a new format template for a CGI which supports this,
+ open a current template for
+ that CGI and take note of the INTERFACE comment (if present.) This
+ comment defines what variables are passed into this template. If
+ there isn't one, I'm afraid you'll have to read the template and
+ the code to find out what information you get.
+
Write your template in whatever markup or text style is appropriate.
+
You now need to decide what content type you want your template
+ served as. Open up the localconfig file and find the $contenttypes
+ variable. If your content type is not there, add it. Remember
+ the three- or four-letter tag assigned to you content type.
+ This tag will be part of the template filename.
+
Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl.
+ Try out the template by calling the CGI as
+ <cginame>.cgi?format=<formatname> .
+
As well as the text-based dependency graphs, Bugzilla also
+ supports dependency graphing, using a package called 'dot'.
+ Exactly how this works is controlled by the 'webdotbase' parameter.
+
(To be written...
As long as you installed the GD and Graph::Base Perl modules you
+ might as well turn on the nifty Bugzilla bug reporting graphs.
Add a cron entry like this to run
+ collectstats.pl
+ daily at 5 after midnight:
+
|
bash#
+
+ crontab -e
+
+ |
|
5 0 * * * cd <your-bugzilla-directory> ;
+ ./collectstats.pl
+ |
+
After two days have passed you'll be able to view bug graphs from
+ the Bug Reports page.
By now you have a fully functional Bugzilla, but what good are
+ bugs if they're not annoying? To help make those bugs more annoying you
+ can set up Bugzilla's automatic whining system to complain at engineers
+ which leave their bugs in the NEW state without triaging them.
+
This can be done by
+ adding the following command as a daily crontab entry (for help on that
+ see that crontab man page):
+
|
cd <your-bugzilla-directory> ;
+ ./whineatnews.pl
+
+ |
+
![]() | Depending on your system, crontab may have several manpages.
+ The following command should lead you to the most useful page for
+ this purpose:
+
+ |
![]() | This information on using the LDAP
+ authentication options with Bugzilla is old, and the authors do
+ not know of anyone who has tested it. Approach with caution.
+ |
+
The existing authentication
+ scheme for Bugzilla uses email addresses as the primary user ID, and a
+ password to authenticate that user. All places within Bugzilla where
+ you need to deal with user ID (e.g assigning a bug) use the email
+ address. The LDAP authentication builds on top of this scheme, rather
+ than replacing it. The initial log in is done with a username and
+ password for the LDAP directory. This then fetches the email address
+ from LDAP and authenticates seamlessly in the standard Bugzilla
+ authentication scheme using this email address. If an account for this
+ address already exists in your Bugzilla system, it will log in to that
+ account. If no account for that email address exists, one is created at
+ the time of login. (In this case, Bugzilla will attempt to use the
+ "displayName" or "cn" attribute to determine the user's full name.)
+ After authentication, all other user-related tasks are still handled by
+ email address, not LDAP username. You still assign bugs by email
+ address, query on users by email address, etc.
+
Using LDAP for Bugzilla authentication requires the
+ Mozilla::LDAP (aka PerLDAP) Perl module. The
+ Mozilla::LDAP module in turn requires Netscape's Directory SDK for C.
+ After you have installed the SDK, then install the PerLDAP module.
+ Mozilla::LDAP and the Directory SDK for C are both
+ available for
+ download from mozilla.org.
+
Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP
+ directory for
+ authentication. Be very careful when setting up this parameter; if you
+ set LDAP authentication, but do not have a valid LDAP directory set up,
+ you will not be able to log back in to Bugzilla once you log out. (If
+ this happens, you can get back in by manually editing the data/params
+ file, and setting useLDAP back to 0.)
+
If using LDAP, you must set the
+ three additional parameters: Set LDAPserver to the name (and optionally
+ port) of your LDAP server. If no port is specified, it defaults to the
+ default port of 389. (e.g "ldap.mycompany.com" or
+ "ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching
+ for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids
+ must be unique under the DN specified here. Set LDAPmailattribute to
+ the name of the attribute in your LDAP directory which contains the
+ primary email address. On most directory servers available, this is
+ "mail", but you may need to change this.
+
Groups can be very useful in bugzilla, because they allow users
+ to isolate bugs or products that should only be seen by certain people.
+ Groups can also be a complicated minefield of interdependencies and
+ weirdness if mismanaged.
+
+
+ Groups only work if you enable the "usebuggroups" paramater. In
+ addition, if the "usebuggroupsentry" parameter is "On", one can
+ restrict access to products by groups, so that only members of a
+ product group are able to view bugs within that product. Group security
+ in Bugzilla can be divided into two categories: Generic and
+ Product-Based.
![]() | Groups in Bugzilla are a complicated beast that evolved out of
+ very simple user permission bitmasks, apparently itself derived from
+ common concepts in UNIX access controls. A "bitmask" is a
+ fixed-length number whose value can describe one, and only one, set
+ of states. For instance, UNIX file permissions are assigned bitmask
+ values: "execute" has a value of 1, "write" has a value of 2, and
+ "read" has a value of 4. Add them together, and a file can be read,
+ written to, and executed if it has a bitmask of "7". (This is a
+ simplified example -- anybody who knows UNIX security knows there is
+ much more to it than this. Please bear with me for the purpose of
+ this note.) The only way a bitmask scheme can work is by doubling the
+ bit count for each value. Thus if UNIX wanted to offer another file
+ permission, the next would have to be a value of 8, then the next 16,
+ the next 32, etc. Similarly, Bugzilla offers a bitmask to define group
+ permissions, with an internal limit of 64. Several are already
+ occupied by built-in permissions. The way around this limitation is
+ to avoid assigning groups to products if you have many products,
+ avoid bloating of group lists, and religiously prune irrelevant
+ groups. In reality, most installations of Bugzilla support far fewer
+ than 64 groups, so this limitation has not hit for most sites, but it
+ is on the table to be revised for Bugzilla 3.0 because it interferes
+ with the security schemes of some administrators. |
To enable Generic Group Security ("usebuggroups"):
Turn "On" "usebuggroups" in the "Edit Parameters"
+ screen.
You will generally have no groups set up. Select the "groups"
+ link in the footer.
Take a moment to understand the instructions on the "Edit
+ Groups" screen. Once you feel confident you understand what is
+ expected of you, select the "Add Group" link.
Fill out the "New Name" (remember, no spaces!), "New
+ Description", and "New User RegExp" fields. "New User RegExp"
+ allows you to automatically place all users who fulfill the Regular
+ Expression into the new group.
+
+
+ When you have finished, select the Add button.
To enable Product-Based Group Security
+ (usebuggroupsentry):
![]() | Don't forget that you only have 64 groups masks available,
+ total, for your installation of Bugzilla! If you plan on having more
+ than 50 products in your individual Bugzilla installation, and
+ require group security for your products, you should consider either
+ running multiple Bugzillas or using Generic Group Security instead of
+ Product-Based ("usebuggroupsentry") Group Security. |
Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit
+ Parameters" screen.
![]() | "usebuggroupsentry" has the capacity to prevent the
+ administrative user from directly altering bugs because of
+ conflicting group permissions. If you plan on using
+ "usebuggroupsentry", you should plan on restricting
+ administrative account usage to administrative duties only. In
+ other words, manage bugs with an unpriveleged user account, and
+ manage users, groups, Products, etc. with the administrative
+ account. |
You will generally have no Groups set up, unless you enabled
+ "usebuggroupsentry" prior to creating any Products. To create
+ "Generic Group Security" groups, follow the instructions given
+ above. To create Product-Based Group security, simply follow the
+ instructions for creating a new Product. If you need to add users
+ to these new groups as you create them, you will find the option to
+ add them to the group available under the "Edit User"
+ screens.
You may find this example illustrative for how bug groups work.
+
Example 5-7. Bugzilla Groups
Bugzilla Groups example ----------------------- For
+ this example, let us suppose we have four groups, call them Group1,
+ Group2, Group3, and Group4. We have 5 users, User1, User2, User3,
+ User4, User5. We have 8 bugs, Bug1, ..., Bug8. Group membership is
+ defined by this chart: (X denotes that user is in that group.) (I
+ apologize for the nasty formatting of this table. Try viewing it in a
+ text-based browser or something for now. -MPB) G G G G r r r r o o o
+ o u u u u p p p p 1 2 3 4 +-+-+-+-+ User1|X| | | | +-+-+-+-+ User2|
+ |X| | | +-+-+-+-+ User3|X| |X| | +-+-+-+-+ User4|X|X|X| | +-+-+-+-+
+ User5| | | | | +-+-+-+-+ Bug restrictions are defined by this chart:
+ (X denotes that bug is restricted to that group.) G G G G r r r r o o
+ o o u u u u p p p p 1 2 3 4 +-+-+-+-+ Bug1| | | | | +-+-+-+-+ Bug2|
+ |X| | | +-+-+-+-+ Bug3| | |X| | +-+-+-+-+ Bug4| | | |X| +-+-+-+-+
+ Bug5|X|X| | | +-+-+-+-+ Bug6|X| |X| | +-+-+-+-+ Bug7|X|X|X| |
+ +-+-+-+-+ Bug8|X|X|X|X| +-+-+-+-+ Who can see each bug? Bug1 has no
+ group restrictions. Therefore, Bug1 can be seen by any user, whatever
+ their group membership. This is going to be the only bug that User5
+ can see, because User5 isn't in any groups. Bug2 can be seen by
+ anyone in Group2, that is User2 and User4. Bug3 can be seen by anyone
+ in Group3, that is User3 and User4. Bug4 can be seen by anyone in
+ Group4. Nobody is in Group4, so none of these users can see Bug4.
+ Bug5 can be seen by anyone who is in _both_ Group1 and Group2. This
+ is only User4. User1 cannot see it because he is not in Group2, and
+ User2 cannot see it because she is not in Group1. Bug6 can be seen by
+ anyone who is in both Group1 and Group3. This would include User3 and
+ User4. Similar to Bug5, User1 cannot see Bug6 because he is not in
+ Group3. Bug7 can be seen by anyone who is in Group1, Group2, and
+ Group3. This is only User4. All of the others are missing at least
+ one of those group privileges, and thus cannot see the bug. Bug8 can
+ be seen by anyone who is in Group1, Group2, Group3, and Group4. There
+ is nobody in all four of these groups, so nobody can see Bug8. It
+ doesn't matter that User4 is in Group1, Group2, and Group3, since he
+ isn't in Group4.
+
This section distills some Bugzilla tips and best practices
+ that have been developed.
Bugzilla comments are plain text - so posting HTML will result
+ in literal HTML tags rather than being interpreted by a browser.
+ However, Bugzilla will automatically make hyperlinks out of certain
+ sorts of text in comments. For example, the text
+ http://www.bugzilla.org will be turned into
+ http://www.bugzilla.org.
+ Other strings which get linkified in the obvious manner are:
+
| bug 12345 |
| bug 23456, comment 53 |
| attachment 4321 |
| mailto:george@example.com |
| ftp://ftp.mozilla.org |
| Most other sorts of URL |
+
A corollary here is that if you type a bug number in a comment,
+ you should put the word "bug" before it, so it gets autolinkified
+ for the convenience of others.
+
Quicksearch is a single-text-box query tool which uses
+ metacharacters to indicate what is to be searched. For example, typing
+ "foo|bar" into Quicksearch would search for "foo" or "bar" in the
+ summary and status whiteboard of a bug; adding ":BazProduct" would
+ search only in that product.
+
You'll find the Quicksearch box on Bugzilla's
+ front page, along with a
+ Help
+ link which details how to use it.
If you are changing the fields on a bug, only comment if
+ either you have something pertinent to say, or Bugzilla requires it.
+ Otherwise, you may spam people unnecessarily with bug mail.
+ To take an example: a user sets up their account to filter out messages
+ where someone just adds themselves to the CC field of a bug
+ (which happens a lot.) If you come along, add yourself to the CC field,
+ and add a comment saying "Adding self to CC", then that person
+ gets a pointless piece of mail they would otherwise have avoided.
+
Don't use sigs in comments. Signing your name ("Bill") is acceptable,
+ particularly if you do it out of habit, but full mail/news-style
+ four line ASCII art creations are not.
+
Use attachments, rather than comments, for large chunks of ASCII data,
+ such as trace, debugging output files, or log files. That way, it doesn't
+ bloat the bug for everyone who wants to read it, and cause people to
+ receive fat, useless mails.
+
Trim screenshots. There's no need to show the whole screen if
+ you are pointing out a single-pixel problem.
+
Don't attach simple test cases (e.g. one html file and one
+ css file and one image) as a ZIP file. Instead, upload them in
+ reverse order and edit the referring file so that they point to the
+ attached files. This way, the test case works immediately
+ out of the bug.
+
Try to make sure that everything said in the summary is also
+ said in the first comment. Summaries are often updated and this will
+ ensure your original information is easily accessible.
+
You do not need to put "any" or similar strings in the URL field.
+ If there is no specific URL associated with the bug, leave this
+ field blank.
+
If you feel a bug you filed was incorrectly marked as a
+ DUPLICATE of another, please question it in your bug, not
+ the bug it was duped to. Feel free to CC the person who duped it
+ if they are not already CCed.
+
This section gives solutions to common Bugzilla installation
+ problems.
+
The following error message may appear due to a bug in DBD::mysql
+ (over which the Bugzilla team have no control):
+
"DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
+ SV = NULL(0x0) at 0x20fc444
+ REFCNT = 1
+ FLAGS = (PADBUSY,PADMY)"
+ |
To fix this, go to <path-to-perl>/lib/DBD/sponge.pm in your Perl
+ installation and replace
+
my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAME'}) {
+ $numFields = @{$attribs->{NAME}};
+ |
by
+
my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAMES'}) {
+ $numFields = @{$attribs->{NAMES}};
+ |
(note the S added to NAME.)
+
If you are installing Bugzilla on SuSE Linux, or some other
+ distributions with
+ "paranoid"
+ security options, it is possible that the checksetup.pl script may fail
+ with the error:
+
cannot chdir(/var/spool/mqueue): Permission denied
+ |
+
This is because your
+ /var/spool/mqueue
+ directory has a mode of
+ "drwx------". Type
+ chmod 755
+ /var/spool/mqueue
+
+ as root to fix this problem.
+
Once you have logged in, you can customise various aspects of
+ Bugzilla via the "Edit prefs" link in the page footer.
+ The preferences are split into four tabs:
On this tab, you can change your basic account information,
+ including your password, email address and real name. For security
+ reasons, in order to change anything on this page you must type your
+ current
+ password into the
+ "Password"
+ field at the top of the page.
+ If you attempt to change your email address, a confirmation
+ email is sent to both the old and new addresses, with a link to use to
+ confirm the change. This helps to prevent account hijacking.
On this tab you can reduce or increase the amount of email sent
+ you from Bugzilla, opting in our out depending on your relationship to
+ the bug and the change that was made to it. (Note that you can also do
+ client-side filtering using the X-Bugzilla-Reason header which Bugzilla
+ adds to all bugmail.)
By entering user email names, delineated by commas, into the
+ "Users to watch" text entry box you can receive a copy of all the
+ bugmail of other users (security settings permitting.) This powerful
+ functionality enables seamless transitions as developers change
+ projects, managers wish to get in touch with the issues faced by their
+ direct reports, or users go on vacation.
![]() | The ability to watch other users may not be available in all
+ Bugzilla installations. If you can't see it, ask your
+ administrator. |
On the Search page, you can store queries in Bugzilla, so if you
+ regularly run a particular query it is just a drop-down menu away.
+ Once you have a stored query, you can come
+ here to request that it also be displayed in your page footer.
This is a purely informative page which outlines your current
+ permissions on this installation of Bugzilla - what product groups you
+ are in, and whether you can edit bugs or perform various administration
+ functions.
The concept of "voting" is a poorly understood, yet powerful
+ feature for the management of open-source projects. Each user is
+ assigned so many Votes per product, which they can freely reassign (or
+ assign multiple votes to a single bug). This allows developers to gauge
+ user need for a particular enhancement or bugfix. By allowing bugs with
+ a certain number of votes to automatically move from "UNCONFIRMED" to
+ "NEW", users of the bug system can help high-priority bugs garner
+ attention so they don't sit for a long time awaiting triage.
The daunting challenge of Votes is deciding where you draw the
+ line for a "vocal majority". If you only have a user base of 100 users,
+ setting a low threshold for bugs to move from UNCONFIRMED to NEW makes
+ sense. As the Bugzilla user base expands, however, these thresholds
+ must be re-evaluated. You should gauge whether this feature is worth
+ the time and close monitoring involved, and perhaps forego
+ implementation until you have a critical mass of users who demand
+ it.
To modify Voting settings:
Navigate to the "Edit product" screen for the Product you
+ wish to modify
Set "Maximum Votes per person" to your calculated value.
+ Setting this field to "0" disables voting.
Set "Maximum Votes a person can put on a single bug" to your
+ calculated value. It should probably be some number lower than the
+ "Maximum votes per person". Setting this field to "0" disables
+ voting, but leaves the voting options open to the user. This is
+ confusing.
Set "Number of votes a bug in this product needs to
+ automatically get out of the UNCONFIRMED state" to your calculated
+ number. Setting this field to "0" disables the automatic move of
+ bugs from UNCONFIRMED to NEW. Some people advocate leaving this at
+ "0", but of what use are Votes if your Bugzilla user base is unable
+ to affect which bugs appear on Development radar?
+
![]() | You should probably set this number to higher than a small
+ coalition of Bugzilla users can influence it. Most sites use this
+ as a "referendum" mechanism -- if users are able to vote a bug
+ out of UNCONFIRMED, it is a
+ really
+
+ bad bug! |
Once you have adjusted the values to your preference, select
+ the "Update" button.