From 11945a73c631bedbcf8daaba531964c3fc2d6333 Mon Sep 17 00:00:00 2001 From: "justdave%syndicomm.com" <> Date: Thu, 5 Feb 2004 12:49:08 +0000 Subject: - Remove html, txt, and pdf directories from CVS - makedocs.pl now creates said directories when building the docs The idea here is that it's useless to have compiled stuff in CVS. The website will now auto-build the docs upon changes to the xml directory. --- docs/txt/Bugzilla-Guide.txt | 4520 ------------------------------------------- 1 file changed, 4520 deletions(-) delete mode 100644 docs/txt/Bugzilla-Guide.txt (limited to 'docs/txt/Bugzilla-Guide.txt') diff --git a/docs/txt/Bugzilla-Guide.txt b/docs/txt/Bugzilla-Guide.txt deleted file mode 100644 index 4453224ee..000000000 --- a/docs/txt/Bugzilla-Guide.txt +++ /dev/null @@ -1,4520 +0,0 @@ - -The Bugzilla Guide - 2.17.7 Development Release - -The Bugzilla Team - - 2004-01-24 - - This is the documentation for Bugzilla, a bug-tracking system from - mozilla.org. Bugzilla is an enterprise-class piece of software that - tracks millions of bugs and issues for hundreds of organizations - around the world. - - The most current version of this document can always be found on the - Bugzilla Documentation Page. - _________________________________________________________________ - - Table of Contents - 1. About This Guide - - 1.1. Copyright Information - 1.2. Disclaimer - 1.3. New Versions - 1.4. Credits - 1.5. Document Conventions - - 2. Installing Bugzilla - - 2.1. Installation - 2.2. Configuration - 2.3. Optional Additional Configuration - 2.4. OS-Specific Installation Notes - 2.5. Troubleshooting - - 3. Administering Bugzilla - - 3.1. Bugzilla Configuration - 3.2. User Administration - 3.3. Products - 3.4. Components - 3.5. Versions - 3.6. Milestones - 3.7. Voting - 3.8. Groups and Group Security - 3.9. Upgrading to New Releases - - 4. Customising Bugzilla - - 4.1. Template Customization - 4.2. Template Hooks - 4.3. Customizing Who Can Change What - 4.4. Modifying Your Running System - 4.5. MySQL Bugzilla Database Introduction - 4.6. Integrating Bugzilla with Third-Party Tools - - 5. Using Bugzilla - - 5.1. Introduction - 5.2. Create a Bugzilla Account - 5.3. Anatomy of a Bug - 5.4. Searching for Bugs - 5.5. Bug Lists - 5.6. Filing Bugs - 5.7. Patch Viewer - 5.8. Hints and Tips - 5.9. User Preferences - 5.10. Reports - - A. The Bugzilla FAQ - B. Contrib - - B.1. Command-line Search Interface - - C. Manual Installation of Perl Modules - - C.1. Instructions - C.2. Download Locations - - D. GNU Free Documentation License - - 0. Preamble - 1. Applicability and Definition - 2. Verbatim Copying - 3. Copying in Quantity - 4. Modifications - 5. Combining Documents - 6. Collections of Documents - 7. Aggregation with Independent Works - 8. Translation - 9. Termination - 10. Future Revisions of this License - How to use this License for your documents - - Glossary - - List of Examples - 3-1. Upgrading using CVS - 3-2. Upgrading using the tarball - 3-3. Upgrading using patches - _________________________________________________________________ - -Chapter 1. About This Guide - -1.1. Copyright Information - - This document is copyright (c) 2000-2004 by the various Bugzilla - contributors who wrote it. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation; with no Invariant Sections, no Front-Cover Texts, and - with no Back-Cover Texts. A copy of the license is included in - Appendix D. - - If you have any questions regarding this document, its copyright, or - publishing this document in non-electronic form, please contact the - Bugzilla Team. - _________________________________________________________________ - -1.2. Disclaimer - - No liability for the contents of this document can be accepted. Follow - the instructions herein at your own risk. This document may contain - errors and inaccuracies that may damage your system, cause your - partner to leave you, your boss to fire you, your cats to pee on your - furniture and clothing, and global thermonuclear war. Proceed with - caution. - - Naming of particular products or brands should not be seen as - endorsements, with the exception of the term "GNU/Linux". We - wholeheartedly endorse the use of GNU/Linux; it is an extremely - versatile, stable, and robust operating system that offers an ideal - operating environment for Bugzilla. - - Although the Bugzilla development team has taken great care to ensure - that all exploitable bugs have been fixed, security holes surely exist - in any piece of code. Great care should be taken both in the - installation and usage of this software. The Bugzilla development team - members assume no liability for your use of Bugzilla. You have the - source code, and are responsible for auditing it yourself to ensure - your security needs are met. - _________________________________________________________________ - -1.3. New Versions - - This is the 2.17.7 version of The Bugzilla Guide. It is so named to - match the current version of Bugzilla. This version of the guide, like - its associated Bugzilla version, is a development version. - - The latest version of this guide can always be found at - http://www.bugzilla.org, or checked out via CVS by following the - Mozilla CVS instructions and check out the - mozilla/webtools/bugzilla/docs/ subtree. However, you should read the - version which came with the Bugzilla release you are using. - - The Bugzilla Guide, or a section of it, is also available in the - following languages: German. - - In addition, there are Bugzilla template localisation projects in the - following languages. They may have translated documentation available: - Belarusian, Brazilian Portuguese, Chinese, French, German, Korean, - Russian and Spanish. - - If you would like to volunteer to translate the Guide into additional - languages, please contact Dave Miller. - _________________________________________________________________ - -1.4. Credits - - The people listed below have made enormous contributions to the - creation of this Guide, through their writing, dedicated hacking - efforts, numerous e-mail and IRC support sessions, and overall - excellent contribution to the Bugzilla community: - - Matthew P. Barnson, Kevin Brannen, Dawn Endico, Ben FrantzDale, Eric - Hanson, Tara Hernandez, Dave Lawrence, Zach Lipton, Gervase Markham, - Andrew Pearson, Joe Robins, Spencer Smith, Jacob Steenhagen, Ron - Teitelbaum, Terry Weissman, Martin Wulffeld. - - Also, thanks are due to the members of the - netscape.public.mozilla.webtools newsgroup. Without your discussions, - insight, suggestions, and patches, this could never have happened. - _________________________________________________________________ - -1.5. Document Conventions - - This document uses the following conventions: - - Descriptions Appearance - Warning - - Caution - - Don't run with scissors! - Hint - - Tip - - Would you like a breath mint? - Note - - Note - - Dear John... - Information requiring special attention - - Warning - - Read this or the cat gets it. - File or directory name filename - Command to be typed command - Application name application - Normal user's prompt under bash shell bash$ - Root user's prompt under bash shell bash# - Normal user's prompt under tcsh shell tcsh$ - Environment variables VARIABLE - Term found in the glossary Bugzilla - Code example - -Beginning and end of paragraph - - - This documentation is maintained in DocBook 4.1.2 XML format. Changes - are best submitted as plain text or XML diffs, attached to a bug filed - in the Bugzilla Documentation component. - _________________________________________________________________ - -Chapter 2. Installing Bugzilla - -2.1. Installation - - Note - - If you just want to use Bugzilla, you do not need to install it. None - of this chapter is relevant to you. Ask your Bugzilla administrator - for the URL to access it over the web. - - The Bugzilla server software is usually installed on Linux or Solaris. - If you are installing on another OS, check Section 2.4 before you - start your installation to see if there are any special instructions. - - As an alternative to following these instructions, you may wish to try - Arne Schirmacher's unofficial and unsupported Bugzilla Installer, - which installs Bugzilla and all its prerequisites on Linux or Solaris - systems. - - This guide assumes that you have administrative access to the Bugzilla - machine. It not possible to install and run Bugzilla itself without - administrative access except in the very unlikely event that every - single prerequisite is already installed. - - Warning - - The installation process may make your machine insecure for short - periods of time. Make sure there is a firewall between you and the - Internet. - - You are strongly recommended to make a backup of your system before - installing Bugzilla (and at regular intervals thereafter :-). - - In outline, the installation proceeds as follows: - 1. Install Perl (5.6.0 or above) - 2. Install MySQL (3.23.41 or above) - 3. Install a Webserver - 4. Install Bugzilla - 5. Install Perl modules - 6. Configure all of the above. - _________________________________________________________________ - -2.1.1. Perl - - Installed Version Test: perl -v - - Any machine that doesn't have Perl on it is a sad machine indeed. If - you don't have it and your OS doesn't provide official packages, visit - http://www.perl.com. Although Bugzilla runs with Perl 5.6.0, it's a - good idea to be using the latest stable version. As of this writing, - that is Perl 5.8.2. - _________________________________________________________________ - -2.1.2. MySQL - - Installed Version Test: mysql -V - - If you don't have it and your OS doesn't provide official packages, - visit http://www.mysql.com. You need MySQL version 3.23.41 or higher. - - Note - - Many of the binary versions of MySQL store their data files in /var. - On some Unix systems, this is part of a smaller root partition, and - may not have room for your bug database. To change the data directory, - you have to build MySQL from source yourself, and set it as an option - to configure. - - If you install from something other than a packaging/installation - system (such as .rpm, .dep, .exe, or .msi) make sure the MySQL server - is started when the machine boots. - _________________________________________________________________ - -2.1.3. Web Server - - Installed Version Test: view the default welcome page at - http:/// - - You have freedom of choice here, pretty much any web server that is - capable of running CGI scripts will work. However, we strongly - recommend using the Apache web server (either 1.3.x or 2.x), and the - installation instructions usually assume you are using it. If you have - got Bugzilla working using another webserver, please share your - experiences with us by filing a bug in Bugzilla Documentation. - - If you don't have Apache and your OS doesn't provide official - packages, visit http://httpd.apache.org/. - _________________________________________________________________ - -2.1.4. Bugzilla - - Download a Bugzilla tarball (or check it out from CVS) and place it in - a suitable directory, writable by the default web server user - (probably "nobody"). Good locations are either directly in the main - web space for your web server or perhaps in /usr/local with a symbolic - link from the web space. - - Caution - - The default Bugzilla distribution is not designed to be placed in a - cgi-bin directory. This includes any directory which is configured - using the ScriptAlias directive of Apache. - - Once all the files are in a web accessible directory, make that - directory writable by your webserver's user. This is a temporary step - until you run the checksetup.pl script, which locks down your - installation. - _________________________________________________________________ - -2.1.5. Perl Modules - - Bugzilla's installation process is based on a script called - checksetup.pl. The first thing it checks is whether you have - appropriate versions of all the required Perl modules. The aim of this - section is to pass this check. When it passes, do not run it again, - but proceed to Section 2.2. - - At this point, you need to su to root. You should remain as root until - the end of the install. Then run: - bash# ./checksetup.pl - - checksetup.pl will print out a list of the required and optional Perl - modules, together with the versions (if any) installed on your - machine. The list of required modules is reasonably long; however, you - may already have several of them installed. - - There is a meta-module called Bundle::Bugzilla, which installs all the - other modules with a single command. You should use this if you are - running Perl 5.6.1 or above. - - The preferred way of installing Perl modules is via CPAN on Unix, or - PPM on Windows (see Section 2.4.1.2). These instructions assume you - are using CPAN; if for some reason you need to install the Perl - modules manually, see Appendix C. - bash# perl -MCPAN -e 'install ""' - - If you using Bundle::Bugzilla, invoke the magic CPAN command on it. - Otherwise, you need to work down the list of modules that - checksetup.pl says are required, in the order given, invoking the - command on each. - - Tip - - Many people complain that Perl modules will not install for them. Most - times, the error messages complain that they are missing a file in - "@INC". Virtually every time, this error is due to permissions being - set too restrictively for you to compile Perl modules or not having - the necessary Perl development libraries installed on your system. - Consult your local UNIX systems administrator for help solving these - permissions issues; if you are the local UNIX sysadmin, please consult - the newsgroup/mailing list for further assistance or hire someone to - help you out. - - Here is a complete list of modules and their minimum versions. Some - modules have special installation notes, which follow. - - Required Perl modules: - - 1. AppConfig (1.52) - 2. CGI (2.93) - 3. Data::Dumper (any) - 4. Date::Format (2.21) - 5. DBI (1.32) - 6. DBD::mysql (2.1010) - 7. File::Spec (0.82) - 8. File::Temp (any) - 9. Template (2.08) - 10. Text::Wrap (2001.0131) - - Optional Perl modules: - - 1. GD (1.20) for bug charting - 2. Chart::Base (0.99c) for bug charting - 3. GD::Graph (any) for bug charting - 4. GD::Text::Align (any) for bug charting - 5. XML::Parser (any) for the XML interface - 6. PatchReader (0.9.1) for pretty HTML view of patches - 7. MIME::Parser (any) for the optional email interface - _________________________________________________________________ - -2.1.5.1. DBD::mysql - - The installation process will ask you a few questions about the - desired compilation target and your MySQL installation. For most of - the questions the provided default will be adequate, but when asked if - your desired target is the MySQL or mSQL packages, you should select - the MySQL-related ones. Later you will be asked if you wish to provide - backwards compatibility with the older MySQL packages; you should - answer YES to this question. The default is NO. - - A host of 'localhost' should be fine. A testing user of 'test', with a - null password, should have sufficient access to run tests on the - 'test' database which MySQL creates upon installation. - _________________________________________________________________ - -2.1.5.2. Template Toolkit (2.08) - - When you install Template Toolkit, you'll get asked various questions - about features to enable. The defaults are fine, except that it is - recommended you use the high speed XS Stash of the Template Toolkit, - in order to achieve best performance. - _________________________________________________________________ - -2.1.5.3. GD (1.20) - - The GD module is only required if you want graphical reports. - - Note - - The Perl GD module requires some other libraries that may or may not - be installed on your system, including libpng and libgd. The full - requirements are listed in the Perl GD module README. If compiling GD - fails, it's probably because you're missing a required library. - - Tip - - The version of the GD module you need is very closely tied to the - libgd version installed on your system. If you have a version 1.x of - libgd the 2.x versions of the GD module won't work for you. - _________________________________________________________________ - -2.1.5.4. Chart::Base (0.99c) - - The Chart::Base module is only required if you want graphical reports. - Note that earlier versions that 0.99c used GIFs, which are no longer - supported by the latest versions of GD. - _________________________________________________________________ - -2.1.5.5. GD::Graph (any) - - The GD::Graph module is only required if you want graphical reports. - _________________________________________________________________ - -2.1.5.6. GD::Text::Align (any) - - The GD::Text::Align module is only required if you want graphical - reports. - _________________________________________________________________ - -2.1.5.7. XML::Parser (any) - - The XML::Parser module is only required if you want to import XML bugs - using the importxml.pl script. This is required to use Bugzilla's - "move bugs" feature; you may also want to use it for migrating from - another bug database. XML::Parser requires that the expat library is - already installed on your machine. - _________________________________________________________________ - -2.1.5.8. MIME::Parser (any) - - The MIME::Parser module is only required if you want to use the email - interface located in the contrib directory. - _________________________________________________________________ - -2.1.5.9. PatchReader (0.9.1) - - The PatchReader module is only required if you want to use Patch - Viewer, a Bugzilla feature to show code patches in your web browser in - a more readable form. - _________________________________________________________________ - -2.2. Configuration - - Warning - - Poorly-configured MySQL and Bugzilla installations have given - attackers full access to systems in the past. Please take the security - parts of these guidelines seriously, even for Bugzilla machines hidden - away behind your firewall. - _________________________________________________________________ - -2.2.1. localconfig - - Once you run checksetup.pl with all the correct modules installed, it - displays a message about, and write out a file called, localconfig. - This file contains the default settings for a number of Bugzilla - parameters. - - Load this file in your editor. The only value you need to change is - $db_pass, the password for the user you will create for your database. - Pick a strong password (for simplicity, it should not contain single - quote characters) and put it here. - - The other options in the localconfig file are documented by their - accompanying comments. If you have a slightly non-standard MySQL - setup, you may wish to change one or more of the other "$db_*" - parameters. - - You may also wish to change the names of the priorities, severities, - operating systems and platforms for your installation. However, you - can always change these after installation has finished; if you then - re-run checksetup.pl, the changes will get picked up. - _________________________________________________________________ - -2.2.2. MySQL - -2.2.2.1. Security - - MySQL ships as insecure by default. It allows anybody to on the local - machine full administrative capabilities without requiring a password; - the special MySQL root account (note: this is not the same as the - system root) also has no password. Also, many installations default to - running mysqld as the system root. - - 1. To disable the anonymous user account and set a password for the - root user, execute the following. The root user password should be - different to the bugs user password you set in localconfig in the - previous section, and also different to the password for the - system root account on your machine. - - bash$ mysql mysql - mysql> DELETE FROM user WHERE user = ''; - mysql> UPDATE user SET password = password('new_password') WHERE user = 'root -'; - mysql> FLUSH PRIVILEGES; - - From this point forward, to run the mysql command-line client, you - will need to type mysql -u root -p and enter new_password when - prompted. - 2. If you run MySQL on the same machine as your web server, you - should disable remote access to MySQL by adding the following to - your /etc/my.conf: - - [myslqd] - # Prevent network access to MySQL. - skip-networking - - 3. Consult the documentation that came with your system for - information on making mysqld run as an unprivileged user. - 4. For added security, you could also run MySQL, or even all of - Bugzilla in a chroot jail; however, instructions for doing that - are beyond the scope of this document. - _________________________________________________________________ - -2.2.2.2. Allow large attachments - - You need to configure MySQL to accept large packets, if you want to - have attachments larger than 64K. Add the text below to your - /etc/my.conf. There is also a parameter in Bugzilla for setting the - maximum allowable attachment size, (default 1MB). Bugzilla will only - accept attachments up to the lower of these two sizes. - [mysqld] - # Allow packets up to 1M - set-variable = max_allowed_packet=1M - _________________________________________________________________ - -2.2.2.3. Add a user to MySQL - - You need to add a new MySQL user for Bugzilla to use. (It's not safe - to have Bugzilla use the MySQL root account.) The following - instructions assume the defaults in localconfig; if you changed those, - you need to modify the SQL command appropriately. You will need the - $db_pass password you set in localconfig in Section 2.2.1. - - We use an SQL GRANT command to create a "bugs" user. This also - restricts the "bugs" user to operations within a database called - "bugs", and only allows the account to connect from "localhost". - Modify it to reflect your setup if you will be connecting from another - machine or as a different user. - - Run the mysql command-line client and enter: - mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE, - DROP,REFERENCES ON bugs.* TO bugs@localhost - IDENTIFIED BY '$db_pass'; - mysql> FLUSH PRIVILEGES - - Note - - If you are using MySQL 4, you need to add the LOCK TABLES and CREATE - TEMPORARY TABLES permissions to the list. - _________________________________________________________________ - -2.2.3. checksetup.pl - - Next, rerun checksetup.pl. It reconfirms that all the modules are - present, and notices the altered localconfig file, which it assumes - you have edited to your satisfaction. It compiles the UI templates, - connects to the database using the 'bugs' user you created and the - password you defined, and creates the 'bugs' database and the tables - therein. - - After that, it asks for details of an administrator account. Bugzilla - can have multiple administrators - you can create more later - but it - needs one to start off with. Enter the email address of an - administrator, his or her full name, and a suitable Bugzilla password. - - checksetup.pl will then finish. You may rerun checksetup.pl at any - time if you wish. - _________________________________________________________________ - -2.2.4. Web server - - Configure your web server according to the instructions in the - appropriate section. The Bugzilla Team recommends Apache. - _________________________________________________________________ - -2.2.4.1. Apache httpd - - Load httpd.conf in your editor. - - Uncomment (or add) the following line. This configures Apache to run - .cgi files outside the cgi-bin directory. - AddHandler cgi-script .cgi - - Apache uses directives to permit fine-grained permission - setting. Add the following two lines to a directive that - applies either to the Bugzilla directory or one of its parents (e.g. - the directive). This allows Bugzilla's - .htaccess files to override global permissions, and allows .cgi files - to run in the Bugzilla directory. - Options +ExecCGI +FollowSymLinks - AllowOverride Limit - - Add index.cgi to the end of the DirectoryIndex line. - - checksetup.pl can set tighter permissions on Bugzilla's files and - directories if it knows what user the webserver runs as. Look for the - User line in httpd.conf, and place that value in the $webservergroup - variable in localconfig. Then rerun checksetup.pl. - _________________________________________________________________ - -2.2.4.2. Microsoft Internet Information Services - - If you need, or for some reason even want, to use Microsoft's Internet - Information Services or Personal Web Server you should be able to. You - will need to configure them to know how to run CGI scripts. This is - described in Microsoft Knowledge Base article Q245225 for Internet - Information Services and Q231998 for Personal Web Server. - - Also, and this can't be stressed enough, make sure that files such as - localconfig and your data directory are secured as described in - Section 2.2.4.4. - _________________________________________________________________ - -2.2.4.3. AOL Server - - Ben FrantzDale reported success using AOL Server with Bugzilla. He - reported his experience and what appears below is based on that. - - AOL Server will have to be configured to run CGI scripts, please - consult the documentation that came with your server for more - information on how to do this. - - Because AOL Server doesn't support .htaccess files, you'll have to - create a TCL script. You should create an - aolserver/modules/tcl/filter.tcl file (the filename shouldn't matter) - with the following contents (change /bugzilla/ to the web-based path - to your Bugzilla installation): - ns_register_filter preauth GET /bugzilla/localconfig filter_deny - ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny - ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny - ns_register_filter preauth GET /bugzilla/*.pl filter_deny - ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny - ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny - ns_register_filter preauth GET /bugzilla/data/* filter_deny - ns_register_filter preauth GET /bugzilla/template/* filter_deny - - proc filter_deny { why } { - ns_log Notice "filter_deny" - return "filter_return" - } - - Warning - - This probably doesn't account for all possible editor backup files so - you may wish to add some additional variations of localconfig. For - more information, see bug 186383 or Bugtraq ID 6501. - - Note - - If you are using webdot from research.att.com (the default - configuration for the webdotbase paramater), you will need to allow - access to data/webdot/*.dot for the reasearch.att.com machine. - - If you are using a local installation of GraphViz, you will need to - allow everybody to access *.png, *.gif, *.jpg, and *.map in the - data/webdot directory. - _________________________________________________________________ - -2.2.4.4. Web Server Access Controls - - Users of Apache can skip this section because Bugzilla ships with - .htaccess files which restrict access in the manner required. Users of - other webservers, read on. - - There are several files in the Bugzilla directory that should not be - accessible from the web. You need to configure your webserver so they - they aren't. Not doing this may reveal sensitive information such as - database passwords. - - * In the main Bugzilla directory, you should: - + Block: *.pl, *localconfig*, runtests.sh - + But allow: localconfig.js, localconfig.rdf - * In data: - + Block everything - + But allow: duplicates.rdf - * In data/webdot: - + If you use a remote webdot server: - o Block everything - o But allow *.dot only for the remote webdot server - + Otherwise, if you use a local GraphViz: - o Block everything - o But allow: *.png, *.gif, *.jpg, *.map - + And if you don't use any dot: - o Block everything - * In Bugzilla: - + Block everything - * In template: - + Block everything - - You should test to make sure that the files mentioned above are not - accessible from the Internet, especially your localconfig file which - contains your database password. To test, simply point your web - browser at the file; for example, to test mozilla.org's installation, - we'd try to access http://bugzilla.mozilla.org/localconfig. You should - get a 403 Forbidden error. - _________________________________________________________________ - -2.2.5. Bugzilla - - Your Bugzilla should now be working. Access - http:/// - you should see the Bugzilla front - page. If not, consult the Troubleshooting section, Section 2.5. - - Log in with the administrator account you defined in the last - checksetup.pl run. You should go through the parameters on the Edit - Parameters page (see link in the footer) and see if there are any you - wish to change. They key parameters are documented in Section 3.1; you - should certainly alter maintainer and urlbase; you may also want to - alter cookiepath or requirelogin. - - This would also be a good time to revisit the localconfig file and - make sure that the names of the priorities, severities, platforms and - operating systems are those you wish to use when you start creating - bugs. Remember to rerun checksetup.pl if you change it. - - Bugzilla has several optional features which require extra - configuration. You can read about those in Section 2.3. - _________________________________________________________________ - -2.3. Optional Additional Configuration - - Bugzilla has a number of optional features. This section describes how - to configure or enable them. - _________________________________________________________________ - -2.3.1. Bug Graphs - - If you have installed the necessary Perl modules you can start - collecting statistics for the nifty Bugzilla graphs. - bash# crontab -e - - This should bring up the crontab file in your editor. Add a cron entry - like this to run collectstats.pl daily at 5 after midnight: - 5 0 * * * cd ; ./collectstats.pl - - After two days have passed you'll be able to view bug graphs from the - Reports page. - _________________________________________________________________ - -2.3.2. Dependency Charts - - As well as the text-based dependency trees, Bugzilla also supports a - graphical view of dependency relationships, using a package called - 'dot'. Exactly how this works is controlled by the 'webdotbase' - parameter, which can have one of three values: - - 1. A complete file path to the command 'dot' (part of GraphViz) will - generate the graphs locally - 2. A URL prefix pointing to an installation of the webdot package - will generate the graphs remotely - 3. A blank value will disable dependency graphing. - - The easiest way to get this working is to install GraphViz. If you do - that, you need to enable server-side image maps in Apache. - Alternatively, you could set up a webdot server, or use the AT&T - public webdot server. This is the default for the webdotbase param, - but it's often overloaded and slow. Note that AT&T's server won't work - if Bugzilla is only accessible using HARTS. Editor's note: What the - heck is HARTS? Google doesn't know... - _________________________________________________________________ - -2.3.3. The Whining Cron - - What good are bugs if they're not annoying? To help make them more so - you can set up Bugzilla's automatic whining system to complain at - engineers which leave their bugs in the NEW or REOPENED state without - triaging them. - - This can be done by adding the following command as a daily crontab - entry, in the same manner as explained above for bug graphs. This - example runs it at 12.55am. - 55 0 * * * cd ; ./whineatnews.pl - _________________________________________________________________ - -2.3.4. Patch Viewer - - Patch Viewer is the engine behind Bugzilla's graphical display of code - patches. You can integrate this with copies of the cvs, lxr and bonsai - tools if you have them, by giving the locations of your installation - of these tools in editparams.cgi. - - Patch Viewer also optionally will use the cvs, diff and interdiff - command-line utilities if they exist on the system. Interdiff can be - obtained from http://cyberelk.net/tim/patchutils/. If these programs - are not in the system path, you can configure their locations in - localconfig. - _________________________________________________________________ - -2.3.5. LDAP Authentication - - LDAP authentication is a module for Bugzilla's plugin authentication - architecture. - - 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. - - Caution - - Because the Bugzilla account is not created until the first time a - user logs in, a user who has not yet logged is unknown to Bugzilla. - This means they cannot be used as an assignee or QA contact (default - or otherwise), added to any cc list, or any other such operation. One - possible workaround is the bugzilla_ldapsync.rb script in the contrib - directory. Another possible solution is fixing bug 201069. - - Parameters required to use LDAP Authentication: - - loginmethod - This parameter should be set to "LDAP" only if you will be - using an LDAP directory for authentication. If you set this - param to "LDAP" but fail to set up the other parameters listed - below you will not be able to log back in to Bugzilla one you - log out. If this happens to you, you will need to manually edit - data/params and set loginmethod to "DB". - - LDAPserver - This parameter should be set to the name (and optionally the - port) of your LDAP server. If no port is specified, it assumes - the default LDAP port of 389. - - Ex. "ldap.company.com" or "ldap.company.com:3268" - - LDAPbinddn [Optional] - Some LDAP servers will not allow an anonymous bind to search - the directory. If this is the case with your configuration you - should set the LDAPbinddn parameter to the user account - Bugzilla should use instead of the anonymous bind. - - Ex. "cn=default,cn=user:password" - - LDAPBaseDN - The LDAPBaseDN parameter should be set to the location in your - LDAP tree that you would like to search for email addresses. - Your uids should be unique under the DN specified here. - - Ex. "ou=People,o=Company" - - LDAPuidattribute - The LDAPuidattribute parameter should be set to the attribute - which contains the unique UID of your users. The value - retrieved from this attribute will be used when attempting to - bind as the user to confirm their password. - - Ex. "uid" - - LDAPmailattribute - The LDAPmailattribute parameter should be the name of the - attribute which contains the email address your users will - enter into the Bugzilla login boxes. - - Ex. "mail" - _________________________________________________________________ - -2.3.6. Prevent users injecting malicious Javascript - - It is possible for a Bugzilla user to take advantage of character set - encoding ambiguities to inject HTML into Bugzilla comments. This could - include malicious scripts. Due to internationalization concerns, we - are unable to incorporate by default the code changes suggested by the - CERT advisory on this issue. If your installation is for an English - speaking audience only, making the change below will prevent this - problem. - - Simply locate the following line in Bugzilla/CGI.pm: - $self->charset(''); - - and change it to: - $self->charset('ISO-8859-1'); - _________________________________________________________________ - -2.3.7. mod_throttle - - It is possible for a user, by mistake or on purpose, to access the - database many times in a row which can result in very slow access - speeds for other users. If your Bugzilla installation is experiencing - this problem, you may install the Apache module mod_throttle which can - limit connections by IP address. You may download this module at - http://www.snert.com/Software/mod_throttle/. Follow the instructions - to install into your Apache install. This module only functions with - the Apache web server! The command you need is ThrottleClientIP. See - the documentation for more information. - _________________________________________________________________ - -2.3.8. TCP/IP Ports - - A single-box Bugzilla only requires port 80, plus port 25 if you are - using the optional email interface. You should firewall all other - ports and/or disable services listening on them. - _________________________________________________________________ - -2.3.9. Daemon Accounts - - Many daemons, such as Apache's httpd and MySQL's mysqld default to - running as either "root" or "nobody". Running as "root" introduces - obvious security problems, but the problems introduced by running - everything as "nobody" may not be so obvious. Basically, if you're - running every daemon as "nobody" and one of them gets compromised, - they all get compromised. For this reason it is recommended that you - create a user account for each daemon. - _________________________________________________________________ - -2.4. OS-Specific Installation Notes - - Many aspects of the Bugzilla installation can be affected by the the - operating system you choose to install it on. Sometimes it can be made - easier and others more difficult. This section will attempt to help - you understand both the difficulties of running on specific operating - systems and the utilities available to make it easier. - - If you have anything to add or notes for an operating system not - covered, please file a bug in Bugzilla Documentation. - _________________________________________________________________ - -2.4.1. Microsoft Windows - - Making Bugzilla work on Windows is still a painful processes. The - Bugzilla Team is working to make it easier, but that goal is not - considered a top priority. If you wish to run Bugzilla, we still - recommend doing so on a Unix based system such as GNU/Linux. As of - this writing, all members of the Bugzilla team and all known large - installations run on Unix based systems. - - If after hearing all that, you have enough pain tolerance to attempt - installing Bugzilla on Win32, here are some pointers. Because this is - a development version of the guide, these instructions are subject to - change without notice. In fact, the Bugzilla Team hopes to have - Bugzilla reasonably close to "out of the box" compatibility with - Windows by the 2.18 release. - _________________________________________________________________ - -2.4.1.1. Win32 Perl - - Perl for Windows can be obtained from ActiveState. You should be able - to find a compiled binary at - http://aspn.activestate.com/ASPN/Downloads/ActivePerl/. - _________________________________________________________________ - -2.4.1.2. Perl Modules on Win32 - - Bugzilla on Windows requires the same perl modules found in Section - 2.1.5. The main difference is that windows uses PPM instead of CPAN. -C:\perl> ppm - - Note - - The above syntax should work for all modules with the exception of - Template Toolkit. The Template Toolkit website suggests using the - instructions on OpenInteract's website. - _________________________________________________________________ - -2.4.1.3. Code changes required to run on win32 - - As Bugzilla still doesn't run "out of the box" on Windows, code has to - be modified. This section lists the required changes. - _________________________________________________________________ - -2.4.1.3.1. Changes to checksetup.pl - - In checksetup.pl, the line reading: -my $mysql_binaries = `which mysql`; - - to -my $mysql_binaries = "D:\\mysql\\bin\\mysql"; - - And you'll also need to change: -my $webservergid = getgrnam($my_webservergroup) - - to -my $webservergid = '8' - _________________________________________________________________ - -2.4.1.3.2. Changes to BugMail.pm - - To make bug email work on Win32 (until bug 84876 lands), the simplest - way is to have the Net::SMTP Perl module installed and change this: -open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") || - die "Can't open sendmail"; - -print SENDMAIL trim($msg) . "\n"; -close SENDMAIL; - - to -use Net::SMTP; -my $smtp_server = 'smtp.mycompany.com'; # change this - -# Use die on error, so that the mail will be in the 'unsent mails' and -# can be sent from the sanity check page. -my $smtp = Net::SMTP->new($smtp_server) || - die 'Cannot connect to server \'$smtp_server\''; - -$smtp->mail('bugzilla-daemon@mycompany.com'); # change this -$smtp->to($person); -$smtp->data(); -$smtp->datasend($msg); -$smtp->dataend(); -$smtp->quit; - - Don't forget to change the name of your SMTP server and the domain of - the sending email address (after the '@') in the above lines of code. - _________________________________________________________________ - -2.4.1.4. Serving the web pages - - As is the case on Unix based systems, any web server should be able to - handle Bugzilla; however, the Bugzilla Team still recommends Apache - whenever asked. No matter what web server you choose, be sure to pay - attention to the security notes in Section 2.2.4.4. More information - on configuring specific web servers can be found in Section 2.2.4. - - Note - - If using Apache on windows, you can set the ScriptInterpreterSource - directive in your Apache config to avoid having to modify the first - line of every script to contain your path to perl instead of - /usr/bin/perl. - _________________________________________________________________ - -2.4.2. Mac OS X - - Apple did not include the GD library with Mac OS X. Bugzilla needs - this for bug graphs. - - You can install it using a program called Fink, which is similar in - nature to the CPAN installer, but installs common GNU utilities. Fink - is available from http://sourceforge.net/projects/fink/. - - Follow the instructions for setting up Fink. Once it's installed, - you'll want to use it to install the gd2 package. - - It will prompt you for a number of dependencies, type 'y' and hit - enter to install all of the dependencies and then watch it work. You - will then be able to use CPAN to install the GD Perl module. - - Note - - To prevent creating conflicts with the software that Apple installs by - default, Fink creates its own directory tree at /sw where it installs - most of the software that it installs. This means your libraries and - headers be at /sw/lib and /sw/include instead of /usr/lib and - /usr/local/include. When the Perl module config script asks where your - libgd is, be sure to tell it /sw/lib. - - Also available via Fink is expat. After using fink to install the - expat package you will be able to install XML::Parser using CPAN. - There is one caveat. Unlike recent versions of the GD module, - XML::Parser doesn't prompt for the location of the required libraries. - When using CPAN, you will need to use the following command sequence: -# perl -MCPAN -e'look XML::Parser' (1) -# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include -# make; make test; make install (2) -# exit (3) - - (1) (3) - The look command will download the module and spawn a new shell - with the extracted files as the current working directory. The - exit command will return you to your original shell. - (2) - You should watch the output from these make commands, - especially "make test" as errors may prevent XML::Parser from - functioning correctly with Bugzilla. - _________________________________________________________________ - -2.4.3. Linux-Mandrake 8.0 - - Linux-Mandrake 8.0 includes every required and optional library for - Bugzilla. The easiest way to install them is by using the urpmi - utility. If you follow these commands, you should have everything you - need for Bugzilla, and ./checksetup.pl should not complain about any - missing libraries. You may already have some of these installed. -bash# urpmi perl-mysql -bash# urpmi perl-chart -bash# urpmi perl-gd -bash# urpmi perl-MailTools (1) -bash# urpmi apache-modules - - (1) - for Bugzilla email integration - _________________________________________________________________ - -2.5. Troubleshooting - - This section gives solutions to common Bugzilla installation problems. - If none of the section headings seems to match your problem, read the - general advice. - _________________________________________________________________ - -2.5.1. General Advice - - If you can't get checksetup.pl to run to completion, it normally - explains what's wrong and how to fix it. If you can't work it out, or - if it's being uncommunicative, post the errors in the - netscape.public.mozilla.webtools newsgroup. - - If you have made it all the way through Section 2.1 (Installation) and - Section 2.2 (Configuration) but accessing the Bugzilla URL doesn't - work, the first thing to do is to check your webserver error log. For - Apache, this is often located at /etc/logs/httpd/error_log. The error - messages you see may be self-explanatory enough to enable you to - diagnose and fix the problem. If not, see below for some - commonly-encountered errors. If that doesn't help, post the errors to - the newsgroup. - _________________________________________________________________ - -2.5.2. I installed a Perl module, but checksetup.pl claims it's not -installed! - - You have two versions of Perl on your machine. You are installing - modules into one, and Bugzilla is using the other. Rerun the CPAN - commands (or manual compile) using the full path to Perl from the top - of checksetup.pl. This will make sure you are installing the modules - in the right place. - _________________________________________________________________ - -2.5.3. Bundle::Bugzilla makes me upgrade to Perl 5.6.1 - - Try executing perl -MCPAN -e 'install CPAN' and then continuing. - - Certain older versions of the CPAN toolset were somewhat naive about - how to upgrade Perl modules. When a couple of modules got rolled into - the core Perl distribution for 5.6.1, CPAN thought that the best way - to get those modules up to date was to haul down the Perl distribution - itself and build it. Needless to say, this has caused headaches for - just about everybody. Upgrading to a newer version of CPAN with the - commandline above should fix things. - _________________________________________________________________ - -2.5.4. DBD::Sponge::db prepare failed - - 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 /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.) - _________________________________________________________________ - -2.5.5. cannot chdir(/var/spool/mqueue) - - 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. - _________________________________________________________________ - -2.5.6. Your vendor has not defined Fcntl macro O_NOINHERIT - - This is caused by a bug in the version of File::Temp that is - distributed with perl 5.6.0. Many minor variations of this error have - been reported: -Your vendor has not defined Fcntl macro O_NOINHERIT, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208. - -Your vendor has not defined Fcntl macro O_EXLOCK, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210. - -Your vendor has not defined Fcntl macro O_TEMPORARY, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. - - Numerous people have reported that upgrading to version 5.6.1 or - higher solved the problem for them. A less involved fix is to apply - the following patch, which is also available as a patch file. ---- File/Temp.pm.orig Thu Feb 6 16:26:00 2003 -+++ File/Temp.pm Thu Feb 6 16:26:23 2003 -@@ -205,6 +205,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; -@@ -226,6 +227,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; - _________________________________________________________________ - -Chapter 3. Administering Bugzilla - -3.1. Bugzilla Configuration - - Bugzilla is configured by changing various parameters, accessed from - the "Edit parameters" link in the page footer. Here are some of the - key parameters on that page. You should run down this list and set - them appropriately after installing Bugzilla. - 1. maintainer: The maintainer parameter is the email address of the - person responsible for maintaining this Bugzilla installation. The - address need not be that of a valid Bugzilla account. - 2. urlbase: This parameter defines the fully qualified domain name - and web server path to your Bugzilla installation. - For example, if your Bugzilla query page is - http://www.foo.com/bugzilla/query.cgi, set your "urlbase" to - http://www.foo.com/bugzilla/. - 3. makeproductgroups: This dictates whether or not to automatically - create groups when new products are created. - 4. useentrygroupdefault: Bugzilla products can have a group - associated with them, so that certain users can only see bugs in - certain products. When this parameter is set to "on", this causes - the initial group controls on newly created products to place all - newly-created bugs in the group having the same name as the - product immediately. After a product is initially created, the - group controls can be further adjusted without interference by - this mechanism. - 5. shadowdb: You run into an interesting problem when Bugzilla - reaches a high level of continuous activity. MySQL supports only - table-level write locking. What this means is that if someone - needs to make a change to a bug, they will lock the entire table - until the operation is complete. Locking for write also blocks - reads until the write is complete. Note that more recent versions - of mysql support row level locking using different table types. - These types are slower than the standard type, and Bugzilla does - not yet take advantage of features such as transactions which - would justify this speed decrease. The Bugzilla team are, however, - happy to hear about any experiences with row level locking and - Bugzilla. - The "shadowdb" parameter was designed to get around this - limitation. While only a single user is allowed to write to a - table at a time, reads can continue unimpeded on a read-only - shadow copy of the database. Although your database size will - double, a shadow database can cause an enormous performance - improvement when implemented on extremely high-traffic Bugzilla - databases. - As a guide, on reasonably old hardware, mozilla.org began needing - "shadowdb" when they reached around 40,000 Bugzilla users with - several hundred Bugzilla bug changes and comments per day. - The value of the parameter defines the name of the shadow bug - database. You will need to set the host and port settings from the - params page, and set up replication in your database server so - that updates reach this readonly mirror. Consult your database - documentation for more detail. - 6. shutdownhtml: If you need to shut down Bugzilla to perform - administration, enter some descriptive HTML here and anyone who - tries to use Bugzilla will receive a page to that effect. - Obviously, editparams.cgi will still be accessible so you can - remove the HTML and re-enable Bugzilla. :-) - 7. passwordmail: Every time a user creates an account, the text of - this parameter (with substitutions) is sent to the new user along - with their password message. - Add any text you wish to the "passwordmail" parameter box. For - instance, many people choose to use this box to give a quick - training blurb about how to use Bugzilla at your site. - 8. movebugs: This option is an undocumented feature to allow moving - bugs between separate Bugzilla installations. You will need to - understand the source code in order to use this feature. Please - consult movebugs.pl in your Bugzilla source tree for further - documentation, such as it is. - 9. useqacontact: This allows you to define an email address for each - component, in addition to that of the default owner, who will be - sent carbon copies of incoming bugs. - 10. usestatuswhiteboard: This defines whether you wish to have a - free-form, overwritable field associated with each bug. The - advantage of the Status Whiteboard is that it can be deleted or - modified with ease, and provides an easily-searchable field for - indexing some bugs that have some trait in common. - 11. whinedays: Set this to the number of days you want to let bugs go - in the NEW or REOPENED state before notifying people they have - untouched new bugs. If you do not plan to use this feature, simply - do not set up the whining cron job described in the installation - instructions, or set this value to "0" (never whine). - 12. commenton*: All these fields allow you to dictate what changes can - pass without comment, and which must have a comment from the - person who changed them. Often, administrators will allow users to - add themselves to the CC list, accept bugs, or change the Status - Whiteboard without adding a comment as to their reasons for the - change, yet require that most other changes come with an - explanation. - Set the "commenton" options according to your site policy. It is a - wise idea to require comments when users resolve, reassign, or - reopen bugs at the very least. - - Note - - It is generally far better to require a developer comment when - resolving bugs than not. Few things are more annoying to bug database - users than having a developer mark a bug "fixed" without any comment - as to what the fix was (or even that it was truly fixed!) - 13. supportwatchers: Turning on this option allows users to ask to - receive copies of all a particular other user's bug email. This - is, of course, subject to the groupset restrictions on the bug; if - the "watcher" would not normally be allowed to view a bug, the - watcher cannot get around the system by setting herself up to - watch the bugs of someone with bugs outside her privileges. They - would still only receive email updates for those bugs she could - normally view. - _________________________________________________________________ - -3.2. User Administration - -3.2.1. Creating the Default User - - When you first run checksetup.pl after installing Bugzilla, it will - prompt you for the administrative username (email address) and - password for this "super user". If for some reason you delete the - "super user" account, re-running checksetup.pl will again prompt you - for this username and password. - - Tip - - If you wish to add more administrative users, add them to the "admin" - group and, optionally, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. - _________________________________________________________________ - -3.2.2. Managing Other Users - -3.2.2.1. Creating new users - - Your users can create their own user accounts by clicking the "New - Account" link at the bottom of each page (assuming they aren't logged - in as someone else already.) However, should you desire to create user - accounts ahead of time, here is how you do it. - - 1. After logging in, click the "Users" link at the footer of the - query page, and then click "Add a new user". - 2. Fill out the form presented. This page is self-explanatory. When - done, click "Submit". - - Note - - Adding a user this way will not send an email informing them of their - username and password. While useful for creating dummy accounts - (watchers which shuttle mail to another system, for instance, or email - addresses which are a mailing list), in general it is preferable to - log out and use the "New Account" button to create users, as it will - pre-populate all the required fields and also notify the user of her - account name and password. - _________________________________________________________________ - -3.2.2.2. Modifying Users - - To see a specific user, search for their login name in the box - provided on the "Edit Users" page. To see all users, leave the box - blank. - - You can search in different ways the listbox to the right of the text - entry box. You can match by case-insensitive substring (the default), - regular expression, or a reverse regular expression match, which finds - every user name which does NOT match the regular expression. (Please - see the man regexp manual page for details on regular expression - syntax.) - - Once you have found your user, you can change the following fields: - - * Login Name: This is generally the user's full email address. - However, if you have are using the emailsuffix Param, this may - just be the user's login name. Note that users can now change - their login names themselves (to any valid email address.) - * Real Name: The user's real name. Note that Bugzilla does not - require this to create an account. - * Password: You can change the user's password here. Users can - automatically request a new password, so you shouldn't need to do - this often. If you want to disable an account, see Disable Text - below. - * Disable Text: If you type anything in this box, including just a - space, the user is prevented from logging in, or making any - changes to bugs via the web interface. The HTML you type in this - box is presented to the user when they attempt to perform these - actions, and should explain why the account was disabled. - - Warning - - Don't disable all the administrator accounts! - - Note - - The user can still submit bugs via the e-mail gateway, if you set it - up, even if the disabled text field is filled in. The e-mail gateway - should not be enabled for secure installations of Bugzilla. - * : If you have created some groups, e.g. - "securitysensitive", then checkboxes will appear here to allow you - to add users to, or remove them from, these groups. - * canconfirm: This field is only used if you have enabled the - "unconfirmed" status. If you enable this for a user, that user can - then move bugs from "Unconfirmed" to a "Confirmed" status (e.g.: - "New" status). - * creategroups: This option will allow a user to create and destroy - groups in Bugzilla. - * editbugs: Unless a user has this bit set, they can only edit those - bugs for which they are the assignee or the reporter. Even if this - option is unchecked, users can still add comments to bugs. - * editcomponents: This flag allows a user to create new products and - components, as well as modify and destroy those that have no bugs - associated with them. If a product or component has bugs - associated with it, those bugs must be moved to a different - product or component before Bugzilla will allow them to be - destroyed. - * editkeywords: If you use Bugzilla's keyword functionality, - enabling this feature allows a user to create and destroy - keywords. As always, the keywords for existing bugs containing the - keyword the user wishes to destroy must be changed before Bugzilla - will allow it to die. - * editusers: This flag allows a user to do what you're doing right - now: edit other users. This will allow those with the right to do - so to remove administrator privileges from other users or grant - them to themselves. Enable with care. - * tweakparams: This flag allows a user to change Bugzilla's Params - (using editparams.cgi.) - * : This allows an administrator to specify the - products in which a user can see bugs. The user must still have - the "editbugs" privilege to edit bugs in these products. - _________________________________________________________________ - -3.3. Products - - Products are the broadest category in Bugzilla, and tend to represent - real-world shipping products. E.g. if your company makes computer - games, you should have one product per game, perhaps a "Common" - product for units of technology used in multiple games, and maybe a - few special products (Website, Administration...) - - Many of Bugzilla's settings are configurable on a per-product basis. - The number of "votes" available to users is set per-product, as is the - number of votes required to move a bug automatically from the - UNCONFIRMED status to the NEW status. - - To create a new product: - - 1. Select "products" from the footer - 2. Select the "Add" link in the bottom right - 3. Enter the name of the product and a description. The Description - field may contain HTML. - - Don't worry about the "Closed for bug entry", "Maximum Votes per - person", "Maximum votes a person can put on a single bug", "Number of - votes a bug in this Product needs to automatically get out of the - UNCOMFIRMED state", and "Version" options yet. We'll cover those in a - few moments. - _________________________________________________________________ - -3.4. Components - - Components are subsections of a Product. E.g. the computer game you - are designing may have a "UI" component, an "API" component, a "Sound - System" component, and a "Plugins" component, each overseen by a - different programmer. It often makes sense to divide Components in - Bugzilla according to the natural divisions of responsibility within - your Product or company. - - Each component has a owner and (if you turned it on in the - parameters), a QA Contact. The owner should be the primary person who - fixes bugs in that component. The QA Contact should be the person who - will ensure these bugs are completely fixed. The Owner, QA Contact, - and Reporter will get email when new bugs are created in this - Component and when these bugs change. Default Owner and Default QA - Contact fields only dictate the default assignments; these can be - changed on bug submission, or at any later point in a bug's life. - - To create a new Component: - - 1. Select the "Edit components" link from the "Edit product" page - 2. Select the "Add" link in the bottom right. - 3. Fill out the "Component" field, a short "Description", the - "Initial Owner" and "Initial QA Contact" (if enabled.) The - Component and Description fields may contain HTML; the "Initial - Owner" field must be a login name already existing in the - database. - _________________________________________________________________ - -3.5. Versions - - Versions are the revisions of the product, such as "Flinders 3.1", - "Flinders 95", and "Flinders 2000". Version is not a multi-select - field; the usual practice is to select the earliest version known to - have the bug. - - To create and edit Versions: - - 1. From the "Edit product" screen, select "Edit Versions" - 2. You will notice that the product already has the default version - "undefined". Click the "Add" link in the bottom right. - 3. Enter the name of the Version. This field takes text only. Then - click the "Add" button. - _________________________________________________________________ - -3.6. Milestones - - Milestones are "targets" that you plan to get a bug fixed by. For - example, you have a bug that you plan to fix for your 3.0 release, it - would be assigned the milestone of 3.0. - - Note - - Milestone options will only appear for a Product if you turned on the - "usetargetmilestone" Param in the "Edit Parameters" screen. - - To create new Milestones, set Default Milestones, and set Milestone - URL: - - 1. Select "Edit milestones" from the "Edit product" page. - 2. Select "Add" in the bottom right corner. text - 3. Enter the name of the Milestone in the "Milestone" field. You can - optionally set the "sortkey", which is a positive or negative - number (-255 to 255) that defines where in the list this - particular milestone appears. This is because milestones often do - not occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add". - 4. From the Edit product screen, you can enter the URL of a page - which gives information about your milestones and what they mean. - _________________________________________________________________ - -3.7. Voting - - Voting allows users to be given a pot of votes which they can allocate - to bugs, to indicate that they'd like them fixed. 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. - - To modify Voting settings: - - 1. Navigate to the "Edit product" screen for the Product you wish to - modify - 2. Maximum Votes per person: Setting this field to "0" disables - voting. - 3. Maximum Votes a person can put on a single bug: It should probably - be some number lower than the "Maximum votes per person". Don't - set this field to "0" if "Maximum votes per person" is non-zero; - that doesn't make any sense. - 4. Number of votes a bug in this product needs to automatically get - out of the UNCONFIRMED state: Setting this field to "0" disables - the automatic move of bugs from UNCONFIRMED to NEW. - 5. Once you have adjusted the values to your preference, click - "Update". - _________________________________________________________________ - -3.8. Groups and Group Security - - Groups allow the administrator to isolate bugs or products that should - only be seen by certain people. The association between products and - groups is controlled from the product edit page under "Edit Group - Controls." - - If the makeproductgroups param is on, a new group will be - automatically created for every new product. - - On the product edit page, there is a page to edit the "Group Controls" - for a product and determine which groups are applicable, default, and - mandatory for each product as well as controlling entry for each - product and being able to set bugs in a product to be totally - read-only unless some group restrictions are met. - - For each group, it is possible to specify if membership in that group - is... - - 1. required for bug entry, - 2. Not applicable to this product(NA), a possible restriction for a - member of the group to place on a bug in this product(Shown), a - default restriction for a member of the group to place on a bug in - this product(Default), or a mandatory restriction to be placed on - bugs in this product(Mandatory). - 3. Not applicable by non-members to this product(NA), a possible - restriction for a non-member of the group to place on a bug in - this product(Shown), a default restriction for a non-member of the - group to place on a bug in this product(Default), or a mandatory - restriction to be placed on bugs in this product when entered by a - non-member(Mandatory). - 4. required in order to make any change to bugs in this product - including comments. - - To create Groups: - - 1. Select the "groups" link in the footer. - 2. Take a moment to understand the instructions on the "Edit Groups" - screen, then select the "Add Group" link. - 3. Fill out the "Group", "Description", and "User RegExp" fields. - "User RegExp" allows you to automatically place all users who - fulfill the Regular Expression into the new group. When you have - finished, click "Add". - - Warning - - If specifying a domain in the regexp, make sure you end the regexp - with a $. Otherwise, when granting access to "@mycompany\.com", you - will allow access to 'badperson@mycompany.com.cracker.net'. You need - to use '@mycompany\.com$' as the regexp. - 4. After you add your new group, edit the new group. On the edit - page, you can specify other groups that should be included in this - group and which groups should be permitted to add and delete users - from this group. - - Note that group permissions are such that you need to be a member of - all the groups a bug is in, for whatever reason, to see that bug. - Similarly, you must be a member of all of the entry groups for a - product to add bugs to a product and you must be a member of all of - the canedit groups for a product in order to make any change to bugs - in that product. - _________________________________________________________________ - -3.9. Upgrading to New Releases - - Warning - - Upgrading is a one-way process. You should backup your database and - current Bugzilla directory before attempting the upgrade. If you wish - to revert to the old Bugzilla version for any reason, you will have to - restore from these backups. - - Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors. - - * If the new version is a revision or a new point release - * How many, if any, local changes have been made - - There are also three different methods to upgrade your installation. - - 1. Using CVS (Example 3-1) - 2. Downloading a new tarball (Example 3-2) - 3. Applying the relevant patches (Example 3-3) - - Which options are available to you may depend on how large a jump you - are making and/or your network configuration. - - Revisions are normally released to fix security vulnerabilities and - are distinguished by an increase in the third number. For example, - when 2.16.2 was released, it was a revision to 2.16.1. - - Point releases are normally released when the Bugzilla team feels that - there has been a significant amount of progress made between the last - point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.16.2 is a newer point - release than 2.14.5. - - The examples in this section are written as if you were updating to - version 2.16.2. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point - release, escpecially if you've made local changes. - - These examples also assume that your Bugzilla installation is at - /var/www/html/bugzilla. If that is not the case, simply substitute the - proper paths where appropriate. - - Example 3-1. Upgrading using CVS - - Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. - - Tip - - If you can do this, updating using CVS is probably the most painless - method, especially if you have a lot of local changes. -bash$ cd /var/www/html/bugzilla -bash$ cvs login -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: anonymous -bash$ cvs -q update -r BUGZILLA-2_16_2 -dP -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - - Caution - - If a line in the output from cvs update begins with a C that - represents a file with local changes that CVS was unable to properly - merge. You need to resolve these conflicts manually before Bugzilla - (or at least the portion using that file) will be usable. - - Note - - You also need to run ./checksetup.pl before your Bugzilla upgrade will - be complete. - - Example 3-2. Upgrading using the tarball - - If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. -bash$ cd /var/www/html -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz -Output omitted -bash$ tar xzvf bugzilla-2.16.2.tar.gz -bugzilla-2.16.2/ -bugzilla-2.16.2/.cvsignore -bugzilla-2.16.2/1x1.gif -Output truncated -bash$ cd bugzilla-2.16.2 -bash$ cp ../bugzilla/localconfig* . -bash$ cp -r ../bugzilla/data . -bash$ cd .. -bash$ mv bugzilla bugzilla.old -bash$ mv bugzilla-2.16.2 bugzilla -bash$ cd bugzilla -bash$ ./checksetup.pl -Output omitted - - Warning - - The cp commands both end with periods which is a very important - detail, it tells the shell that the destination directory is the - current working directory. Also, the period at the beginning of the - ./checksetup.pl is important and can not be omitted. - - Note - - You will now have to reapply any changes you have made to your local - installation manually. - - Example 3-3. Upgrading using patches - - The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You - could also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in. It is also - theoretically possible to scour the fixed bug list and pick and choose - which patches to apply from a point release, but this is not - recommended either as what you'll end up with is a hodge podge - Bugzilla that isn't really any version. This would also make it more - difficult to upgrade in the future. -bash$ cd /var/www/html/bugzilla -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz -Output omitted -bash$ gunzip bugzilla-2.16.1-to-2.16.2.diff.gz -bash$ patch -p1 < bugzilla-2.16.1-to-2.16.2.diff -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - - Caution - - If you do this, beware that this doesn't change the entires in your - CVS directory so it may make updates using CVS (Example 3-1) more - difficult in the future. - _________________________________________________________________ - -Chapter 4. Customising Bugzilla - -4.1. Template Customization - - Administrators can 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. - - Templatization also makes localized versions of Bugzilla possible, for - the first time. It's possible to have Bugzilla's UI language - determined by the user's browser. More information is available in - Section 4.1.5. - _________________________________________________________________ - -4.1.1. What to Edit - - The template directory structure is that there's a top level - directory, template, which contains a directory for each installed - localization. The default English templates are therefore in en. - Underneath that, there is the default directory and optionally the - custom directory. The default directory contains all the templates - shipped with Bugzilla, whereas the custom directory does not exist at - first and must be created if you want to use it. - - There are two different ways of editing Bugzilla's templates, and - which you use depends mainly on the method you plan to use to upgrade - Bugzilla. The first method of making customizations is to directly - edit the templates in template/en/default. This is probably the best - method for small changes if you are going to use the CVS method of - upgrading, because if you then execute a cvs update, any template - fixes will get automagically merged into your modified versions. - - If you use this method, your installation will break if CVS conflicts - occur. - - The other method is to copy the templates to be modified into a - mirrored directory structure under template/en/custom. The templates - in this directory automatically override those in default. This is the - technique you need to use if you use the overwriting method of - upgrade, because otherwise your changes will be lost. This method is - also better if you are using the CVS method of upgrading and 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. - - If you use this method, your installation may break if incompatible - changes are made to the template interface. If such changes are made - they will be documented in the release notes, provided you are using a - stable release of Bugzilla. If you use using unstable code, you will - need to deal with this one yourself, although if possible the changes - will be mentioned before they occur in the deprecations section of the - previous stable release's release notes. - - Note - - Don't directly edit the compiled templates in data/template/* - your - changes will be lost when Template Toolkit recompiles them. - - Note - - It is recommended that you run ./checksetup.pl after any template - edits, especially if you've created a new file in the custom - directory. - _________________________________________________________________ - -4.1.2. How To Edit Templates - - Note - - If you are making template changes that you intend on submitting back - for inclusion in standard Bugzilla, you should read the relevant - sections of the Developers' Guide. - - 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. - - One thing you should take particular care about is the need to - properly HTML filter data that has been passed into the template. This - means that if the data can possibly contain special HTML characters - such as <, and the data was not intended to be HTML, they need to be - converted to entity form, ie <. You use the 'html' filter in the - Template Toolkit to do this. If you forget, you may open up your - installation to cross-site scripting attacks. - - Also note that Bugzilla adds a few filters of its own, that are not in - standard Template Toolkit. In particular, the 'url_quote' filter can - convert characters that are illegal or have special meaning in URLs, - such as &, to the encoded form, ie %26. This actually encodes most - characters (but not the common ones such as letters and numbers and so - on), including the HTML-special characters, so there's never a need to - HTML filter afterwards. - - Editing templates is a good way of doing a "poor man's custom fields". - For example, if you don't use the Status Whiteboard, but want to have - a free-form text entry box for "Build Identifier", then you can just - edit the templates to change the field labels. It's still be called - status_whiteboard internally, but your users don't need to know that. - _________________________________________________________________ - -4.1.3. Template Formats - - 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 - "GetFormat". If it's not present, adding multiple format support isn't - too hard - see how it's done in other CGIs, e.g. config.cgi. - - 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 -..tmpl. - Try out the template by calling the CGI as - .cgi?format= . - _________________________________________________________________ - -4.1.4. Particular Templates - - There are a few templates you may be particularly interested in - customizing for your installation. - - index.html.tmpl: This is the Bugzilla front page. - - global/header.html.tmpl: This defines the header that goes on all - Bugzilla pages. The header includes the banner, which is what appears - to users and is probably what you want to edit instead. However the - header also includes the HTML HEAD section, so you could for example - add a stylesheet or META tag by editing the header. - - global/banner.html.tmpl: This contains the "banner", the part of the - header that appears at the top of all Bugzilla pages. The default - banner is reasonably barren, so you'll probably want to customize this - to give your installation a distinctive look and feel. It is - recommended you preserve the Bugzilla version number in some form so - the version you are running can be determined, and users know what - docs to read. - - global/footer.html.tmpl: This defines the footer that goes on all - Bugzilla pages. Editing this is another way to quickly get a - distinctive look and feel for your Bugzilla installation. - - bug/create/user-message.html.tmpl: This is a message that appears near - the top of the bug reporting page. By modifying this, you can tell - your users how they should report bugs. - - bug/create/create.html.tmpl and bug/create/comment.txt.tmpl: You may - wish to get bug submitters to give certain bits of structured - information, each in a separate input widget, for which there is not a - field in the database. The bug entry system has been designed in an - extensible fashion to enable you to define arbitrary fields and - widgets, and have their values appear formatted in the initial - Description, rather than in database fields. An example of this is the - mozilla.org guided bug submission form. - - To make this work, create a custom template for enter_bug.cgi (the - default template, on which you could base it, is create.html.tmpl), - and either call it create.html.tmpl or use a format and call it - create-.html.tmpl. Put it in the custom/bug/create - directory. In it, add widgets for each piece of information you'd like - collected - such as a build number, or set of steps to reproduce. - - Then, create a template like custom/bug/create/comment.txt.tmpl, also - named after your format if you are using one, which references the - form fields you have created. When a bug report is submitted, the - initial comment attached to the bug report will be formatted according - to the layout of this template. - - For example, if your enter_bug template had a field - - - and then your comment.txt.tmpl had - BuildID: [% form.buildid %] - - then - BuildID: 20020303 - - would appear in the initial checkin comment. - _________________________________________________________________ - -4.1.5. Configuring Bugzilla to Detect the User's Language - - Bugzilla honours the user's Accept: HTTP header. You can install - templates in other languages, and Bugzilla will pick the most - appropriate according to a priority order defined by you. Many - language templates can be obtained from - http://www.bugzilla.org/download.html#localizations. Instructions for - submitting new languages are also available from that location. - - After untarring the localizations (or creating your own) in the - BUGZILLA_ROOT/template directory, you must update the languages - parameter to contain any localizations you'd like to permit. You may - also wish to set the defaultlanguage parameter to something other than - "en" if you don't want Engish to be the default language. - _________________________________________________________________ - -4.2. Template Hooks - - Template hooks are a way for extensions to Bugzilla to insert code - into the standard Bugzilla templates without modifying the template - files themselves. The hooks mechanism defines a consistent API for - extending the standard templates in a way that cleanly separates - standard code from extension code. Hooks reduce merge conflicts and - make it easier to write extensions that work across multiple versions - of Bugzilla, making upgrading a Bugzilla installation with installed - extensions easier. - - A template hook is just a named place in a standard template file - where extension template files for that hook get processed. Each hook - has a corresponding directory in the Bugzilla directory tree. Hooking - an extension template to a hook is as simple as putting the extension - file into the hook's directory. When Bugzilla processes the standard - template and reaches the hook, it will process all extension templates - in the hook's directory. The hooks themselves can be added into any - standard template upon request by extension authors. - - To use hooks to extend a Bugzilla template, first make sure there is a - hook at the appropriate place within the template you want to extend. - Hooks appear in the standard Bugzilla templates as a single directive - in the format [% Hook.process("name") %], where name is the unique - (within that template) name of the hook. - - If you aren't sure which template you want to extend or just want to - browse the available hooks, either use your favorite multi-file search - tool (e.g. grep) to search the standard templates for occurrences of - Hook.process or browse the directory tree in - BUGZILLA_ROOT/template/en/extension/hook/, which contains a directory - for each hook in the following location: - - BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STA - NDARD_TEMPLATE_NAME/HOOK_NAME/ - - If there is no hook at the appropriate place within the Bugzilla - template you want to extend, file a bug requesting one, specifying: - - the template for which you are requesting a hook; - where in the template you would like the hook to be placed (line - number/position for latest version of template in CVS or description - of location); - the purpose of the hook; - a link to information about your extension, if any. - - The Bugzilla reviewers will promptly review each hook request, name - the hook, add it to the template, check the new version of the - template into CVS, and create the corresponding directory in - BUGZILLA_ROOT/template/en/extension/hook/. - - You may optionally attach a patch to the bug which implements the hook - and check it in yourself after receiving approval from a Bugzilla - reviewer. The developers may suggest changes to the location of the - hook based on their analysis of your needs or so the hook can satisfy - the needs of multiple extensions, but the process of getting hooks - approved and checked in is not as stringent as the process for general - changes to Bugzilla, and any extension, whether released or still in - development, can have hooks added to meet their needs. - - After making sure the hook you need exists (or getting it added if - not), add your extension template to the directory within the Bugzilla - directory tree corresponding to the hook. - - That's it! Now, when the standard template containing the hook is - processed, your extension template will be processed at the point - where the hook appears. - - For example, let's say you have an extension named Projman that adds - project management capabilities to Bugzilla. Projman has an - administration interface edit-projects.cgi, and you want to add a link - to it into the navigation bar at the bottom of every Bugzilla page for - those users who are authorized to administer projects. - - The navigation bar is generated by the template file - useful-links.html.tmpl, which is located in the global/ subdirectory - on the standard Bugzilla template path - BUGZILLA_ROOT/template/en/default/. Looking in useful-links.html.tmpl, - you find the following hook at the end of the list of standard - Bugzilla administration links: -... - [% ', keywords' - IF user.groups.editkeywords %] - [% Hook.process("edit") %] -... - - The corresponding directory for this hook is - BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl - /edit/. - - You put a template named projman-edit-projects.html.tmpl into that - directory with the following content: -...[% ', projects' IF user.groups.projman_admin -s %] - - Voila! The link now appears after the other administration links in - the navigation bar for users in the projman_admins group. - - Notes: - - * You may want to prefix your extension template names with the name - of your extension, e.g. projman-foo.html.tmpl, so they do not - conflict with the names of templates installed by other - extensions. - * If your extension includes entirely new templates in addition to - extensions of standard templates, it should install those new - templates into an extension-specific subdirectory of the - BUGZILLA_ROOT/template/en/extension/ directory. The extension/ - directory, like the default/ and custom/ directories, is part of - the template search path, so putting templates there enables them - to be found by the template processor. - The template processor looks for templates first in the custom/ - directory (i.e. templates added by the specific installation), - then in the extension/ directory (i.e. templates added by - extensions), and finally in the default/ directory (i.e. the - standard Bugzilla templates). Thus extension templates can - override standard templates, but installation-specific templates - override both. - Note that overriding standard templates with extension templates - gives you great power but also makes upgrading an installation - harder. As with custom templates, we recommend using this - functionality sparingly and only when absolutely necessary. - * Installation customizers can also take advantage of hooks when - adding code to a Bugzilla template. To do so, create directories - in BUGZILLA_ROOT/template/en/custom/hook/ equivalent to the - directories in BUGZILLA_ROOT/template/en/extension/hook/ for the - hooks you want to use, then place your customization templates - into those directories. - Obviously this method of customizing Bugzilla only lets you add - code to the standard templates; you cannot change the existing - code. Nevertheless, for those customizations that only add code, - this method can reduce conflicts when merging changes, making - upgrading your customized Bugzilla installation easier. - _________________________________________________________________ - -4.3. Customizing Who Can Change What - - Warning - - This feature should be considered experimental; the Bugzilla code you - will be changing is not stable, and could change or move between - versions. Be aware that if you make modifications as outlined here, - you may have to re-make them or port them if Bugzilla changes - internally between versions, and you upgrade. - - Companies often have rules about which employees, or classes of - employees, are allowed to change certain things in the bug system. For - example, only the bug's designated QA Contact may be allowed to VERIFY - the bug. Bugzilla has been designed to make it easy for you to write - your own custom rules to define who is allowed to make what sorts of - value transition. - - For maximum flexibility, customizing this means editing Bugzilla's - Perl code. This gives the administrator complete control over exactly - who is allowed to do what. The relevant function is called - CheckCanChangeField(), and is found in process_bug.cgi in your - Bugzilla directory. If you open that file and grep for "sub - CheckCanChangeField", you'll find it. - - This function has been carefully commented to allow you to see exactly - how it works, and give you an idea of how to make changes to it. - Certain marked sections should not be changed - these are the - "plumbing" which makes the rest of the function work. In between those - sections, you'll find snippets of code like: - # Allow the owner to change anything. - if ($ownerid eq $whoid) { - return 1; - } - - It's fairly obvious what this piece of code does. - - So, how does one go about changing this function? Well, simple changes - can be made just be removing pieces - for example, if you wanted to - prevent any user adding a comment to a bug, just remove the lines - marked "Allow anyone to change comments." And if you want the reporter - to have no special rights on bugs they have filed, just remove the - entire section which refers to him. - - More complex customizations are not much harder. Basically, you add a - check in the right place in the function, i.e. after all the variables - you are using have been set up. So, don't look at $ownerid before - $ownerid has been obtained from the database. You can either add a - positive check, which returns 1 (allow) if certain conditions are - true, or a negative check, which returns 0 (deny.) E.g.: - if ($field eq "qacontact") { - if (Bugzilla->user->groups("quality_assurance")) { - return 1; - } - else { - return 0; - } - } - - This says that only users in the group "quality_assurance" can change - the QA Contact field of a bug. Getting more weird: - if (($field eq "priority") && - (Bugzilla->user->email =~ /.*\@example\.com$/)) - { - if ($oldvalue eq "P1") { - return 1; - } - else { - return 0; - } - } - - This says that if the user is trying to change the priority field, and - their email address is @example.com, they can only do so if the old - value of the field was "P1". Not very useful, but illustrative. - - For a list of possible field names, look in data/versioncache for the - list called @::log_columns. If you need help writing custom rules for - your organization, ask in the newsgroup. - _________________________________________________________________ - -4.4. Modifying Your Running System - - Bugzilla optimizes database lookups by storing all relatively static - information in the versioncache file, located in the data/ - subdirectory under your installation directory. - - If you make a change to the structural data in your database (the - versions table for example), or to the "constants" encoded in - defparams.pl, you will need to remove the cached content from the data - directory (by doing a "rm data/versioncache" ), or your changes won't - show up. - - versioncache gets automatically regenerated whenever it's more than an - hour old, so Bugzilla will eventually notice your changes by itself, - but generally you want it to notice right away, so that you can test - things. - _________________________________________________________________ - -4.5. MySQL Bugzilla Database Introduction - - This information comes straight from my life. I was forced to learn - how Bugzilla organizes database because of nitpicky requests from - users for tiny changes in wording, rather than having people - re-educate themselves or figure out how to work our procedures around - the tool. It sucks, but it can and will happen to you, so learn how - the schema works and deal with it when it comes. - - So, here you are with your brand-new installation of Bugzilla. You've - got MySQL set up, Apache working right, Perl DBI and DBD talking to - the database flawlessly. Maybe you've even entered a few test bugs to - make sure email's working; people seem to be notified of new bugs and - changes, and you can enter and edit bugs to your heart's content. - Perhaps you've gone through the trouble of setting up a gateway for - people to submit bugs to your database via email, have had a few - people test it, and received rave reviews from your beta testers. - - What's the next thing you do? Outline a training strategy for your - development team, of course, and bring them up to speed on the new - tool you've labored over for hours. - - Your first training session starts off very well! You have a captive - audience which seems enraptured by the efficiency embodied in this - thing called "Bugzilla". You are caught up describing the nifty - features, how people can save favorite queries in the database, set - them up as headers and footers on their pages, customize their - layouts, generate reports, track status with greater efficiency than - ever before, leap tall buildings with a single bound and rescue Jane - from the clutches of Certain Death! - - But Certain Death speaks up -- a tiny voice, from the dark corners of - the conference room. "I have a concern," the voice hisses from the - darkness, "about the use of the word 'verified'." - - The room, previously filled with happy chatter, lapses into - reverential silence as Certain Death (better known as the Vice - President of Software Engineering) continues. "You see, for two years - we've used the word 'verified' to indicate that a developer or quality - assurance engineer has confirmed that, in fact, a bug is valid. I - don't want to lose two years of training to a new software product. - You need to change the bug status of 'verified' to 'approved' as soon - as possible. To avoid confusion, of course." - - Oh no! Terror strikes your heart, as you find yourself mumbling "yes, - yes, I don't think that would be a problem," You review the changes - with Certain Death, and continue to jabber on, "no, it's not too big a - change. I mean, we have the source code, right? You know, 'Use the - Source, Luke' and all that... no problem," All the while you quiver - inside like a beached jellyfish bubbling, burbling, and boiling on a - hot Jamaican sand dune... - - Thus begins your adventure into the heart of Bugzilla. You've been - forced to learn about non-portable enum() fields, varchar columns, and - tinyint definitions. The Adventure Awaits You! - _________________________________________________________________ - -4.5.1. Bugzilla Database Basics - - If you were like me, at this point you're totally clueless about the - internals of MySQL, and if it weren't for this executive order from - the Vice President you couldn't care less about the difference between - a "bigint" and a "tinyint" entry in MySQL. I recommend you refer to - the MySQL documentation . Below are the basics you need to know about - the Bugzilla database. Check the chart above for more details. - - 1. To connect to your database: - bash# mysql -u root - If this works without asking you for a password, shame on you ! - You should have locked your security down like the installation - instructions told you to. You can find details on locking down - your database in the Bugzilla FAQ in this directory (under - "Security"), or more robust security generalities in the MySQL - searchable documentation. - 2. You should now be at a prompt that looks like this: - mysql> - At the prompt, if "bugs" is the name you chose in the localconfig - file for your Bugzilla database, type: - mysql use bugs; - _________________________________________________________________ - -4.5.1.1. Bugzilla Database Tables - - Imagine your MySQL database as a series of spreadsheets, and you won't - be too far off. If you use this command: - - mysql> show tables from bugs; - - you'll be able to see the names of all the "spreadsheets" (tables) in - your database. - - From the command issued above, ou should have some output that looks - like this: -+-------------------+ -| Tables in bugs | -+-------------------+ -| attachments | -| bugs | -| bugs_activity | -| cc | -| components | -| dependencies | -| fielddefs | -| groups | -| keyworddefs | -| keywords | -| logincookies | -| longdescs | -| milestones | -| namedqueries | -| products | -| profiles | -| profiles_activity | -| tokens | -| versions | -| votes | -| watch | -+-------------------+ - - Here's an overview of what each table does. Most columns in each tab - le have - descriptive names that make it fairly trivial to figure out their jobs - . - attachments: This table stores all attachments to bugs. It tends to be - your - largest table, yet also generally has the fewest entries because file - attachments are so (relatively) large. - bugs: This is the core of your system. The bugs table stores most of - the - current information about a bug, with the exception of the info stored - in the - other tables. - bugs_activity: This stores information regarding what changes are mad - e to bugs - when -- a history file. - cc: This tiny table simply stores all the CC information for any bug - which has - any entries in the CC field of the bug. Note that, like most other tab - les in - Bugzilla, it does not refer to users by their user names, but by their - unique - userid, stored as a primary key in the profiles table. - components: This stores the programs and components (or products and - components, in newer Bugzilla parlance) for Bugzilla. Curiously, the " - program" - (product) field is the full name of the product, rather than some othe - r unique - identifier, like bug_id and user_id are elsewhere in the database. - dependencies: Stores data about those cool dependency trees. - fielddefs: A nifty table that defines other tables. For instance, whe - n you - submit a form that changes the value of "AssignedTo" this table allows - translation to the actual field name "assigned_to" for entry into MySQ - L. - groups: defines bitmasks for groups. A bitmask is a number that can u - niquely - identify group memberships. For instance, say the group that is allowe - d to - tweak parameters is assigned a value of "1", the group that is allowed - to edit - users is assigned a "2", and the group that is allowed to create new g - roups is - assigned the bitmask of "4". By uniquely combining the group bitmasks - (much - like the chmod command in UNIX,) you can identify a user is allowed to - tweak - parameters and create groups, but not edit users, by giving him a bitm - ask of - "5", or a user allowed to edit users and create groups, but not tweak - parameters, by giving him a bitmask of "6" Simple, huh? - If this makes no sense to you, try this at the mysql prompt: - mysql> select * from groups; - You'll see the list, it makes much more sense that way. - keyworddefs: Definitions of keywords to be used - keywords: Unlike what you'd think, this table holds which keywords are - associated with which bug id's. - logincookies: This stores every login cookie ever assigned to you for - every - machine you've ever logged into Bugzilla from. Curiously, it never doe - s any - housecleaning -- I see cookies in this file I've not used for months. - However, - since Bugzilla never expires your cookie (for convenience' sake), it m - akes - sense. - longdescs: The meat of bugzilla -- here is where all user comments ar - e stored! - You've only got 2^24 bytes per comment (it's a mediumtext field), so s - peak - sparingly -- that's only the amount of space the Old Testament from th - e Bible - would take (uncompressed, 16 megabytes). Each comment is keyed to the - bug_id to which it's attached, so the order is necessarily chronologic - al, for - comments are played back in the order in which they are received. - milestones: Interesting that milestones are associated with a specifi - c product - in this table, but Bugzilla does not yet support differing milestones - by - product through the standard configuration interfaces. - namedqueries: This is where everybody stores their "custom queries". - Very - cool feature; it beats the tar out of having to bookmark each cool que - ry you - construct. - products: What products you have, whether new bug entries are allowed - for the - product, what milestone you're working toward on that product, votes, - etc. It - will be nice when the components table supports these same features, s - o you - could close a particular component for bug entry without having to clo - se an - entire product... - profiles: Ahh, so you were wondering where your precious user informa - tion was - stored? Here it is! With the passwords in plain text for all to see! - (but - sshh... don't tell your users!) - profiles_activity: Need to know who did what when to who's profile? - This'll - tell you, it's a pretty complete history. - versions: Version information for every product - votes: Who voted for what when - watch: Who (according to userid) is watching who's bugs (according to - their - userid). - === - THE DETAILS - === - Ahh, so you're wondering just what to do with the information above? - At the - mysql prompt, you can view any information about the columns in a tabl - e with - this command (where "table" is the name of the table you wish to view) - : - mysql> show columns from table; - You can also view all the data in a table with this command: - mysql> select * from table; - -- note: this is a very bad idea to do on, for instance, the "bugs" - table if - you have 50,000 bugs. You'll be sitting there a while until you ctrl-c - or - 50,000 bugs play across your screen. - You can limit the display from above a little with the command, wher - e - "column" is the name of the column for which you wish to restrict info - rmation: - mysql> select * from table where (column = "some info"); - -- or the reverse of this - mysql> select * from table where (column != "some info"); - Let's take our example from the introduction, and assume you need to - change - the word "verified" to "approved" in the resolution field. We know fro - m the - above information that the resolution is likely to be stored in the "b - ugs" - table. Note we'll need to change a little perl code as well as this da - tabase - change, but I won't plunge into that in this document. Let's verify th - e - information is stored in the "bugs" table: - mysql> show columns from bugs - (exceedingly long output truncated here) - | bug_status| enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED - ','VERIFIED','CLOSED')||MUL | UNCONFIRMED|| - Sorry about that long line. We see from this that the "bug status" c - olumn is - an "enum field", which is a MySQL peculiarity where a string type fiel - d can - only have certain types of entries. While I think this is very cool, i - t's not - standard SQL. Anyway, we need to add the possible enum field entry - 'APPROVED' by altering the "bugs" table. - mysql> ALTER table bugs CHANGE bug_status bug_status - -> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED", - -> "VERIFIED", "APPROVED", "CLOSED") not null; - (note we can take three lines or more -- whatever you put in befor - e the - semicolon is evaluated as a single expression) - Now if you do this: - mysql> show columns from bugs; - you'll see that the bug_status field has an extra "APPROVED" enum th - at's - available! Cool thing, too, is that this is reflected on your query p - age as - well -- you can query by the new status. But how's it fit into the exi - sting - scheme of things? - Looks like you need to go back and look for instances of the word "v - erified" - in the perl code for Bugzilla -- wherever you find "verified", change - it to - "approved" and you're in business (make sure that's a case-insensitive - search). - Although you can query by the enum field, you can't give something a s - tatus - of "APPROVED" until you make the perl changes. Note that this change I - mentioned can also be done by editing checksetup.pl, which automates a - lot of - this. But you need to know this stuff anyway, right? - _________________________________________________________________ - -4.6. Integrating Bugzilla with Third-Party Tools - -4.6.1. Bonsai - - Bonsai is a web-based tool for managing CVS, the Concurrent Versioning - System . Using Bonsai, administrators can control open/closed status - of trees, query a fast relational database back-end for change, - branch, and comment information, and view changes made since the last - time the tree was closed. Bonsai also integrates with Tinderbox, the - Mozilla automated build management system. - _________________________________________________________________ - -4.6.2. CVS - - CVS integration is best accomplished, at this point, using the - Bugzilla Email Gateway. - - Follow the instructions in this Guide for enabling Bugzilla e-mail - integration. Ensure that your check-in script sends an email to your - Bugzilla e-mail gateway with the subject of "[Bug XXXX]", and you can - have CVS check-in comments append to your Bugzilla bug. If you want to - have the bug be closed automatically, you'll have to modify the - contrib/bugzilla_email_append.pl script. - - There is also a CVSZilla project, based upon somewhat dated Bugzilla - code, to integrate CVS and Bugzilla through CVS' ability to email. - Check it out at: http://homepages.kcbbs.gen.nz/~tonyg/. - _________________________________________________________________ - -4.6.3. Perforce SCM - - You can find the project page for Bugzilla and Teamtrack Perforce - integration (p4dti) at: http://www.ravenbrook.com/project/p4dti/ . - "p4dti" is now an officially supported product from Perforce, and you - can find the "Perforce Public Depot" p4dti page at - http://public.perforce.com/public/perforce/p4dti/index.html . - - Integration of Perforce with Bugzilla, once patches are applied, is - seamless. Perforce replication information will appear below the - comments of each bug. Be certain you have a matching set of patches - for the Bugzilla version you are installing. p4dti is designed to - support multiple defect trackers, and maintains its own documentation - for it. Please consult the pages linked above for further information. - _________________________________________________________________ - -4.6.4. Tinderbox/Tinderbox2 - - Tinderbox is a continuous-build system which can integrate with - Bugzilla - see http://www.mozilla.org/projects/tinderbox for details - of Tinderbox, and http://tinderbox.mozilla.org/showbuilds.cgi to see - it in action. - _________________________________________________________________ - -Chapter 5. Using Bugzilla - -5.1. Introduction - - This section contains information for end-users of Bugzilla. There is - a Bugzilla test installation, called Landfill, which you are welcome - to play with (if it's up.) However, it does not necessarily have all - Bugzilla features enabled, and runs an up-to-the-minute version, so - some things may not quite work as this document describes. - _________________________________________________________________ - -5.2. Create a Bugzilla Account - - If you want to use Bugzilla, first you need to create an account. - Consult with the administrator responsible for your installation of - Bugzilla for the URL you should use to access it. If you're - test-driving Bugzilla, use this URL: - http://landfill.bugzilla.org/bugzilla-tip/. - - 1. Click the "Open a new Bugzilla account" link, enter your email - address and, optionally, your name in the spaces provided, then - click "Create Account" . - 2. Within moments, you should receive an email to the address you - provided, which contains your login name (generally the same as - the email address), and a password. This password is randomly - generated, but can be changed to something more memorable. - 3. Click the "Log In" link in the footer at the bottom of the page in - your browser, enter your email address and password into the - spaces provided, and click "Login". - - You are now logged in. Bugzilla uses cookies to remember you are - logged in so, unless you have cookies disabled or your IP address - changes, you should not have to log in again. - _________________________________________________________________ - -5.3. Anatomy of a Bug - - The core of Bugzilla is the screen which displays a particular bug. - It's a good place to explain some Bugzilla concepts. Bug 1 on Landfill - is a good example. Note that the labels for most fields are - hyperlinks; clicking them will take you to context-sensitive help on - that particular field. Fields marked * may not be present on every - installation of Bugzilla. - - 1. Product and Component: Bugs are divided up by Product and - Component, with a Product having one or more Components in it. For - example, bugzilla.mozilla.org's "Bugzilla" Product is composed of - several Components: - - Administration: Administration of a Bugzilla installation. - Bugzilla-General: Anything that doesn't fit in the other components, - or spans multiple components. - Creating/Changing Bugs: Creating, changing, and viewing bugs. - Documentation: The Bugzilla documentation, including The Bugzilla - Guide. - Email: Anything to do with email sent by Bugzilla. - Installation: The installation process of Bugzilla. - Query/Buglist: Anything to do with searching for bugs and viewing the - buglists. - Reporting/Charting: Getting reports from Bugzilla. - User Accounts: Anything about managing a user account from the user's - perspective. Saved queries, creating accounts, changing passwords, - logging in, etc. - User Interface: General issues having to do with the user interface - cosmetics (not functionality) including cosmetic issues, HTML - templates, etc. - 2. Status and Resolution: These define exactly what state the bug is - in - from not even being confirmed as a bug, through to being - fixed and the fix confirmed by Quality Assurance. The different - possible values for Status and Resolution on your installation - should be documented in the context-sensitive help for those - items. - 3. Assigned To: The person responsible for fixing the bug. - 4. *URL: A URL associated with the bug, if any. - 5. Summary: A one-sentence summary of the problem. - 6. *Status Whiteboard: (a.k.a. Whiteboard) A free-form text area for - adding short notes and tags to a bug. - 7. *Keywords: The administrator can define keywords which you can use - to tag and categorise bugs - e.g. The Mozilla Project has keywords - like crash and regression. - 8. Platform and OS: These indicate the computing environment where - the bug was found. - 9. Version: The "Version" field is usually used for versions of a - product which have been released, and is set to indicate which - versions of a Component have the particular problem the bug report - is about. - 10. Priority: The bug assignee uses this field to prioritise his or - her bugs. It's a good idea not to change this on other people's - bugs. - 11. Severity: This indicates how severe the problem is - from blocker - ("application unusable") to trivial ("minor cosmetic issue"). You - can also use this field to indicate whether a bug is an - enhancement request. - 12. *Target: (a.k.a. Target Milestone) A future version by which the - bug is to be fixed. e.g. The Bugzilla Project's milestones for - future Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are - not restricted to numbers, thought - you can use any text strings, - such as dates. - 13. Reporter: The person who filed the bug. - 14. CC list: A list of people who get mail when the bug changes. - 15. Attachments: You can attach files (e.g. testcases or patches) to - bugs. If there are any attachments, they are listed in this - section. - 16. *Dependencies: If this bug cannot be fixed unless other bugs are - fixed (depends on), or this bug stops other bugs being fixed - (blocks), their numbers are recorded here. - 17. *Votes: Whether this bug has any votes. - 18. Additional Comments: You can add your two cents to the bug - discussion here, if you have something worthwhile to say. - _________________________________________________________________ - -5.4. Searching for Bugs - - The Bugzilla Search page is is the interface where you can find any - bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - http://landfill.bugzilla.org/bugzilla-tip/query.cgi. - - The Search page has controls for selecting different possible values - for all of the fields in a bug, as described above. For some fields, - multiple values can be selected. In those cases, Bugzilla returns bugs - where the content of the field matches any one of the selected values. - If none is selected, then the field can take any value. - - Once you've run a search, you can save it as a Saved Search, which - appears in the page footer. - - Highly advanced querying is done using Boolean Charts. See the Boolean - Charts help link on the Search page for more information. - _________________________________________________________________ - -5.5. Bug Lists - - If you run a search, a list of matching bugs will be returned. - - The format of the list is configurable. For example, it can be sorted - by clicking the column headings. Other useful features can be accessed - using the links at the bottom of the list: - - Long Format: this gives you a large page with a non-editable summary - of the fields of each bug. - CSV: get the buglist as comma-separated values, for import into e.g. a - spreadsheet. - Change Columns: change the bug attributes which appear in the list. - Change several bugs at once: If your account is sufficiently - empowered, you can make the same change to all the bugs in the list - - for example, changing their owner. - Send mail to bug owners: Sends mail to the owners of all bugs on the - list. - Edit Search: If you didn't get exactly the results you were looking - for, you can return to the Query page through this link and make small - revisions to the query you just made so you get more accurate results. - Remember Search As: You can give a search a name and remember it; a - link will appear in your page footer giving you quick access to run it - again later. - _________________________________________________________________ - -5.6. Filing Bugs - - Years of bug writing experience has been distilled for your reading - pleasure into the Bug Writing Guidelines. While some of the advice is - Mozilla-specific, the basic principles of reporting Reproducible, - Specific bugs, isolating the Product you are using, the Version of the - Product, the Component which failed, the Hardware Platform, and - Operating System you were using at the time of the failure go a long - way toward ensuring accurate, responsible fixes for the bug that bit - you. - - The procedure for filing a test bug is as follows: - - 1. Go to Landfill in your browser and click Enter a new bug report. - 2. Select a product - any one will do. - 3. Fill in the fields. Bugzilla should have made reasonable guesses, - based upon your browser, for the "Platform" and "OS" drop-down - boxes. If they are wrong, change them. - 4. Select "Commit" and send in your bug report. - - 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. - _________________________________________________________________ - -5.7. Patch Viewer - - Viewing and reviewing patches in Bugzilla is often difficult due to - lack of context, improper format and the inherent readability issues - that raw patches present. Patch Viewer is an enhancement to Bugzilla - designed to fix that by offering increased context, linking to - sections, and integrating with Bonsai, LXR and CVS. - - Patch viewer allows you to: - - View patches in color, with side-by-side view rather than trying to - interpret the contents of the patch. - See the difference between two patches. - Get more context in a patch. - Collapse and expand sections of a patch for easy reading. - Link to a particular section of a patch for discussion or review - Go to Bonsai or LXR to see more context, blame, and cross-references - for the part of the patch you are looking at - Create a rawtext unified format diff out of any patch, no matter what - format it came from - _________________________________________________________________ - -5.7.1. Viewing Patches in Patch Viewer - - The main way to view a patch in patch viewer is to click on the "Diff" - link next to a patch in the Attachments list on a bug. You may also do - this within the edit window by clicking the "View Attachment As Diff" - button in the Edit Attachment screen. - _________________________________________________________________ - -5.7.2. Seeing the Difference Between Two Patches - - To see the difference between two patches, you must first view the - newer patch in Patch Viewer. Then select the older patch from the - dropdown at the top of the page ("Differences between [dropdown] and - this patch") and click the "Diff" button. This will show you what is - new or changed in the newer patch. - _________________________________________________________________ - -5.7.3. Getting More Context in a Patch - - To get more context in a patch, you put a number in the textbox at the - top of Patch Viewer ("Patch / File / [textbox]") and hit enter. This - will give you that many lines of context before and after each change. - Alternatively, you can click on the "File" link there and it will show - each change in the full context of the file. This feature only works - against files that were diffed using "cvs diff". - _________________________________________________________________ - -5.7.4. Collapsing and Expanding Sections of a Patch - - To view only a certain set of files in a patch (for example, if a - patch is absolutely huge and you want to only review part of it at a - time), you can click the "(+)" and "(-)" links next to each file (to - expand it or collapse it). If you want to collapse all files or expand - all files, you can click the "Collapse All" and "Expand All" links at - the top of the page. - _________________________________________________________________ - -5.7.5. Linking to a Section of a Patch - - To link to a section of a patch (for example, if you want to be able - to give someone a URL to show them which part you are talking about) - you simply click the "Link Here" link on the section header. The - resulting URL can be copied and used in discussion. (Copy Link - Location in Mozilla works as well.) - _________________________________________________________________ - -5.7.6. Going to Bonsai and LXR - - To go to Bonsai to get blame for the lines you are interested in, you - can click the "Lines XX-YY" link on the section header you are - interested in. This works even if the patch is against an old version - of the file, since Bonsai stores all versions of the file. - - To go to LXR, you click on the filename on the file header - (unfortunately, since LXR only does the most recent version, line - numbers are likely to rot). - _________________________________________________________________ - -5.7.7. Creating a Unified Diff - - If the patch is not in a format that you like, you can turn it into a - unified diff format by clicking the "Raw Unified" link at the top of - the page. - _________________________________________________________________ - -5.8. Hints and Tips - - This section distills some Bugzilla tips and best practices that have - been developed. - _________________________________________________________________ - -5.8.1. Autolinkification - - Bugzilla comments are plain text - so typing will produce - less-than, U, greater-than rather than underlined text. 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 a link: http://www.bugzilla.org. Other strings which - get linkified in the obvious manner are: - - bug 12345 - comment 7 - bug 23456, comment 53 - attachment 4321 - mailto:george@example.com - 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. - _________________________________________________________________ - -5.8.2. Quicksearch - - 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. - _________________________________________________________________ - -5.8.3. Comments - - 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 can set 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, - if you do it out of habit, but full mail/news-style four line ASCII - art creations are not. - _________________________________________________________________ - -5.8.4. Attachments - - 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, one CSS file and - an 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. - _________________________________________________________________ - -5.9. User Preferences - - 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 three tabs: - _________________________________________________________________ - -5.9.1. Account Settings - - 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. - _________________________________________________________________ - -5.9.2. Email Settings - - 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. - - You can also do further filtering on the client side by using the - X-Bugzilla-Reason mail header which Bugzilla adds to all bugmail. This - tells you what relationship you have to the bug in question, and can - be any of Owner, Reporter, QAcontact, CClist, Voter and - WatchingComponent. - - 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 or users go on holiday. - - Note - - The ability to watch other users may not be available in all Bugzilla - installations. If you can't see it, ask your administrator. - _________________________________________________________________ - -5.9.3. Permissions - - 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. - _________________________________________________________________ - -5.10. Reports - - To be written - _________________________________________________________________ - -Appendix A. The Bugzilla FAQ - - This FAQ includes questions not covered elsewhere in the Guide. - - 1. General Questions - - A.1.1. What license is Bugzilla distributed under? - A.1.2. How do I get commercial support for Bugzilla? - A.1.3. What major companies or projects are currently using - Bugzilla for bug-tracking? - - A.1.4. Who maintains Bugzilla? - A.1.5. How does Bugzilla stack up against other bug-tracking - databases? - - A.1.6. Why doesn't Bugzilla offer this or that feature or - compatibility with this other tracking software? - - A.1.7. Why MySQL? I'm interested in seeing Bugzilla run on - Oracle/Sybase/Msql/PostgreSQL/MSSQL. - - A.1.8. What is /usr/bonsaitools/bin/perl? - A.1.9. My perl is not located at /usr/bin/perl, is there an easy - way to change it everywhere it needs to be changed? - - A.1.10. Is there an easy way to change the Bugzilla cookie name? - A.1.11. Does bugzilla run under mod_perl? - - 2. Managerial Questions - - A.2.1. Is Bugzilla web-based, or do you have to have specific - software or a specific operating system on your machine? - - A.2.2. Does Bugzilla allow us to define our own priorities and - levels? Do we have complete freedom to change the labels - of fields and format of them, and the choice of - acceptable values? - - A.2.3. Does Bugzilla provide any reporting features, metrics, - graphs, etc? You know, the type of stuff that management - likes to see. :) - - A.2.4. Is there email notification and if so, what do you see - when you get an email? - - A.2.5. Do users have to have any particular type of email - application? - - A.2.6. Does Bugzilla allow data to be imported and exported? If I - had outsiders write up a bug report using a MS Word bug - template, could that template be imported into "matching" - fields? If I wanted to take the results of a query and - export that data to MS Excel, could I do that? - - A.2.7. Has anyone converted Bugzilla to another language to be - used in other countries? Is it localizable? - - A.2.8. Can a user create and save reports? Can they do this in - Word format? Excel format? - - A.2.9. Does Bugzilla provide record locking when there is - simultaneous access to the same bug? Does the second - person get a notice that the bug is in use or how are - they notified? - - A.2.10. Are there any backup features provided? - A.2.11. Can users be on the system while a backup is in progress? - - A.2.12. What type of human resources are needed to be on staff to - install and maintain Bugzilla? Specifically, what type of - skills does the person need to have? I need to find out - if we were to go with Bugzilla, what types of individuals - would we need to hire and how much would that cost vs - buying an "out-of-the-box" solution? - - A.2.13. What time frame are we looking at if we decide to hire - people to install and maintain the Bugzilla? Is this - something that takes hours or weeks to install and a - couple of hours per week to maintain and customize or is - this a multi-week install process, plus a full time job - for 1 person, 2 people, etc? - - A.2.14. Is there any licensing fee or other fees for using - Bugzilla? Any out-of-pocket cost other than the bodies - needed as identified above? - - 3. Bugzilla Security - - A.3.1. How do I completely disable MySQL security if it's giving - me problems (I've followed the instructions in the - installation section of this guide)? - - A.3.2. Are there any security problems with Bugzilla? - - 4. Bugzilla Email - - A.4.1. I have a user who doesn't want to receive any more email - from Bugzilla. How do I stop it entirely for this user? - - A.4.2. I'm evaluating/testing Bugzilla, and don't want it to send - email to anyone but me. How do I do it? - - A.4.3. I want whineatnews.pl to whine at something other than new - and reopened bugs. How do I do it? - - A.4.4. How do I set up the email interface to submit/change bugs - via email? - - A.4.5. Email takes FOREVER to reach me from Bugzilla -- it's - extremely slow. What gives? - - A.4.6. How come email from Bugzilla changes never reaches me? - - 5. Bugzilla Database - - A.5.1. I've heard Bugzilla can be used with Oracle? - A.5.2. I think my database might be corrupted, or contain invalid - entries. What do I do? - - A.5.3. I want to manually edit some entries in my database. How? - A.5.4. I think I've set up MySQL permissions correctly, but - Bugzilla still can't connect. - - A.5.5. How do I synchronize bug information among multiple - different Bugzilla databases? - - 6. Bugzilla and Win32 - - A.6.1. What is the easiest way to run Bugzilla on Win32 - (Win98+/NT/2K)? - - A.6.2. Is there a "Bundle::Bugzilla" equivalent for Win32? - A.6.3. CGI's are failing with a "something.cgi is not a valid - Windows NT application" error. Why? - - A.6.4. I'm having trouble with the perl modules for NT not being - able to talk to to the database. - - 7. Bugzilla Usage - - A.7.1. How do I change my user name (email address) in Bugzilla? - A.7.2. The query page is very confusing. Isn't there a simpler - way to query? - - A.7.3. I'm confused by the behavior of the "accept" button in the - Show Bug form. Why doesn't it assign the bug to me when I - accept it? - - A.7.4. I can't upload anything into the database via the "Create - Attachment" link. What am I doing wrong? - - A.7.5. How do I change a keyword in Bugzilla, once some bugs are - using it? - - A.7.6. Why can't I close bugs from the "Change Several Bugs at - Once" page? - - 8. Bugzilla Hacking - - A.8.1. What kind of style should I use for templatization? - A.8.2. What bugs are in Bugzilla right now? - A.8.3. How can I change the default priority to a null value? For - instance, have the default priority be "---" instead of - "P2"? - - A.8.4. What's the best way to submit patches? What guidelines - should I follow? - -1. General Questions - - A.1.1. What license is Bugzilla distributed under? - - Bugzilla is covered by the Mozilla Public License. See details at - http://www.mozilla.org/MPL/. - - A.1.2. How do I get commercial support for Bugzilla? - - http://bugzilla.org/consulting.html is a list of people and companies - who have asked us to list them as consultants for Bugzilla. - - There are several experienced Bugzilla hackers on the mailing - list/newsgroup who are willing to make themselves available for - generous compensation. Try sending a message to the mailing list - asking for a volunteer. - - A.1.3. What major companies or projects are currently using Bugzilla - for bug-tracking? - - There are dozens of major companies with public Bugzilla sites to - track bugs in their products. We have a fairly complete list available - on our website at http://bugzilla.org/installation-list/. If you have - an installation of Bugzilla and would like to be added to the list, - whether it's a public install or not, simply e-mail Gerv - . - - A.1.4. Who maintains Bugzilla? - - A core team, led by Dave Miller (justdave@bugzilla.org). - - A.1.5. How does Bugzilla stack up against other bug-tracking - databases? - - We can't find any head-to-head comparisons of Bugzilla against other - defect-tracking software. If you know of one, please get in touch. - However, from the author's personal experience with other - bug-trackers, Bugzilla offers superior performance on commodity - hardware, better price (free!), more developer- friendly features - (such as stored queries, email integration, and platform - independence), improved scalability, open source code, greater - flexibility, and superior ease-of-use. - - If you happen to be a commercial bug-tracker vendor, please step - forward with a list of advantages your product has over Bugzilla. We'd - be happy to include it in the "Competitors" section. - - A.1.6. Why doesn't Bugzilla offer this or that feature or - compatibility with this other tracking software? - - It may be that the support has not been built yet, or that you have - not yet found it. Bugzilla is making tremendous strides in usability, - customizability, scalability, and user interface. It is widely - considered the most complete and popular open-source bug-tracking - software in existence. - - That doesn't mean it can't use improvement! You can help the project - along by either hacking a patch yourself that supports the - functionality you require, or else submitting a "Request for - Enhancement" (RFE) using the bug submission interface at - bugzilla.mozilla.org. - - A.1.7. Why MySQL? I'm interested in seeing Bugzilla run on - Oracle/Sybase/Msql/PostgreSQL/MSSQL. - - MySQL was originally chosen because it is free, easy to install, and - was available for the hardware Netscape intended to run it on. - - There is currently work in progress to make Bugzilla work on - PostgreSQL and Sybase in the default distribution. You can track the - progress of these initiatives in bug 98304 and bug 173130 - respectively. - - Once both of these are done, adding support for additional database - servers should be trivial. - - A.1.8. What is /usr/bonsaitools/bin/perl? - - Bugzilla used to have the path to perl on the shebang line set to - /usr/bonsaitools/bin/perl because when Terry first started writing the - code for mozilla.org he needed a version of Perl and other tools that - were completely under his control. This location was abandoned for the - 2.18 release in favor of the more sensible /usr/bin/perl. If you - installed an older verion of Bugzilla and created the symlink we - suggested, you can remove it now (provided that you don't have - anything else, such as Bonsai, using it and you don't intend to - reinstall an older version of Bugzilla). - - A.1.9. My perl is not located at /usr/bin/perl, is there an easy way - to change it everywhere it needs to be changed? - - Yes, the following bit of perl magic will change all the shebang - lines. Be sure to change /usr/local/bin/perl to your path to the perl - binary. -perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl - - A.1.10. Is there an easy way to change the Bugzilla cookie name? - - At present, no. - - A.1.11. Does bugzilla run under mod_perl? - - At present, no. This is being worked on. - -2. Managerial Questions - - A.2.1. Is Bugzilla web-based, or do you have to have specific software - or a specific operating system on your machine? - - It is web and e-mail based. - - A.2.2. Does Bugzilla allow us to define our own priorities and levels? - Do we have complete freedom to change the labels of fields and format - of them, and the choice of acceptable values? - - Yes. However, modifying some fields, notably those related to bug - progression states, also require adjusting the program logic to - compensate for the change. - - There is no GUI for adding fields to Bugzilla at this time. You can - follow development of this feature in bug 91037 - - A.2.3. Does Bugzilla provide any reporting features, metrics, graphs, - etc? You know, the type of stuff that management likes to see. :) - - Yes. Look at http://bugzilla.mozilla.org/report.cgi for samples of - what Bugzilla can do in reporting and graphing. - - If you can not get the reports you want from the included reporting - scripts, it is possible to hook up a professional reporting package - such as Crystal Reports using ODBC. If you choose to do this, beware - that giving direct access to the database does contain some security - implications. Even if you give read-only access to the bugs database - it will bypass the secure bugs features of Bugzilla. - - A.2.4. Is there email notification and if so, what do you see when you - get an email? - - Email notification is user-configurable. By default, the bug id and - summary of the bug report accompany each email notification, along - with a list of the changes made. - - A.2.5. Do users have to have any particular type of email application? - - Bugzilla email is sent in plain text, the most compatible mail format - on the planet. - - Note - - If you decide to use the bugzilla_email integration features to allow - Bugzilla to record responses to mail with the associated bug, you may - need to caution your users to set their mailer to "respond to messages - in the format in which they were sent". For security reasons Bugzilla - ignores HTML tags in comments, and if a user sends HTML-based email - into Bugzilla the resulting comment looks downright awful. - - A.2.6. Does Bugzilla allow data to be imported and exported? If I had - outsiders write up a bug report using a MS Word bug template, could - that template be imported into "matching" fields? If I wanted to take - the results of a query and export that data to MS Excel, could I do - that? - - Bugzilla can output buglists as HTML (the default), CSV or RDF. The - link for CSV can be found at the bottom of the buglist in HTML format. - This CSV format can easily be imported into MS Excel or other - spreadsheet applications. - - To use the RDF format of the buglist it is necessary to append a - &ctype=rdf to the URL. RDF is meant to be machine readable and thus it - is assumed that the URL would be generated programatically so there is - no user visible link to this format. - - Currently the only script included with Bugzilla that can import data - is importxml.pl which is intended to be used for importing the data - generated by the XML ctype of show_bug.cgi in association with bug - moving. Any other use is left as an exercise for the user. - - There are also scripts included in the contrib/ directory for using - e-mail to import information into Bugzilla, but these scripts are not - currently supported and included for educational purposes. - - A.2.7. Has anyone converted Bugzilla to another language to be used in - other countries? Is it localizable? - - Yes. For more information including available translated templates, - see http://www.bugzilla.org/download.html#localizations. The admin - interfaces are still not included in these translated templates and is - therefore still English only. Also, there may be issues with the - charset not being declared. See bug 126226 for more information. - - A.2.8. Can a user create and save reports? Can they do this in Word - format? Excel format? - - Yes. No. Yes (using the CSV format). - - A.2.9. Does Bugzilla provide record locking when there is simultaneous - access to the same bug? Does the second person get a notice that the - bug is in use or how are they notified? - - Bugzilla does not lock records. It provides mid-air collision - detection, and offers the offending user a choice of options to deal - with the conflict. - - A.2.10. Are there any backup features provided? - - MySQL, the database back-end for Bugzilla, allows hot-backup of data. - You can find strategies for dealing with backup considerations at - http://www.mysql.com/doc/B/a/Backup.html. - - A.2.11. Can users be on the system while a backup is in progress? - - Yes. However, commits to the database must wait until the tables are - unlocked. Bugzilla databases are typically very small, and backups - routinely take less than a minute. - - A.2.12. What type of human resources are needed to be on staff to - install and maintain Bugzilla? Specifically, what type of skills does - the person need to have? I need to find out if we were to go with - Bugzilla, what types of individuals would we need to hire and how much - would that cost vs buying an "out-of-the-box" solution? - - If Bugzilla is set up correctly from the start, continuing maintenance - needs are minimal and can be done easily using the web interface. - - Commercial Bug-tracking software typically costs somewhere upwards of - $20,000 or more for 5-10 floating licenses. Bugzilla consultation is - available from skilled members of the newsgroup. Simple questions are - answered there and then. - - A.2.13. What time frame are we looking at if we decide to hire people - to install and maintain the Bugzilla? Is this something that takes - hours or weeks to install and a couple of hours per week to maintain - and customize or is this a multi-week install process, plus a full - time job for 1 person, 2 people, etc? - - It all depends on your level of commitment. Someone with much Bugzilla - experience can get you up and running in less than a day, and your - Bugzilla install can run untended for years. If your Bugzilla strategy - is critical to your business workflow, hire somebody with reasonable - UNIX or Perl skills to handle your process management and bug-tracking - maintenance & customization. - - A.2.14. Is there any licensing fee or other fees for using Bugzilla? - Any out-of-pocket cost other than the bodies needed as identified - above? - - No. MySQL asks, if you find their product valuable, that you purchase - a support contract from them that suits your needs. - -3. Bugzilla Security - - A.3.1. How do I completely disable MySQL security if it's giving me - problems (I've followed the instructions in the installation section - of this guide)? - - Run MySQL like this: "mysqld --skip-grant-tables". Please remember - this makes MySQL as secure as taping a $100 to the floor of a football - stadium bathroom for safekeeping. - - A.3.2. Are there any security problems with Bugzilla? - - The Bugzilla code has undergone a reasonably complete security audit, - and user-facing CGIs run under Perl's taint mode. However, it is - recommended that you closely examine permissions on your Bugzilla - installation, and follow the recommended security guidelines found in - The Bugzilla Guide. - -4. Bugzilla Email - - A.4.1. I have a user who doesn't want to receive any more email from - Bugzilla. How do I stop it entirely for this user? - - The user should be able to set this in user email preferences (uncheck - all boxes) or you can add their email address to the data/nomail file. - - A.4.2. I'm evaluating/testing Bugzilla, and don't want it to send - email to anyone but me. How do I do it? - - Edit the "newchangedmail" Param. Replace "To:" with "X-Real-To:", - replace "Cc:" with "X-Real-CC:", and add a "To: ". - - A.4.3. I want whineatnews.pl to whine at something other than new and - reopened bugs. How do I do it? - - Try Klaas Freitag's excellent patch for "whineatassigned" - functionality. You can find it in bug 6679. This patch is against an - older version of Bugzilla, so you must apply the diffs manually. - - A.4.4. How do I set up the email interface to submit/change bugs via - email? - - You can find an updated README.mailif file in the contrib/ directory - of your Bugzilla distribution that walks you through the setup. - - A.4.5. Email takes FOREVER to reach me from Bugzilla -- it's extremely - slow. What gives? - - If you are using sendmail, try enabling sendmailnow in editparams.cgi. - - If you are using an alternate MTA, make sure the options given in - Bugzilla/BugMail.pm and any other place where sendmail is called from - are correct for your MTA. You should also ensure that the sendmailnow - param is set to on. - - A.4.6. How come email from Bugzilla changes never reaches me? - - Double-check that you have not turned off email in your user - preferences. Confirm that Bugzilla is able to send email by visiting - the "Log In" link of your Bugzilla installation and clicking the - "Email me a password" button after entering your email address. - - If you never receive mail from Bugzilla, chances are you do not have - sendmail in "/usr/lib/sendmail". Ensure sendmail lives in, or is - symlinked to, "/usr/lib/sendmail". - -5. Bugzilla Database - - A.5.1. I've heard Bugzilla can be used with Oracle? - - Red Hat's old version of Bugzilla (based on 2.8) worked on Oracle, but - it is now so old as to be obsolete, and is totally unsupported. Red - Hat's newer version (based on 2.17.1 and soon to be merged into the - main distribution) runs on PostgreSQL. At this time we know of no - recent ports of Bugzilla to Oracle; to be honest, Bugzilla doesn't - need what Oracle offers. - - A.5.2. I think my database might be corrupted, or contain invalid - entries. What do I do? - - Run the "sanity check" utility (sanitycheck.cgi) from your web browser - to see! If it finishes without errors, you're probably OK. If it - doesn't come back OK (i.e. any red letters), there are certain things - Bugzilla can recover from and certain things it can't. If it can't - auto-recover, I hope you're familiar with mysqladmin commands or have - installed another way to manage your database. Sanity Check, although - it is a good basic check on your database integrity, by no means is a - substitute for competent database administration and avoiding deletion - of data. It is not exhaustive, and was created to do a basic check for - the most common problems in Bugzilla databases. - - A.5.3. I want to manually edit some entries in my database. How? - - There is no facility in Bugzilla itself to do this. It's also - generally not a smart thing to do if you don't know exactly what - you're doing. However, if you understand SQL you can use the mysql - command line utility to manually insert, delete and modify table - information. There are also more intuitive GUI clients available. - Personal favorites of the Bugzilla team are phpMyAdmin and MySQL - Control Center. - - A.5.4. I think I've set up MySQL permissions correctly, but Bugzilla - still can't connect. - - Try running MySQL from its binary: "mysqld --skip-grant-tables". This - will allow you to completely rule out grant tables as the cause of - your frustration. If this Bugzilla is able to connect at this point - then you need to check that you have granted proper permission to the - user password combo defined in localconfig. - - Warning - - Running MySQL with this command line option is very insecure and - should only be done when not connected to the external network as a - troubleshooting step. - - A.5.5. How do I synchronize bug information among multiple different - Bugzilla databases? - - Well, you can synchronize or you can move bugs. Synchronization will - only work one way -- you can create a read-only copy of the database - at one site, and have it regularly updated at intervals from the main - database. - - MySQL has some synchronization features builtin to the latest - releases. It would be great if someone looked into the possibilities - there and provided a report to the newsgroup on how to effectively - synchronize two Bugzilla installations. - - If you simply need to transfer bugs from one Bugzilla to another, - checkout the "move.pl" script in the Bugzilla distribution. - -6. Bugzilla and Win32 - - A.6.1. What is the easiest way to run Bugzilla on Win32 - (Win98+/NT/2K)? - - Remove Windows. Install Linux. Install Bugzilla. The boss will never - know the difference. - - A.6.2. Is there a "Bundle::Bugzilla" equivalent for Win32? - - Not currently. Bundle::Bugzilla enormously simplifies Bugzilla - installation on UNIX systems. If someone can volunteer to create a - suitable PPM bundle for Win32, it would be appreciated. - - A.6.3. CGI's are failing with a "something.cgi is not a valid Windows - NT application" error. Why? - - Depending on what Web server you are using, you will have to configure - the Web server to treat *.cgi files as CGI scripts. In IIS, you do - this by adding *.cgi to the App Mappings with the \perl.exe %s - %s as the executable. - - Microsoft has some advice on this matter, as well: - - "Set application mappings. In the ISM, map the extension for the - script file(s) to the executable for the script interpreter. For - example, you might map the extension .py to Python.exe, the - executable for the Python script interpreter. Note For the - ActiveState Perl script interpreter, the extension .pl is - associated with PerlIS.dll by default. If you want to change the - association of .pl to perl.exe, you need to change the application - mapping. In the mapping, you must add two percent (%) characters to - the end of the pathname for perl.exe, as shown in this example: - c:\perl\bin\perl.exe %s %s" - - A.6.4. I'm having trouble with the perl modules for NT not being able - to talk to to the database. - - Your modules may be outdated or inaccurate. Try: - - 1. Hitting http://www.activestate.com/ActivePerl - 2. Download ActivePerl - 3. Go to your prompt - 4. Type 'ppm' - 5. PPM> install DBI DBD-mysql GD - - I reckon TimeDate and Data::Dumper come with the activeperl. You can - check the ActiveState site for packages for installation through PPM. - http://www.activestate.com/Packages/. - -7. Bugzilla Usage - - A.7.1. How do I change my user name (email address) in Bugzilla? - - New in 2.16 - go to the Account section of the Preferences. You will - be emailed at both addresses for confirmation. - - A.7.2. The query page is very confusing. Isn't there a simpler way to - query? - - The interface was simplified by a UI designer for 2.16. Further - suggestions for improvement are welcome, but we won't sacrifice power - for simplicity. - - A.7.3. I'm confused by the behavior of the "accept" button in the Show - Bug form. Why doesn't it assign the bug to me when I accept it? - - The current behavior is acceptable to bugzilla.mozilla.org and most - users. You have your choice of patches to change this behavior, - however. - - Add a "and accept bug" radio button - "Accept" button automatically assigns to you - - Note that these patches are somewhat dated. You will need to apply - them manually. - - A.7.4. I can't upload anything into the database via the "Create - Attachment" link. What am I doing wrong? - - The most likely cause is a very old browser or a browser that is - incompatible with file upload via POST. Download the latest Netscape, - Microsoft, or Mozilla browser to handle uploads correctly. - - A.7.5. How do I change a keyword in Bugzilla, once some bugs are using - it? - - In the Bugzilla administrator UI, edit the keyword and it will let you - replace the old keyword name with a new one. This will cause a problem - with the keyword cache. Run sanitycheck.cgi to fix it. - - A.7.6. Why can't I close bugs from the "Change Several Bugs at Once" - page? - - The logic flow currently used is RESOLVED, then VERIFIED, then CLOSED. - You can mass-CLOSE bugs from the change several bugs at once page. - but, every bug listed on the page has to be in VERIFIED state before - the control to do it will show up on the form. You can also - mass-VERIFY, but every bug listed has to be RESOLVED in order for the - control to show up on the form. The logic behind this is that if you - pick one of the bugs that's not VERIFIED and try to CLOSE it, the bug - change will fail miserably (thus killing any changes in the list after - it while doing the bulk change) so it doesn't even give you the - choice. - -8. Bugzilla Hacking - - A.8.1. What kind of style should I use for templatization? - - Gerv and Myk suggest a 2-space indent, with embedded code sections on - their own line, in line with outer tags. Like this: - -[% IF foo %] - - [% FOREACH x = barney %] - - - [% x %] - - - [% END %] -[% END %] - - - Myk also recommends you turn on PRE_CHOMP in the template - initialization to prevent bloating of HTML with unnecessary - whitespace. - - Please note that many have differing opinions on this subject, and the - existing templates in Bugzilla espouse both this and a 4-space style. - Either is acceptable; the above is preferred. - - A.8.2. What bugs are in Bugzilla right now? - - Try this link to view current bugs or requests for enhancement for - Bugzilla. - - You can view bugs marked for 2.18 release here. This list includes - bugs for the 2.18 release that have already been fixed and checked - into CVS. Please consult the Bugzilla Project Page for details on how - to check current sources out of CVS so you can have these bug fixes - early! - - A.8.3. How can I change the default priority to a null value? For - instance, have the default priority be "---" instead of "P2"? - - This is well-documented in bug 49862. Ultimately, it's as easy as - adding the "---" priority field to your localconfig file in the - appropriate area, re-running checksetup.pl, and then changing the - default priority in your browser using "editparams.cgi". - - A.8.4. What's the best way to submit patches? What guidelines should I - follow? - - 1. Enter a bug into bugzilla.mozilla.org for the "Bugzilla" product. - 2. Upload your patch as a unified diff (having used "diff -u" against - the current sources checked out of CVS), or new source file by - clicking "Create a new attachment" link on the bug page you've - just created, and include any descriptions of database changes you - may make, into the bug ID you submitted in step #1. Be sure and - click the "Patch" checkbox to indicate the text you are sending is - a patch! - 3. Announce your patch and the associated URL - (http://bugzilla.mozilla.org/show_bug.cgi?id=XXXXXX) for - discussion in the newsgroup (netscape.public.mozilla.webtools). - You'll get a really good, fairly immediate reaction to the - implications of your patch, which will also give us an idea how - well-received the change would be. - 4. If it passes muster with minimal modification, the person to whom - the bug is assigned in Bugzilla is responsible for seeing the - patch is checked into CVS. - 5. Bask in the glory of the fact that you helped write the most - successful open-source bug-tracking software on the planet :) - _________________________________________________________________ - -Appendix B. Contrib - - There are a number of unofficial Bugzilla add-ons in the - $BUGZILLA_ROOT/contrib/ directory. This section documents them. - _________________________________________________________________ - -B.1. Command-line Search Interface - - There are a suite of Unix utilities for searching Bugzilla from the - command line. They live in the contrib/cmdline directory. However, - they have not yet been updated to work with 2.16 - (post-templatisation.). There are three files - query.conf, buglist - and bugs. - - query.conf contains the mapping from options to field names and - comparison types. Quoted option names are "grepped" for, so it should - be easy to edit this file. Comments (#) have no effect; you must make - sure these lines do not contain any quoted "option". - - buglist is a shell script which submits a Bugzilla query and writes - the resulting HTML page to stdout. It supports both short options, - (such as "-Afoo" or "-Rbar") and long options (such as - "--assignedto=foo" or "--reporter=bar"). If the first character of an - option is not "-", it is treated as if it were prefixed with - "--default=". - - The column list is taken from the COLUMNLIST environment variable. - This is equivalent to the "Change Columns" option when you list bugs - in buglist.cgi. If you have already used Bugzilla, grep for COLUMNLIST - in your cookies file to see your current COLUMNLIST setting. - - bugs is a simple shell script which calls buglist and extracts the bug - numbers from the output. Adding the prefix - "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list - into a working link if any bugs are found. Counting bugs is easy. Pipe - the results through sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}' - - Akkana Peck says she has good results piping buglist output through - w3m -T text/html -dump - _________________________________________________________________ - -Appendix C. Manual Installation of Perl Modules - -C.1. Instructions - - If you need to install Perl modules manually, here's how it's done. - Download the module using the link given in the next section, and then - apply this magic incantation, as root: - -bash# tar -xzvf .tar.gz -bash# cd -bash# perl Makefile.PL -bash# make -bash# make test -bash# make install - _________________________________________________________________ - -C.2. Download Locations - - Note: some modules are in the core distribution of ActiveState Perl - for Windows. Others are not available. No PPM links have been provided - in either of these two cases. - - CGI: - - CPAN Download Page: http://search.cpan.org/dist/CGI.pm/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/CGI.zip - Documentation: http://www.perldoc.com/perl5.8.0/lib/CGI.html - - TimeDate: - - CPAN Download Page: http://search.cpan.org/dist/TimeDate/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/TimeDate.zip - Documentation: http://search.cpan.org/dist/TimeDate/lib/Date/F - ormat.pm - - DBI: - - CPAN Download Page: http://search.cpan.org/dist/DBI/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/DBI.zip - Documentation: http://dbi.perl.org/docs/ - - DBD::mysql: - - CPAN Download Page: http://search.cpan.org/dist/DBD-mysql/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/DBD-Mysql.zip - Documentation: http://search.cpan.org/dist/DBD-mysql/lib/DBD/m - ysql.pm - - File::Spec: - - CPAN Download Page: http://search.cpan.org/dist/File-Spec/ - PPM Download Page: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/File-Spec.zip - Documentation: http://www.perldoc.com/perl5.8.0/lib/File/Spec. - html - - File::Temp: - - CPAN Download Page: http://search.cpan.org/dist/File-Temp/ - Documentation: http://www.perldoc.com/perl5.8.0/lib/File/Temp. - html - - Template Toolkit: - - CPAN Download Page: http://search.cpan.org/dist/Template-Toolk - it/ - PPM Download Link: http://openinteract.sourceforge.net/ppmpack - ages/5.6/Template-Toolkit.tar.gz - Documentation: http://www.template-toolkit.org/docs.html - - Text::Wrap: - - CPAN Download Page: http://search.cpan.org/dist/Text-Tabs+Wrap - / - Documentation: http://www.perldoc.com/perl5.8.0/lib/Text/Wrap. - html - - GD: - - CPAN Download Page: http://search.cpan.org/dist/GD/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/GD.zip - Documentation: http://stein.cshl.org/WWW/software/GD/ - - Chart::Base: - - CPAN Download Page: http://search.cpan.org/dist/Chart/ - - GD::Graph: - - CPAN Download Page: http://search.cpan.org/dist/GDGraph/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/GDGraph.zip - Documentation: http://search.cpan.org/dist/GDGraph/Graph.pm - - GD::Text::Align: - - CPAN Download Page: http://search.cpan.org/dist/GDTextUtil/ - PPM Download Page: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/GDTextUtil.zip - Documentation: http://search.cpan.org/dist/GDTextUtil/Text/Ali - gn.pm - - MIME::Parser: - - CPAN Download Page: http://search.cpan.org/dist/MIME-tools/ - PPM Download Link: http://ppm.activestate.com/PPMPackages/zips - /6xx-builds-only/MIME-tools.zip - Documentation: http://search.cpan.org/dist/MIME-tools/lib/MIME - /Parser.pm - - XML::Parser: - - CPAN Download Page: http://search.cpan.org/dist/XML-Parser/ - Documentation: http://www.perldoc.com/perl5.6.1/lib/XML/Parser - .html - - PatchReader: - - CPAN Download Page: http://search.cpan.org/author/JKEISER/Patc - hReader/ - Documentation: http://www.johnkeiser.com/mozilla/Patch_Viewer. - html - _________________________________________________________________ - -Appendix D. GNU Free Documentation License - - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, - Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy - and distribute verbatim copies of this license document, but - changing it is not allowed. - _________________________________________________________________ - -0. Preamble - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. It - complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for free - software, because free software needs free documentation: a free - program should come with manuals providing the same freedoms that the - software does. But this License is not limited to software manuals; it - can be used for any textual work, regardless of subject matter or - whether it is published as a printed book. We recommend this License - principally for works whose purpose is instruction or reference. - _________________________________________________________________ - -1. Applicability and Definition - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to any - such manual or work. Any member of the public is a licensee, and is - addressed as "you". - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section of - the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could fall - directly within that overall subject. (For example, if the Document is - in part a textbook of mathematics, a Secondary Section may not explain - any mathematics.) The relationship could be a matter of historical - connection with the subject or with related matters, or of legal, - commercial, philosophical, ethical or political position regarding - them. - - The "Invariant Sections" are certain Secondary Sections whose titles - are designated, as being those of Invariant Sections, in the notice - that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are listed, - as Front-Cover Texts or Back-Cover Texts, in the notice that says that - the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly and - straightforwardly with generic text editors or (for images composed of - pixels) generic paint programs or (for drawings) some widely available - drawing editor, and that is suitable for input to text formatters or - for automatic translation to a variety of formats suitable for input - to text formatters. A copy made in an otherwise Transparent file - format whose markup has been designed to thwart or discourage - subsequent modification by readers is not Transparent. A copy that is - not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, SGML - or XML using a publicly available DTD, and standard-conforming simple - HTML designed for human modification. Opaque formats include - PostScript, PDF, proprietary formats that can be read and edited only - by proprietary word processors, SGML or XML for which the DTD and/or - processing tools are not generally available, and the - machine-generated HTML produced by some word processors for output - purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the material - this License requires to appear in the title page. For works in - formats which do not have any title page as such, "Title Page" means - the text near the most prominent appearance of the work's title, - preceding the beginning of the body of the text. - _________________________________________________________________ - -2. Verbatim Copying - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License applies - to the Document are reproduced in all copies, and that you add no - other conditions whatsoever to those of this License. You may not use - technical measures to obstruct or control the reading or further - copying of the copies you make or distribute. However, you may accept - compensation in exchange for copies. If you distribute a large enough - number of copies you must also follow the conditions in section 3. - - You may also lend copies, under the same conditions stated above, and - you may publicly display copies. - _________________________________________________________________ - -3. Copying in Quantity - - If you publish printed copies of the Document numbering more than 100, - and the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly and - legibly identify you as the publisher of these copies. The front cover - must present the full title with all words of the title equally - prominent and visible. You may add other material on the covers in - addition. Copying with changes limited to the covers, as long as they - preserve the title of the Document and satisfy these conditions, can - be treated as verbatim copying in other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto adjacent - pages. - - If you publish or distribute Opaque copies of the Document numbering - more than 100, you must either include a machine-readable Transparent - copy along with each Opaque copy, or state in or with each Opaque copy - a publicly-accessible computer-network location containing a complete - Transparent copy of the Document, free of added material, which the - general network-using public has access to download anonymously at no - charge using public-standard network protocols. If you use the latter - option, you must take reasonably prudent steps, when you begin - distribution of Opaque copies in quantity, to ensure that this - Transparent copy will remain thus accessible at the stated location - until at least one year after the last time you distribute an Opaque - copy (directly or through your agents or retailers) of that edition to - the public. - - It is requested, but not required, that you contact the authors of the - Document well before redistributing any large number of copies, to - give them a chance to provide you with an updated version of the - Document. - _________________________________________________________________ - -4. Modifications - - You may copy and distribute a Modified Version of the Document under - the conditions of sections 2 and 3 above, provided that you release - the Modified Version under precisely this License, with the Modified - Version filling the role of the Document, thus licensing distribution - and modification of the Modified Version to whoever possesses a copy - of it. In addition, you must do these things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the Modified - Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. You - may omit a network location for a work that was published at least - four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered in - their text and in their titles. Section numbers or the equivalent - are not considered part of the section titles. - M. Delete any section entitled "Endorsements". Such a section may not - be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no material - copied from the Document, you may at your option designate some or all - of these sections as invariant. To do this, add their titles to the - list of Invariant Sections in the Modified Version's license notice. - These titles must be distinct from any other section titles. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of a - standard. - - You may add a passage of up to five words as a Front-Cover Text, and a - passage of up to 25 words as a Back-Cover Text, to the end of the list - of Cover Texts in the Modified Version. Only one passage of - Front-Cover Text and one of Back-Cover Text may be added by (or - through arrangements made by) any one entity. If the Document already - includes a cover text for the same cover, previously added by you or - by arrangement made by the same entity you are acting on behalf of, - you may not add another; but you may replace the old one, on explicit - permission from the previous publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this License - give permission to use their names for publicity for or to assert or - imply endorsement of any Modified Version. - _________________________________________________________________ - -5. Combining Documents - - You may combine the Document with other documents released under this - License, under the terms defined in section 4 above for modified - versions, provided that you include in the combination all of the - Invariant Sections of all of the original documents, unmodified, and - list them all as Invariant Sections of your combined work in its - license notice. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name but - different contents, make the title of each such section unique by - adding at the end of it, in parentheses, the name of the original - author or publisher of that section if known, or else a unique number. - Make the same adjustment to the section titles in the list of - Invariant Sections in the license notice of the combined work. - - In the combination, you must combine any sections entitled "History" - in the various original documents, forming one section entitled - "History"; likewise combine any sections entitled "Acknowledgements", - and any sections entitled "Dedications". You must delete all sections - entitled "Endorsements." - _________________________________________________________________ - -6. Collections of Documents - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the rules - of this License for verbatim copying of each of the documents in all - other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert a - copy of this License into the extracted document, and follow this - License in all other respects regarding verbatim copying of that - document. - _________________________________________________________________ - -7. Aggregation with Independent Works - - A compilation of the Document or its derivatives with other separate - and independent documents or works, in or on a volume of a storage or - distribution medium, does not as a whole count as a Modified Version - of the Document, provided no compilation copyright is claimed for the - compilation. Such a compilation is called an "aggregate", and this - License does not apply to the other self-contained works thus compiled - with the Document, on account of their being thus compiled, if they - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one quarter - of the entire aggregate, the Document's Cover Texts may be placed on - covers that surround only the Document within the aggregate. Otherwise - they must appear on covers around the whole aggregate. - _________________________________________________________________ - -8. Translation - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section 4. - Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a disagreement - between the translation and the original English version of this - License, the original English version will prevail. - _________________________________________________________________ - -9. Termination - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other attempt - to copy, modify, sublicense or distribute the Document is void, and - will automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such - parties remain in full compliance. - _________________________________________________________________ - -10. Future Revisions of this License - - The Free Software Foundation may publish new, revised versions of the - GNU Free Documentation License from time to time. Such new versions - will be similar in spirit to the present version, but may differ in - detail to address new problems or concerns. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version number. - If the Document specifies that a particular numbered version of this - License "or any later version" applies to it, you have the option of - following the terms and conditions either of that specified version or - of any later version that has been published (not as a draft) by the - Free Software Foundation. If the Document does not specify a version - number of this License, you may choose any version ever published (not - as a draft) by the Free Software Foundation. - _________________________________________________________________ - -How to use this License for your documents - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and - license notices just after the title page: - - Copyright (c) YEAR YOUR NAME. Permission is granted to copy, - distribute and/or modify this document under the terms of the GNU - Free Documentation License, Version 1.1 or any later version - published by the Free Software Foundation; with the Invariant - Sections being LIST THEIR TITLES, with the Front-Cover Texts being - LIST, and with the Back-Cover Texts being LIST. A copy of the - license is included in the section entitled "GNU Free Documentation - License". - - If you have no Invariant Sections, write "with no Invariant Sections" - instead of saying which ones are invariant. If you have no Front-Cover - Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts - being LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -Glossary - -0-9, high ascii - - .htaccess - Apache web server, and other NCSA-compliant web servers, - observe the convention of using files in directories called - .htaccess to restrict access to certain files. In Bugzilla, - they are used to keep secret files which would otherwise - compromise your installation - e.g. the localconfig file - contains the password to your database. curious. - -A - - Apache - In this context, Apache is the web server most commonly used - for serving up Bugzilla pages. Contrary to popular belief, the - apache web server has nothing to do with the ancient and noble - Native American tribe, but instead derived its name from the - fact that it was "a patchy" version of the original NCSA - world-wide-web server. - - Useful Directives when configuring Bugzilla - - AddHandler - Tell Apache that it's OK to run CGI scripts. - - AllowOverride, Options - These directives are used to tell Apache many things - about the directory they apply to. For Bugzilla's - purposes, we need them to allow script execution and - .htaccess overrides. - - DirectoryIndex - Used to tell Apache what files are indexes. If you can - not add index.cgi to the list of valid files, you'll need - to set $index_html to 1 in localconfig so ./checksetup.pl - will create an index.html that redirects to index.cgi. - - ScriptInterpreterSource - Used when running Apache on windows so the shebang line - doesn't have to be changed in every Bugzilla script. - - For more information about how to configure Apache for - Bugzilla, see Section 2.2.4.1. - -B - - Bug - A "bug" in Bugzilla refers to an issue entered into the - database which has an associated number, assignments, comments, - etc. Some also refer to a "tickets" or "issues"; in the context - of Bugzilla, they are synonymous. - - Bug Number - Each Bugzilla bug is assigned a number that uniquely identifies - that bug. The bug associated with a bug number can be pulled up - via a query, or easily from the very front page by typing the - number in the "Find" box. - - Bugzilla - Bugzilla is the world-leading free software bug tracking - system. - -C - - Common Gateway Interface (CGI) - CGI is an acronym for Common Gateway Interface. This is a - standard for interfacing an external application with a web - server. Bugzilla is an example of a CGI application. - - Component - A Component is a subsection of a Product. It should be a narrow - category, tailored to your organization. All Products must - contain at least one Component (and, as a matter of fact, - creating a Product with no Components will create an error in - Bugzilla). - - Comprehensive Perl Archive Network (CPAN) - CPAN stands for the "Comprehensive Perl Archive Network". CPAN - maintains a large number of extremely useful Perl modules - - encapsulated chunks of code for performing a particular task. - - contrib - The contrib directory is a location to put scripts that have - been contributed to Bugzilla but are not a part of the official - distribution. These scripts are written by third parties and - may be in languages other than perl. For those that are in - perl, there may be additional modules or other requirements - than those of the offical distribution. - - Note - - Scripts in the contrib directory are not offically supported by the - Bugzilla team and may break in between versions. - -D - - daemon - A daemon is a computer program which runs in the background. In - general, most daemons are started at boot time via System V - init scripts, or through RC scripts on BSD-based systems. - mysqld, the MySQL server, and apache, a web server, are - generally run as daemons. - -G - - Groups - The word "Groups" has a very special meaning to Bugzilla. - Bugzilla's main security mechanism comes by placing users in - groups, and assigning those groups certain privileges to view - bugs in particular Products in the Bugzilla database. - -J - - JavaScript - JavaScript is cool, we should talk about it. - -M - - Message Transport Agent (MTA) - A Message Transport Agent is used to control the flow of email - on a system. Many unix based systems use sendmail which is what - Bugzilla expects to find by default at /usr/sbin/sendmail. Many - other MTA's will work, but they all require that the - sendmailnow param be set to on. - - MySQL - MySQL is currently the required RDBMS for Bugzilla. MySQL can - be downloaded from http://www.mysql.com. While you should - familiarize yourself with all of the documentation, some high - points are: - - Backup - Methods for backing up your Bugzilla database. - - Option Files - Information about how to configure MySQL using my.cnf. - - Privilege System - Much more detailed information about the suggestions in - Section 2.2.2.1. - -P - - Perl Package Manager (PPM) - http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/ - - Product - A Product is a broad category of types of bugs, normally - representing a single piece of software or entity. In general, - there are several Components to a Product. A Product may define - a group (used for security) for all bugs entered into its - Components. - - Perl - First written by Larry Wall, Perl is a remarkable program - language. It has the benefits of the flexibility of an - interpreted scripting language (such as shell script), combined - with the speed and power of a compiled language, such as C. - Bugzilla is maintained in Perl. - -Q - - QA - "QA", "Q/A", and "Q.A." are short for "Quality Assurance". In - most large software development organizations, there is a team - devoted to ensuring the product meets minimum standards before - shipping. This team will also generally want to track the - progress of bugs over their life cycle, thus the need for the - "QA Contact" field in a bug. - -R - - Relational DataBase Managment System (RDBMS) - A relational database management system is a database system - that stores information in tables that are related to each - other. - - Regular Expression (regexp) - A regular expression is an expression used for pattern - matching. Documentation - -S - - SGML - SGML stands for "Standard Generalized Markup Language". Created - in the 1980's to provide an extensible means to maintain - documentation based upon content instead of presentation, SGML - has withstood the test of time as a robust, powerful language. - XML is the "baby brother" of SGML; any valid XML document it, - by definition, a valid SGML document. The document you are - reading is written and maintained in SGML, and is also valid - XML if you modify the Document Type Definition. - -T - - Target Milestone - Target Milestones are Product goals. They are configurable on a - per-Product basis. Most software development houses have a - concept of "milestones" where the people funding a project - expect certain functionality on certain dates. Bugzilla - facilitates meeting these milestones by giving you the ability - to declare by which milestone a bug will be fixed, or an - enhancement will be implemented. - - Tool Command Language (TCL) - TCL is an open source scripting language available for Windows, - Macintosh, and Unix based systems. Bugzilla 1.0 was written in - TCL but never released. The first release of Bugzilla was 2.0, - which was when it was ported to perl. - -Z - - Zarro Boogs Found - This is just a goofy way of saying that there were no bugs - found matching your query. When asked to explain this message, - Terry had the following to say: - - - - I've been asked to explain this ... way back when, when Netscape - released version 4.0 of its browser, we had a release party. - Naturally, there had been a big push to try and fix every known bug - before the release. Naturally, that hadn't actually happened. (This is - not unique to Netscape or to 4.0; the same thing has happened with - every software project I've ever seen.) Anyway, at the release party, - T-shirts were handed out that said something like "Netscape 4.0: Zarro - Boogs". Just like the software, the T-shirt had no known bugs. Uh-huh. - So, when you query for a list of bugs, and it gets no results, you can - think of this as a friendly reminder. Of *course* there are bugs - matching your query, they just aren't in the bugsystem yet... - - --Terry Weissman -- cgit v1.2.3-24-g4f1b