diff options
Diffstat (limited to 'docs/xml')
| -rw-r--r-- | docs/xml/.cvsignore | 1 | ||||
| -rw-r--r-- | docs/xml/Bugzilla-Guide.xml | 178 | ||||
| -rw-r--r-- | docs/xml/about.xml | 243 | ||||
| -rw-r--r-- | docs/xml/administration.xml | 3448 | ||||
| -rw-r--r-- | docs/xml/conventions.xml | 164 | ||||
| -rw-r--r-- | docs/xml/customization.xml | 820 | ||||
| -rw-r--r-- | docs/xml/dbschema.mysql | 1 | ||||
| -rw-r--r-- | docs/xml/faq.xml | 1659 | ||||
| -rw-r--r-- | docs/xml/filetemp.patch | 18 | ||||
| -rw-r--r-- | docs/xml/gfdl.xml | 445 | ||||
| -rw-r--r-- | docs/xml/glossary.xml | 551 | ||||
| -rw-r--r-- | docs/xml/index.xml | 21 | ||||
| -rw-r--r-- | docs/xml/installation.xml | 2040 | ||||
| -rw-r--r-- | docs/xml/integration.xml | 120 | ||||
| -rw-r--r-- | docs/xml/introduction.xml | 121 | ||||
| -rw-r--r-- | docs/xml/modules.xml | 193 | ||||
| -rw-r--r-- | docs/xml/patches.xml | 131 | ||||
| -rw-r--r-- | docs/xml/requiredsoftware.xml | 77 | ||||
| -rw-r--r-- | docs/xml/security.xml | 367 | ||||
| -rw-r--r-- | docs/xml/troubleshooting.xml | 307 | ||||
| -rw-r--r-- | docs/xml/using.xml | 1957 |
21 files changed, 0 insertions, 12862 deletions
diff --git a/docs/xml/.cvsignore b/docs/xml/.cvsignore deleted file mode 100644 index ef6b304bc..000000000 --- a/docs/xml/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -bugzilla.ent diff --git a/docs/xml/Bugzilla-Guide.xml b/docs/xml/Bugzilla-Guide.xml deleted file mode 100644 index e9650c7cb..000000000 --- a/docs/xml/Bugzilla-Guide.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ - <!ENTITY % myents SYSTEM "bugzilla.ent"> - %myents; - -<!-- Include macros --> -<!ENTITY about SYSTEM "about.xml"> -<!ENTITY conventions SYSTEM "conventions.xml"> -<!ENTITY doc-index SYSTEM "index.xml"> -<!ENTITY gfdl SYSTEM "gfdl.xml"> -<!ENTITY glossary SYSTEM "glossary.xml"> -<!ENTITY installation SYSTEM "installation.xml"> -<!ENTITY administration SYSTEM "administration.xml"> -<!ENTITY security SYSTEM "security.xml"> -<!ENTITY using SYSTEM "using.xml"> -<!ENTITY integration SYSTEM "integration.xml"> -<!ENTITY index SYSTEM "index.xml"> -<!ENTITY customization SYSTEM "customization.xml"> -<!ENTITY troubleshooting SYSTEM "troubleshooting.xml"> -<!ENTITY patches SYSTEM "patches.xml"> -<!ENTITY introduction SYSTEM "introduction.xml"> -<!ENTITY modules SYSTEM "modules.xml"> - -<!-- Things to change for a stable release: - * bz-ver to current stable - * bz-nexver to next stable - * bz-date to the release date - * landfillbase to the branch install - * Remove the BZ-DEVEL comments - - COMPILE DOCS AND CHECKIN - - Also, tag and tarball before completing - * bz-ver to devel version - - For a devel release, simple bump bz-ver and bz-date ---> - -<!ENTITY bz-ver "3.1.3"> -<!ENTITY bz-nextver "3.2"> -<!ENTITY bz-date "2008-02-01"> -<!ENTITY current-year "2008"> - -<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/"> -<!ENTITY bz "http://www.bugzilla.org/"> -<!ENTITY bzg-bugs "<ulink url='https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation'>Bugzilla Documentation</ulink>"> -<!ENTITY mysql "http://www.mysql.com/"> - -<!ENTITY min-perl-ver "5.8.1"> -]> - - -<!-- Coding standards for this document - -* Other than the GFDL, please use the "section" tag instead of "sect1", - "sect2", etc. -* Use Entities to include files for new chapters in Bugzilla-Guide.xml. -* Try to use Entities for frequently-used passages of text as well. -* Ensure all documents compile cleanly to HTML after modification. - The warning, "DTDDECL catalog types not supported" is normal. -* Try to index important terms wherever possible. -* Use "glossterm" whenever you introduce a new term. -* Follow coding standards at http://www.tldp.org, and - check out the KDE guidelines (they are nice, too) - http://i18n.kde.org/doc/markup.html -* All tags should be lowercase. -* Please use sensible spacing. The comments at the very end of each - file define reasonable defaults for PSGML mode in EMACS. -* Double-indent tags, use double spacing whenever possible, and - try to avoid clutter and feel free to waste space in the code to make it - more readable. - ---> - -<book id="index"> - -<!-- Header --> - - <bookinfo> - <title>The Bugzilla Guide - &bz-ver; - <!-- BZ-DEVEL -->Development <!-- /BZ-DEVEL --> - Release</title> - - <authorgroup> - <corpauthor>The Bugzilla Team</corpauthor> - </authorgroup> - - <pubdate>&bz-date;</pubdate> - - <abstract> - <para> - 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. - </para> - - <para> - The most current version of this document can always be found on the - <ulink url="http://www.bugzilla.org/docs/">Bugzilla - Documentation Page</ulink>. - </para> - - </abstract> - - <keywordset> - <keyword>Bugzilla</keyword> - <keyword>Guide</keyword> - <keyword>installation</keyword> - <keyword>FAQ</keyword> - <keyword>administration</keyword> - <keyword>integration</keyword> - <keyword>MySQL</keyword> - <keyword>Mozilla</keyword> - <keyword>webtools</keyword> - </keywordset> - </bookinfo> - -<!-- About This Guide --> -&about; - -<!-- Installing Bugzilla --> -&installation; - -<!-- Administering Bugzilla --> -&administration; - -<!-- Securing Bugzilla --> -&security; - -<!-- Using Bugzilla --> -&using; - -<!-- Customizing Bugzilla --> -&customization; - -<!-- Appendix: Troubleshooting --> -&troubleshooting; - -<!-- Appendix: Custom Patches --> -&patches; - -<!-- Appendix: Manually Installing Perl Modules --> -&modules; - -<!-- Appendix: GNU Free Documentation License --> -&gfdl; - -<!-- Glossary --> -&glossary; - -<!-- Index --> -&index; - - -</book> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/about.xml b/docs/xml/about.xml deleted file mode 100644 index c1633ac0c..000000000 --- a/docs/xml/about.xml +++ /dev/null @@ -1,243 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ -<!ENTITY conventions SYSTEM "conventions.xml"> ] > --> -<!-- $Id: about.xml,v 1.26 2007/08/02 06:52:32 wurblzap%gmail.com Exp $ --> - -<chapter id="about"> -<title>About This Guide</title> - - <section id="copyright"> - <title>Copyright Information</title> - - <para>This document is copyright (c) 2000-¤t-year; by the various - Bugzilla contributors who wrote it.</para> - - <blockquote> - <para> - 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 <xref linkend="gfdl"/>. - </para> - </blockquote> - <para> - If you have any questions regarding this document, its - copyright, or publishing this document in non-electronic form, - please contact the Bugzilla Team. - </para> - </section> - - <section id="disclaimer"> - <title>Disclaimer</title> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - </section> - -<!-- Section 2: New Versions --> - - <section id="newversions"> - <title>New Versions</title> - <para> - This is the &bz-ver; version of The Bugzilla Guide. It is so named - to match the current version of Bugzilla. - <!-- BZ-DEVEL --> This version of the guide, like its associated Bugzilla version, is a - development version.<!-- /BZ-DEVEL --> - </para> - <para> - The latest version of this guide can always be found at <ulink - url="http://www.bugzilla.org"/>, or checked out via CVS by - following the <ulink url="http://www.mozilla.org/cvs.html">Mozilla - CVS</ulink> instructions and check out the - <filename>mozilla/webtools/bugzilla/docs/</filename> - subtree. However, you should read the version - which came with the Bugzilla release you are using. - </para> - <para> - The Bugzilla Guide, or a section of it, is also available in - the following languages: - <ulink url="http://www.traduc.org/docs/guides/lecture/bugzilla/">French</ulink>, - <ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>, - <ulink url="http://www.bugzilla.jp/docs/2.18/">Japanese</ulink>. - Note that these may be outdated or not up to date. - </para> - - <para> - In addition, there are Bugzilla template localization projects in - the following languages. They may have translated documentation - available: - <ulink url="http://sourceforge.net/projects/bugzilla-ar/">Arabic</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-be/">Belarusian</ulink>, - <ulink url="http://openfmi.net/projects/mozilla-bg/">Bulgarian</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-br/">Brazilian Portuguese</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-cn/">Chinese</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-fr/">French</ulink>, - <ulink url="http://germzilla.ganderbay.net/">German</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-it/">Italian</ulink>, - <ulink url="http://www.bugzilla.jp/about/jp.html">Japanese</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-kr/">Korean</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-ru/">Russian</ulink> and - <ulink url="http://sourceforge.net/projects/bugzilla-es/">Spanish</ulink>. - </para> - - <para> - If you would like to volunteer to translate the Guide into additional - languages, please contact - <ulink url="mailto:justdave@bugzilla.org">Dave Miller</ulink>. - </para> - </section> - - <section id="credits"> - <title>Credits</title> - <para> - 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: - </para> - - <!-- TODO: This is evil... there has to be a valid way to get this look --> - <variablelist> - <varlistentry> - <term>Matthew P. Barnson <email>mbarnson@sisna.com</email></term> - <listitem> - <para>for the Herculean task of pulling together the Bugzilla Guide - and shepherding it to 2.14. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Terry Weissman <email>terry@mozilla.org</email></term> - <listitem> - <para>for initially writing Bugzilla and creating the README upon - which the UNIX installation documentation is largely based. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Tara Hernandez <email>tara@tequilarists.org</email></term> - <listitem> - <para>for keeping Bugzilla development going strong after Terry left - mozilla.org and for running landfill. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Dave Lawrence <email>dkl@redhat.com</email></term> - <listitem> - <para>for providing insight into the key differences between Red - Hat's customized Bugzilla. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Dawn Endico <email>endico@mozilla.org</email></term> - <listitem> - <para>for being a hacker extraordinaire and putting up with Matthew's - incessant questions and arguments on irc.mozilla.org in #mozwebtools - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Jacob Steenhagen <email>jake@bugzilla.org</email></term> - <listitem> - <para>for taking over documentation during the 2.17 development - period. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Dave Miller <email>justdave@bugzilla.org</email></term> - <listitem> - <para>for taking over as project lead when Tara stepped down and - continually pushing for the documentation to be the best it can be. - </para> - </listitem> - </varlistentry> - - </variablelist> - - - <para> - Thanks also go to the following people for significant contributions - to this documentation: - <simplelist type="inline"> - <member>Kevin Brannen</member> - <member>Vlad Dascalu</member> - <member>Ben FrantzDale</member> - <member>Eric Hanson</member> - <member>Zach Lipton</member> - <member>Gervase Markham</member> - <member>Andrew Pearson</member> - <member>Joe Robins</member> - <member>Spencer Smith</member> - <member>Ron Teitelbaum</member> - <member>Shane Travis</member> - <member>Martin Wulffeld</member> - </simplelist>. - </para> - - <para> - Also, thanks are due to the members of the - <ulink url="news://news.mozilla.org/mozilla.support.bugzilla"> - mozilla.support.bugzilla</ulink> - newsgroup (and its predecessor, netscape.public.mozilla.webtools). - Without your discussions, insight, suggestions, and patches, - this could never have happened. - </para> - </section> - - <!-- conventions used here (didn't want to give it a chapter of its own) --> -&conventions; - </chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: --> - diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml deleted file mode 100644 index 7a75604de..000000000 --- a/docs/xml/administration.xml +++ /dev/null @@ -1,3448 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<chapter id="administration"> - <title>Administering Bugzilla</title> - - <section id="parameters"> - <title>Bugzilla Configuration</title> - - <para> - Bugzilla is configured by changing various parameters, accessed - from the "Parameters" link in the Administration page (the - Administration page can be found by clicking the "Administration" - link in the footer). The parameters are divided into several categories, - accessed via the menu on the left. Following is a description of the - different categories and important parameters within those categories. - </para> - - <section id="param-requiredsettings"> - <title>Required Settings</title> - - <para> - The core required parameters for any Bugzilla installation are set - here. These parameters must be set before a new Bugzilla installation - can be used. Administrators should review this list before - deploying a new Bugzilla installation. - </para> - - <indexterm> - <primary>checklist</primary> - </indexterm> - - <variablelist> - - <varlistentry> - <term> - maintainer - </term> - <listitem> - <para> - Email address of the person - responsible for maintaining this Bugzilla installation. - The address need not be that of a valid Bugzilla account. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - urlbase - </term> - <listitem> - <para> - Defines the fully qualified domain name and web - server path to this Bugzilla installation. - </para> - <para> - For example, if the Bugzilla query page is - <filename>http://www.foo.com/bugzilla/query.cgi</filename>, - the <quote>urlbase</quote> should be set - to <filename>http://www.foo.com/bugzilla/</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - docs_urlbase - </term> - <listitem> - <para> - Defines path to the Bugzilla documentation. This can be a fully - qualified domain name, or a path relative to "urlbase". - </para> - <para> - For example, if the "Bugzilla Configuration" page - of the documentation is - <filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>, - set the <quote>docs_urlbase</quote> - to <filename>http://www.foo.com/bugzilla/docs/html/</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - sslbase - </term> - <listitem> - <para> - Defines the fully qualified domain name and web - server path for HTTPS (SSL) connections to this Bugzilla installation. - </para> - <para> - For example, if the Bugzilla main page is - <filename>https://www.foo.com/bugzilla/index.cgi</filename>, - the <quote>sslbase</quote> should be set - to <filename>https://www.foo.com/bugzilla/</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - ssl - </term> - <listitem> - <para> - Determines when Bugzilla will force HTTPS (SSL) connections, using - the URL defined in <command>sslbase</command>. - Options include "always", "never", and "authenticated sessions". - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - cookiedomain - </term> - <listitem> - <para> - Defines the domain for Bugzilla cookies. This is typically left blank. - If there are multiple hostnames that point to the same webserver, which - require the same cookie, then this parameter can be utilized. For - example, If your website is at - <filename>https://www.foo.com/</filename>, setting this to - <filename>.foo.com/</filename> will also allow - <filename>bar.foo.com/</filename> to access Bugzilla cookies. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - cookiepath - </term> - <listitem> - <para> - Defines a path, relative to the web server root, that Bugzilla - cookies will be restricted to. For example, if the - <command>urlbase</command> is set to - <filename>http://www.foo.com/bugzilla/</filename>, the - <command>cookiepath</command> should be set to - <filename>/bugzilla/</filename>. Setting it to "/" will allow all sites - served by this web server or virtual host to read Bugzilla cookies. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - timezone - </term> - <listitem> - <para> - Timezone of server. The timezone is displayed with timestamps. If - this parameter is left blank, the timezone is not displayed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - utf8 - </term> - <listitem> - <para> - Determines whether to use UTF-8 (Unicode) encoding for all text in - Bugzilla. New installations should set this to true to avoid character - encoding problems. Existing databases should set this to true only - after the data has been converted from existing legacy character - encoding to UTF-8, using the - <filename>contrib/recode.pl</filename> script. - </para> - <note> - <para> - If you turn this parameter from "off" to "on", you must re-run - <filename>checksetup.pl</filename> immediately afterward. - </para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term> - shutdownhtml - </term> - <listitem> - <para> - If there is any text in this field, this Bugzilla installation will - be completely disabled and this text will appear instead of all - Bugzilla pages for all users, including Admins. Used in the event - of site maintenance or outage situations. - </para> - <note> - <para> - Although regular log-in capability is disabled while - <command>shutdownhtml</command> - is enabled, safeguards are in place to protect the unfortunate - admin who loses connection to Bugzilla. Should this happen to you, - go directly to the <filename>editparams.cgi</filename> (by typing - the URL in manually, if necessary). Doing this will prompt you to - log in, and your name/password will be accepted here (but nowhere - else). - </para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term> - announcehtml - </term> - <listitem> - <para> - Any text in this field will be displayed at the top of every HTML - page in this Bugzilla installation. The text is not wrapped in any - tags. For best results, wrap the text in a <quote><div></quote> - tag. Any style attributes from the CSS can be applied. For example, - to make the text green inside of a red box, add <quote>id=message</quote> - to the <quote><div></quote> tag. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - proxy_url - </term> - <listitem> - <para> - If this Bugzilla installation is behind a proxy, enter the proxy - information here to enable Bugzilla to access the Internet. Bugzilla - requires Internet access to utilize the - <command>upgrade_notification</command> parameter (below). If the - proxy requires authentication, use the syntax: - <filename>http://user:pass@proxy_url/</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - upgrade_notification - </term> - <listitem> - <para> - Enable or disable a notification on the homepage of this Bugzilla - installation when a newer version of Bugzilla is available. This - notification is only visible to administrators. Choose "disabled", - to turn off the notification. Otherwise, choose which version of - Bugzilla you want to be notified about: "development_snapshot" is the - latest release on the trunk; "latest_stable_release" is the most - recent release available on the most recent stable branch; - "stable_branch_release" the most recent release on the branch - this installation is based on. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-admin-policies"> - <title>Administrative Policies</title> - <para> - This page contains parameters for basic administrative functions. - Options include whether to allow the deletion of bugs and users, whether - to allow users to change their email address, and whether to allow - user watching (one user receiving all notifications of a selected - other user). - </para> - - <variablelist> - - <varlistentry> - <term> - supportwatchers - </term> - <listitem> - <para> - Turning on this option allows users to ask to receive copies - of bug mail sent to another user. Watching a user with - different group permissions is not a way to 'get around' the - system; copied emails are still subject to the normal groupset - permissions of a bug, and <quote>watchers</quote> will only be - copied on emails from bugs they would normally be allowed to view. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-user-authentication"> - <title>User Authentication</title> - <para> - This page contains the settings that control how this Bugzilla - installation will do its authentication. Choose what authentication - mechanism to use (the Bugzilla database, or an external source such - as LDAP), and set basic behavioral parameters. For example, choose - whether to require users to login to browse bugs, the management - of authentication cookies, and the regular expression used to - validate email addresses. Some parameters are highlighted below. - </para> - - <variablelist> - - <varlistentry> - <term> - emailregexp - </term> - <listitem> - <para> - Defines the regular expression used to validate email addresses - used for login names. The default attempts to match fully - qualified email addresses (i.e. 'user@example.com'). Some - Bugzilla installations allow only local user names (i.e 'user' - instead of 'user@example.com'). In that case, the - <command>emailsuffix</command> parameter should be used to define - the email domain. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - emailsuffix - </term> - <listitem> - <para> - This string is appended to login names when actually sending - email to a user. For example, - If <command>emailregexp</command> has been set to allow - local usernames, - then this parameter would contain the email domain for all users - (i.e. '@example.com'). - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-attachments"> - <title>Attachments</title> - <para> - This page allows for setting restrictions and other parameters - regarding attachments to bugs. For example, control size limitations - and whether to allow pointing to external files via a URI. - </para> - </section> - - <section id="param-bug-change-policies"> - <title>Bug Change Policies</title> - <para> - Set policy on default behavior for bug change events. For example, - choose which status to set a bug to when it is marked as a duplicate, - and choose whether to allow bug reporters to set the priority or - target milestone. Also allows for configuration of what changes - should require the user to make a comment, described below. - </para> - - <variablelist> - - <varlistentry> - <term> - commenton* - </term> - <listitem> - <para> - 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. - </para> - - <para> - 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. - </para> - - <note> - <para> - 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!) - </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term> - noresolveonopenblockers - </term> - <listitem> - <para> - This option will prevent users from resolving bugs as FIXED if - they have unresolved dependencies. Only the FIXED resolution - is affected. Users will be still able to resolve bugs to - resolutions other than FIXED if they have unresolved dependent - bugs. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-bugfields"> - <title>Bug Fields</title> - <para> - The parameters in this section determine the default settings of - several Bugzilla fields for new bugs, and also control whether - certain fields are used. For example, choose whether to use the - "target milestone" field or the "status whiteboard" field. - </para> - - <variablelist> - - <varlistentry> - <term> - useqacontact - </term> - <listitem> - <para> - This allows you to define an email address for each component, - in addition to that of the default assignee, who will be sent - carbon copies of incoming bugs. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - usestatuswhiteboard - </term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-bugmoving"> - <title>Bug Moving</title> - <para> - This page controls whether this Bugzilla installation allows certain - users to move bugs to an external database. If bug moving is enabled, - there are a number of parameters that control bug moving behaviors. - For example, choose which users are allowed to move bugs, the location - of the external database, and the default product and component that - bugs moved <emphasis>from</emphasis> other bug databases to this - Bugzilla installation are assigned to. - </para> - - </section> - - <section id="param-dependency-graphs"> - <title>Dependency Graphs</title> - <para> - This page has one parameter that sets the location of a Web Dot - server, or of the Web Dot binary on the local system, that is used - to generate dependency graphs. Web Dot is a CGI program that creates - images from <filename>.dot</filename> graphic description files. If - no Web Dot server or binary is specified, then dependency graphs will - be disabled. - </para> - </section> - - <section id="param-group-security"> - <title>Group Security</title> - <para> - Bugzilla allows for the creation of different groups, with the - ability to restrict the visibility of bugs in a group to a set of - specific users. Specific products can also be associated with - groups, and users restricted to only see products in their groups. - Several parameters are described in more detail below. Most of the - configuration of groups and their relationship to products is done - on the "Groups" and "Product" pages of the "Administration" area. - The options on this page control global default behavior. - For more information on Groups and Group Security, see - <xref linkend="groups"/> - </para> - - <variablelist> - - <varlistentry> - <term> - makeproductgroups - </term> - <listitem> - <para> - Determines whether or not to automatically create groups - when new products are created. If this is on, the groups will be - used for querying bugs. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - useentrygroupdefault - </term> - <listitem> - <para> - 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 <quote>on</quote>, 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - usevisibilitygroups - </term> - <listitem> - <para> - If selected, user visibility will be restricted to members of - groups, as selected in the group configuration settings. - Each user-defined group can be allowed to see members of selected - other groups. - For details on configuring groups (including the visibility - restrictions) see <xref linkend="edit-groups"/>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - querysharegroup - </term> - <listitem> - <para> - The name of the group of users who are allowed to share saved - searches with one another. For more information on using - saved searches, see <xref linkend="savedsearches"/>. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="bzldap"> - <title>LDAP Authentication</title> - - <para>LDAP authentication is a module for Bugzilla's plugin - authentication architecture. This page contains all the parameters - necessary to configure Bugzilla for use with LDAP authentication. - </para> - - <para> - 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 that - require a 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. Bugzilla tries to bind to LDAP using - those credentials and, if successful, tries to map this account to a - Bugzilla account. If an LDAP mail attribute is defined, the value of this - attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP - username to form a full email address. If an account for this address - already exists in the Bugzilla installation, 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. For example, bugs are still assigned by - email address and users are still queried by email address. - </para> - - <caution> - <para>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 <filename>bugzilla_ldapsync.rb</filename> - script in the - <glossterm linkend="gloss-contrib"> - <filename class="directory">contrib</filename></glossterm> - directory. Another possible solution is fixing - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug - 201069</ulink>. - </para> - </caution> - - <para>Parameters required to use LDAP Authentication:</para> - - <variablelist> - <varlistentry id="param-user_verify_class_for_ldap"> - <term>user_verify_class</term> - <listitem> - <para>If you want to list <quote>LDAP</quote> here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - <filename>data/params</filename> and set user_verify_class to - <quote>DB</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPserver"> - <term>LDAPserver</term> - <listitem> - <para>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. - </para> - <para>Ex. <quote>ldap.company.com</quote> - or <quote>ldap.company.com:3268</quote> - </para> - <para>You can also specify a LDAP URI, so as to use other - protocols, such as LDAPS or LDAPI. If port was not specified in - the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' - schemes respectively. - </para> - <para>Ex. <quote>ldap://ldap.company.com</quote>, - <quote>ldaps://ldap.company.com</quote> or - <quote>ldapi://%2fvar%2flib%2fldap_sock</quote> - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPbinddn"> - <term>LDAPbinddn [Optional]</term> - <listitem> - <para>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. - </para> - <para>Ex. <quote>cn=default,cn=user:password</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPBaseDN"> - <term>LDAPBaseDN</term> - <listitem> - <para>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. - </para> - <para>Ex. <quote>ou=People,o=Company</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPuidattribute"> - <term>LDAPuidattribute</term> - <listitem> - <para>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. - </para> - <para>Ex. <quote>uid</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPmailattribute"> - <term>LDAPmailattribute</term> - <listitem> - <para>The LDAPmailattribute parameter should be the name of the - attribute which contains the email address your users will enter - into the Bugzilla login boxes. - </para> - <para>Ex. <quote>mail</quote></para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="bzradius"> - <title>RADIUS Authentication</title> - - <para> - RADIUS authentication is a module for Bugzilla's plugin - authentication architecture. This page contains all the parameters - necessary for configuring Bugzilla to use RADIUS authentication. - </para> - <note> - <para> - Most caveats that apply to LDAP authentication apply to RADIUS - authentication as well. See <xref linkend="bzldap"/> for details. - </para> - </note> - - <para>Parameters required to use RADIUS Authentication:</para> - - <variablelist> - <varlistentry id="param-user_verify_class_for_radius"> - <term>user_verify_class</term> - <listitem> - <para>If you want to list <quote>RADIUS</quote> here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - <filename>data/params</filename> and set user_verify_class to - <quote>DB</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_server"> - <term>RADIUS_server</term> - <listitem> - <para>This parameter should be set to the name (and optionally the - port) of your RADIUS server. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_secret"> - <term>RADIUS_secret</term> - <listitem> - <para>This parameter should be set to the RADIUS server's secret. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_email_suffix"> - <term>RADIUS_email_suffix</term> - <listitem> - <para>Bugzilla needs an e-mail address for each user account. - Therefore, it needs to determine the e-mail address corresponding - to a RADIUS user. - Bugzilla offers only a simple way to do this: it can concatenate - a suffix to the RADIUS user name to convert it into an e-mail - address. - You can specify this suffix in the RADIUS_email_suffix parameter. - </para> - <para>If this simple solution does not work for you, you'll - probably need to modify - <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your - requirements. - </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="param-email"> - <title>Email</title> - <para> - This page contains all of the parameters for configuring how - Bugzilla deals with the email notifications it sends. See below - for a summary of important options. - </para> - - <variablelist> - - <varlistentry> - <term> - mail_delivery_method - </term> - <listitem> - <para> - This is used to specify how email is sent, or if it is sent at - all. There are several options included for different MTAs, - along with two additional options that disable email sending. - "Test" does not send mail, but instead saves it in - <filename>data/mailer.testfile</filename> for later review. - "None" disables email sending entirely. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - mailfrom - </term> - <listitem> - <para> - This is the email address that will appear in the "From" field - of all emails sent by this Bugzilla installation. Some email - servers require mail to be from a valid email address, therefore - it is recommended to choose a valid email address here. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - sendmailnow - </term> - <listitem> - <para> - When Bugzilla is using Sendmail older than 8.12, turning this option - off will improve performance by not waiting for Sendmail to actually - send mail. If Sendmail 8.12 or later is being used, there is - nothing to gain by turning this off. If another MTA is being used, - such as Postfix, then this option *must* be turned on (even if you - are using the fake sendmail executable that Postfix provides). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - whinedays - </term> - <listitem> - <para> - 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). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - globalwatcher - </term> - <listitem> - <para> - This allows you to define specific users who will - receive notification each time a new bug in entered, or when - an existing bug changes, according to the normal groupset - permissions. It may be useful for sending notifications to a - mailing-list, for instance. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </section> - - <section id="param-patchviewer"> - <title>Patch Viewer</title> - <para> - This page contains configuration parameters for the CVS server, - Bonsai server and LXR server that Bugzilla will use to enable the - features of the Patch Viewer. Bonsai is a tool that enables queries - to a CVS tree. LXR is a tool that can cross reference and index source - code. - </para> - </section> - - <section id="param-querydefaults"> - <title>Query Defaults</title> - <para> - This page controls the default behavior of Bugzilla in regards to - several aspects of querying bugs. Options include what the default - query options are, what the "My Bugs" page returns, whether users - can freely add bugs to the quip list, and how many duplicate bugs are - needed to add a bug to the "most frequently reported" list. - </para> - </section> - - <section id="param-shadowdatabase"> - <title>Shadow Database</title> - <para> - This page controls whether a shadow database is used, and all the - parameters associated with the shadow database. Versions of Bugzilla - prior to 3.2 used the MyISAM table type, which supports - only table-level write locking. With MyISAM, any time someone is making a change to - a bug, the entire table is locked until the write operation is complete. - Locking for write also blocks reads until the write is complete. - </para> - <para> - The <quote>shadowdb</quote> 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. - </para> - - <note> - <para> - As of version 3.2, Bugzilla no longer uses the MyISAM table type. - Instead, InnoDB is used, which can do transaction-based locking. - Therefore, the limitations the Shadow Database feature was designed - to workaround no longer exist. - </para> - </note> - - </section> - - <section id="admin-usermatching"> - <title>User Matching</title> - <para> - The settings on this page control how users are selected and queried - when adding a user to a bug. For example, users need to be selected - when choosing who the bug is assigned to, adding to the CC list or - selecting a QA contact. With the "usemenuforusers" parameter, it is - possible to configure Bugzilla to - display a list of users in the fields instead of an empty text field. - This should only be used in Bugzilla installations with a small number - of users. If users are selected via a text box, this page also - contains parameters for how user names can be queried and matched - when entered. - </para> - - </section> - - </section> - - <section id="useradmin"> - <title>User Administration</title> - - <section id="defaultuser"> - <title>Creating the Default User</title> - - <para>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.</para> - - <tip> - <para>If you wish to add more administrative users, add them to - the "admin" group and, optionally, edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups (which is the case by default). - </para> - </tip> - </section> - - <section id="manageusers"> - <title>Managing Other Users</title> - - <section id="user-account-search"> - <title>Searching for existing users</title> - - <para> - If you have <quote>editusers</quote> privileges or if you are allowed - to grant privileges for some groups, the <quote>Users</quote> link - will appear in the Administration page. - </para> - - <para> - The first screen is a search form to search for existing user - accounts. You can run searches based either on the user ID, real - name or login name (i.e. the email address, or just the first part - of the email address if the "emailsuffix" parameter is set). - The search can be conducted - in different ways using the listbox to the right of the text entry - box. You can match by case-insensitive substring (the default), - regular expression, a <emphasis>reverse</emphasis> regular expression - match (which finds every user name which does NOT match the regular - expression), or the exact string if you know exactly who you are - looking for. The search can be restricted to users who are in a - specific group. By default, the restriction is turned off. - </para> - - <para> - The search returns a list of - users matching your criteria. User properties can be edited by clicking - the login name. The Account History of a user can be viewed by clicking - the "View" link in the Account History column. The Account History - displays changes that have been made to the user account, the time of - the change and the user who made the change. For example, the Account - History page will display details of when a user was added or removed - from a group. - </para> - </section> - - <section id="createnewusers"> - <title>Creating new users</title> - - <section id="self-registration"> - <title>Self-registration</title> - - <para> - By default, users can create their own user accounts by clicking the - <quote>New Account</quote> link at the bottom of each page (assuming - they aren't logged in as someone else already). If you want to disable - this self-registration, or if you want to restrict who can create his - own user account, you have to edit the <quote>createemailregexp</quote> - parameter in the <quote>Configuration</quote> page, see - <xref linkend="parameters" />. - </para> - </section> - - <section id="user-account-creation"> - <title>Accounts created by an administrator</title> - - <para> - Users with <quote>editusers</quote> privileges, such as administrators, - can create user accounts for other users: - </para> - - <orderedlist> - <listitem> - <para>After logging in, click the "Users" link at the footer of - the query page, and then click "Add a new user".</para> - </listitem> - - <listitem> - <para>Fill out the form presented. This page is self-explanatory. - When done, click "Submit".</para> - - <note> - <para>Adding a user this way will <emphasis>not</emphasis> - 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 <quote>New Account</quote> - button to create users, as it will pre-populate all the - required fields and also notify the user of her account name - and password.</para> - </note> - </listitem> - </orderedlist> - </section> - </section> - - <section id="modifyusers"> - <title>Modifying Users</title> - - <para>Once you have found your user, you can change the following - fields:</para> - - <itemizedlist> - <listitem> - <para> - <emphasis>Login Name</emphasis>: - This is generally the user's full email address. However, if you - have are using the <quote>emailsuffix</quote> parameter, this may - just be the user's login name. Note that users can now change their - login names themselves (to any valid email address). - </para> - </listitem> - - <listitem> - <para> - <emphasis>Real Name</emphasis>: The user's real name. Note that - Bugzilla does not require this to create an account.</para> - </listitem> - - <listitem> - <para> - <emphasis>Password</emphasis>: - 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. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Bugmail Disabled</emphasis>: - Mark this checkbox to disable bugmail and whinemail completely - for this account. This checkbox replaces the data/nomail file - which existed in older versions of Bugzilla. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Disable Text</emphasis>: - 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. - </para> - <para> - Users with disabled accounts will continue to receive - mail from Bugzilla; furthermore, they will not be able - to log in themselves to change their own preferences and - stop it. If you want an account (disabled or active) to - stop receiving mail, simply check the - <quote>Bugmail Disabled</quote> checkbox above. - </para> - <note> - <para> - Even users whose accounts have been disabled can still - submit bugs via the e-mail gateway, if one exists. - The e-mail gateway should <emphasis>not</emphasis> be - enabled for secure installations of Bugzilla. - </para> - </note> - <warning> - <para> - Don't disable all the administrator accounts! - </para> - </warning> - </listitem> - - <listitem> - <para> - <emphasis><groupname></emphasis>: - 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. - </para> - </listitem> - - <listitem> - <para> - <emphasis>canconfirm</emphasis>: - 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).</para> - </listitem> - - <listitem> - <para> - <emphasis>creategroups</emphasis>: - This option will allow a user to create and destroy groups in - Bugzilla.</para> - </listitem> - - <listitem> - <para> - <emphasis>editbugs</emphasis>: - 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. - </para> - </listitem> - - <listitem> - <para> - <emphasis>editcomponents</emphasis>: - 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. - </para> - </listitem> - - <listitem> - <para> - <emphasis>editkeywords</emphasis>: - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>editusers</emphasis>: - 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.</para> - </listitem> - - - <listitem> - <para> - <emphasis>tweakparams</emphasis>: - This flag allows a user to change Bugzilla's Params - (using <filename>editparams.cgi</filename>.)</para> - </listitem> - - <listitem> - <para> - <emphasis><productname></emphasis>: - This allows an administrator to specify the products - in which a user can see bugs. If you turn on the - <quote>makeproductgroups</quote> parameter in - the Group Security Panel in the Parameters page, - then Bugzilla creates one group per product (at the time you create - the product), and this group has exactly the same name as the - product itself. Note that for products that already exist when - the parameter is turned on, the corresponding group will not be - created. The user must still have the <quote>editbugs</quote> - privilege to edit bugs in these products.</para> - </listitem> - </itemizedlist> - </section> - - <section id="user-account-deletion"> - <title>Deleting Users</title> - <para> - If the <quote>allowuserdeletion</quote> parameter is turned on, see - <xref linkend="parameters" />, then you can also delete user accounts. - Note that this is most of the time not the best thing to do. If only - a warning in a yellow box is displayed, then the deletion is safe. - If a warning is also displayed in a red box, then you should NOT try - to delete the user account, else you will get referential integrity - problems in your database, which can lead to unexpected behavior, - such as bugs not appearing in bug lists anymore, or data displaying - incorrectly. You have been warned! - </para> - </section> - - <section id="impersonatingusers"> - <title>Impersonating Users</title> - - <para> - There may be times when an administrator would like to do something as - another user. The <command>sudo</command> feature may be used to do - this. - </para> - - <note> - <para> - To use the sudo feature, you must be in the - <emphasis>bz_sudoers</emphasis> group. By default, all - administrators are in this group.</para> - </note> - - <para> - If you have access to this feature, you may start a session by - going to the Edit Users page, Searching for a user and clicking on - their login. You should see a link below their login name titled - "Impersonate this user". Click on the link. This will take you - to a page where you will see a description of the feature and - instructions for using it. After reading the text, simply - enter the login of the user you would like to impersonate, provide - a short message explaining why you are doing this, and press the - button.</para> - - <para> - As long as you are using this feature, everything you do will be done - as if you were logged in as the user you are impersonating.</para> - - <warning> - <para> - The user you are impersonating will not be told about what you are - doing. If you do anything that results in mail being sent, that - mail will appear to be from the user you are impersonating. You - should be extremely careful while using this feature.</para> - </warning> - </section> - </section> - </section> - - <section id="classifications" xreflabel="Classifications"> - <title>Classifications</title> - - <para>Classifications tend to be used in order to group several related - products into one distinct entity.</para> - - <para>The classifications layer is disabled by default; it can be turned - on or off using the useclassification parameter, - in the <emphasis>Bug Fields</emphasis> section of the edit parameters screen.</para> - - <para>Access to the administration of classifications is controlled using - the <emphasis>editclassifications</emphasis> system group, which defines - a privilege for creating, destroying, and editing classifications.</para> - - <para>When activated, classifications will introduce an additional - step when filling bugs (dedicated to classification selection), and they - will also appear in the advanced search form.</para> - </section> - - <section id="products" xreflabel="Products"> - <title>Products</title> - - <para> - <glossterm linkend="gloss-product" baseform="product"> - Products</glossterm> typically represent real-world - shipping products. Products can be given - <xref linkend="classifications"/>. - For example, if a company makes computer games, - they could have a classification of "Games", and a separate - product for each game. This company might also have a - <quote>Common</quote> product for units of technology used - in multiple games, and perhaps a few special products that - represent items that are not actually shipping products - (for example, "Website", or "Administration"). - </para> - - <para> - Many of Bugzilla's settings are configurable on a per-product - basis. The number of <quote>votes</quote> 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. - </para> - - <para> - When creating or editing products the following options are - available: - </para> - - <variablelist> - - <varlistentry> - <term> - Product - </term> - <listitem> - <para> - The name of the product - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Description - </term> - <listitem> - <para> - A brief description of the product - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - URL describing milestones for this product - </term> - <listitem> - <para> - If there is reference URL, provide it here - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Default milestone - </term> - <listitem> - <para> - Select the default milestone for this product. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Closed for bug entry - </term> - <listitem> - <para> - Select this box to prevent new bugs from being - entered against this product. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Maximum votes per person - </term> - <listitem> - <para> - Maximum votes a user is allowed to give for this - product - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Maximum votes a person can put on a single bug - </term> - <listitem> - <para> - Maximum votes a user is allowed to give for this - product in a single bug - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Confirmation threshold - </term> - <listitem> - <para> - Number of votes needed to automatically remove any - bug against this product from the UNCONFIRMED state - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Version - </term> - <listitem> - <para> - Specify which version of the product bugs will be - entered against. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Create chart datasets for this product - </term> - <listitem> - <para> - Select to make chart datasets available for this product. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - When editing a product there is also a link to edit Group Access Controls, - see <xref linkend="product-group-controls"/>. - </para> - - <section id="create-product"> - <title>Creating New Products</title> - - <para> - To create a new product: - </para> - - <orderedlist> - <listitem> - <para> - Select <quote>Administration</quote> from the footer and then - choose <quote>Products</quote> from the main administration page. - </para> - </listitem> - - <listitem> - <para> - Select the <quote>Add</quote> link in the bottom right. - </para> - </listitem> - - <listitem> - <para> - Enter the name of the product and a description. The - Description field may contain HTML. - </para> - </listitem> - - <listitem> - <para> - When the product is created, Bugzilla will give a message - stating that a component must be created before any bugs can - be entered against the new product. Follow the link to create - a new component. See <xref linkend="components"/> for more - information. - </para> - </listitem> - </orderedlist> - - </section> - - <section id="edit-products"> - <title>Editing Products</title> - - <para> - To edit an existing product, click the "Products" link from the - "Administration" page. If the 'useclassification' parameter is - turned on, a table of existing classifications is displayed, - including an "Unclassified" category. The table indicates how many products - are in each classification. Click on the classification name to see its - products. If the 'useclassification' parameter is not in use, the table - lists all products directly. The product table summarizes the information - about the product defined - when the product was created. Click on the product name to edit these - properties, and to access links to other product attributes such as the - product's components, versions, milestones, and group access controls. - </para> - - </section> - - <section id="comps-vers-miles-products"> - <title>Adding or Editing Components, Versions and Target Milestones</title> - <para> - To edit existing, or add new, Components, Versions or Target Milestones - to a Product, select the "Edit Components", "Edit Versions" or "Edit - Milestones" links from the "Edit Product" page. A table of existing - Components, Versions or Milestones is displayed. Click on a item name - to edit the properties of that item. Below the table is a link to add - a new Component, Version or Milestone. - </para> - <para> - For more information on components, see <xref linkend="components"/>. - </para> - <para> - For more information on versions, see <xref linkend="versions"/>. - </para> - <para> - For more information on milestones, see <xref linkend="milestones"/>. - </para> - </section> - - <section id="product-group-controls"> - <title>Assigning Group Controls to Products</title> - - <para> - On the <quote>Edit Product</quote> page, there is a link called - <quote>Edit Group Access Controls</quote>. The settings on this page - control the relationship of the groups to the product being edited. - </para> - - <para> - Group Access Controls are an important aspect of using groups for - isolating products and restricting access to bugs filed against those - products. For more information on groups, including how to create, edit - add users to, and alter permission of, see <xref linkend="groups"/>. - </para> - - <para> - After selecting the "Edit Group Access Controls" link from the "Edit - Product" page, a table containing all user-defined groups for this - Bugzilla installation is displayed. The system groups that are created - when Bugzilla is installed are not applicable to Group Access Controls. - Below is description of what each of these fields means. - </para> - - <para> - Groups may be applicable (e.g bugs in this product can be associated - with this group) , default (e.g. bugs in this product are in this group - by default), and mandatory (e.g. bugs in this product must be associated - with this group) for each product. Groups can also control access - to bugs for a given product, or be used to make bugs for a product - totally read-only unless the group restrictions are met. The best way to - understand these relationships is by example. See - <xref linkend="group-control-examples"/> for examples of - product and group relationships. - </para> - - <note> - <para> - Products and Groups are not limited to a one-to-one relationship. - Multiple groups can be associated with the same product, and groups - can be associated with more than one product. - </para> - </note> - - <para> - If any group has <emphasis>Entry</emphasis> selected, then the - product will restrict bug entry to only those users - who are members of <emphasis>all</emphasis> the groups with - <emphasis>Entry</emphasis> selected. - </para> - - <para> - If any group has <emphasis>Canedit</emphasis> selected, - then the product will be read-only for any users - who are not members of <emphasis>all</emphasis> of the groups with - <emphasis>Canedit</emphasis> selected. <emphasis>Only</emphasis> users who - are members of all the <emphasis>Canedit</emphasis> groups - will be able to edit bugs for this product. This is an additional - restriction that enables finer-grained control over products rather - than just all-or-nothing access levels. - </para> - - <para> - The following settings let you - choose privileges on a <emphasis>per-product basis</emphasis>. - This is a convenient way to give privileges to - some users for some products only, without having - to give them global privileges which would affect - all products. - </para> - - <para> - Any group having <emphasis>editcomponents</emphasis> - selected allows users who are in this group to edit all - aspects of this product, including components, milestones - and versions. - </para> - - <para> - Any group having <emphasis>canconfirm</emphasis> selected - allows users who are in this group to confirm bugs - in this product. - </para> - - <para> - Any group having <emphasis>editbugs</emphasis> selected allows - users who are in this group to edit all fields of - bugs in this product. - </para> - - <para> - The <emphasis>MemberControl</emphasis> and - <emphasis>OtherControl</emphasis> are used in tandem to determine which - bugs will be placed in this group. The only allowable combinations of - these two parameters are listed in a table on the "Edit Group Access Controls" - page. Consult this table for details on how these fields can be used. - Examples of different uses are described below. - </para> - - <section id="group-control-examples"> - <title>Common Applications of Group Controls</title> - - <para> - The use of groups is best explained by providing examples that illustrate - configurations for common use cases. The examples follow a common syntax: - <emphasis>Group: Entry, MemberControl, OtherControl, CanEdit, - EditComponents, CanConfirm, EditBugs</emphasis>. Where "Group" is the name - of the group being edited for this product. The other fields all - correspond to the table on the "Edit Group Access Controls" page. If any - of these options are not listed, it means they are not checked. - </para> - - <para> - Basic Product/Group Restriction - </para> - - <para> - Suppose there is a product called "Bar". The - "Bar" product can only have bugs entered against it by users in the - group "Foo". Additionally, bugs filed against product "Bar" must stay - restricted to users to "Foo" at all times. Furthermore, only members - of group "Foo" can edit bugs filed against product "Bar", even if other - users could see the bug. This arrangement would achieved by the - following: - </para> - - <programlisting> -Product Bar: -foo: ENTRY, MANDATORY/MANDATORY, CANEDIT - </programlisting> - - <para> - Perhaps such strict restrictions are not needed for product "Bar". A - more lenient way to configure product "Bar" and group "Foo" would be: - </para> - - <programlisting> -Product Bar: -foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS - </programlisting> - - <para> - The above indicates that for product "Bar", members of group "Foo" can - enter bugs. Any one with permission to edit a bug against product "Bar" - can put the bug - in group "Foo", even if they themselves are not in "Foo". Anyone in group - "Foo" can edit all aspects of the components of product "Bar", can confirm - bugs against product "Bar", and can edit all fields of any bug against - product "Bar". - </para> - - <para> - General User Access With Security Group - </para> - - <para> - To permit any user to file bugs against "Product A", - and to permit any user to submit those bugs into a - group called "Security": - </para> - - <programlisting> -Product A: -security: SHOWN/SHOWN - </programlisting> - - <para> - General User Access With A Security Product - </para> - - <para> - To permit any user to file bugs against product called "Security" - while keeping those bugs from becoming visible to anyone - outside the group "SecurityWorkers" (unless a member of the - "SecurityWorkers" group removes that restriction): - </para> - - <programlisting> -Product Security: -securityworkers: DEFAULT/MANDATORY - </programlisting> - - <para> - Product Isolation With a Common Group - </para> - - <para> - To permit users of "Product A" to access the bugs for - "Product A", users of "Product B" to access the bugs for - "Product B", and support staff, who are members of the "Support - Group" to access both, three groups are needed: - </para> - - <orderedlist> - - <listitem> - <para>Support Group: Contains members of the support staff.</para> - </listitem> - - <listitem> - <para>AccessA Group: Contains users of product A and the Support group.</para> - </listitem> - - <listitem> - <para>AccessB Group: Contains users of product B and the Support group.</para> - </listitem> - - </orderedlist> - - <para> - Once these three groups are defined, the product group controls - can be set to: - </para> - - <programlisting> -Product A: -AccessA: ENTRY, MANDATORY/MANDATORY -Product B: -AccessB: ENTRY, MANDATORY/MANDATORY - </programlisting> - - <para> - Perhaps the "Support Group" wants more control. For example, - the "Support Group" could be permitted to make bugs inaccessible to - users of both groups "AccessA" and "AccessB". - Then, the "Support Group" could be permitted to publish - bugs relevant to all users in a third product (let's call it - "Product Common") that is read-only - to anyone outside the "Support Group". In this way the "Support Group" - could control bugs that should be seen by both groups. - That configuration would be: - </para> - - <programlisting> -Product A: -AccessA: ENTRY, MANDATORY/MANDATORY -Support: SHOWN/NA -Product B: -AccessB: ENTRY, MANDATORY/MANDATORY -Support: SHOWN/NA -Product Common: -Support: ENTRY, DEFAULT/MANDATORY, CANEDIT - </programlisting> - - <para> - Make a Product Read Only - </para> - - <para> - Sometimes a product is retired and should no longer have - new bugs filed against it (for example, an older version of a software - product that is no longer supported). A product can be made read-only - by creating a group called "readonly" and adding products to the - group as needed: - </para> - - <programlisting> -Product A: -ReadOnly: ENTRY, NA/NA, CANEDIT - </programlisting> - - <note> - <para> - For more information on Groups outside of how they relate to products - see <xref linkend="groups"/>. - </para> - </note> - - </section> - - </section> - - </section> - - <section id="components" xreflabel="Components"> - <title>Components</title> - - <para>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.</para> - - <para> - Each component has a default assignee and (if you turned it on in the parameters), - a QA Contact. The default assignee 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 Assignee, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Assignee and Default QA Contact fields only - dictate the - <emphasis>default assignments</emphasis>; - these can be changed on bug submission, or at any later point in - a bug's life.</para> - - <para>To create a new Component:</para> - - <orderedlist> - <listitem> - <para>Select the <quote>Edit components</quote> link - from the <quote>Edit product</quote> page</para> - </listitem> - - <listitem> - <para>Select the <quote>Add</quote> link in the bottom right.</para> - </listitem> - - <listitem> - <para>Fill out the <quote>Component</quote> field, a - short <quote>Description</quote>, the - <quote>Default Assignee</quote>, <quote>Default CC List</quote> - and <quote>Default QA Contact</quote> (if enabled). - The <quote>Component Description</quote> field may contain a - limited subset of HTML tags. The <quote>Default Assignee</quote> - field must be a login name already existing in the Bugzilla database. - </para> - </listitem> - </orderedlist> - </section> - - <section id="versions"> - <title>Versions</title> - - <para>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. - </para> - - <para>To create and edit Versions:</para> - - <orderedlist> - <listitem> - <para>From the "Edit product" screen, select "Edit Versions"</para> - </listitem> - - <listitem> - <para>You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right.</para> - </listitem> - - <listitem> - <para>Enter the name of the Version. This field takes text only. - Then click the "Add" button.</para> - </listitem> - - </orderedlist> - </section> - - <section id="milestones"> - <title>Milestones</title> - - <para>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.</para> - - <note> - <para>Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" Param in the "Edit Parameters" screen. - </para> - </note> - - <para>To create new Milestones, set Default Milestones, and set - Milestone URL:</para> - - <orderedlist> - <listitem> - <para>Select "Edit milestones" from the "Edit product" page.</para> - </listitem> - - <listitem> - <para>Select "Add" in the bottom right corner. - text</para> - </listitem> - - <listitem> - <para>Enter the name of the Milestone in the "Milestone" field. You - can optionally set the "sortkey", which is a positive or negative - number (-32768 to 32767) 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".</para> - </listitem> - - <listitem> - <para>From the Edit product screen, you can enter the URL of a - page which gives information about your milestones and what - they mean. </para> - </listitem> - </orderedlist> - </section> - - <section id="flags-overview"> - <title>Flags</title> - - <para> - Flags are a way to attach a specific status to a bug or attachment, - either <quote>+</quote> or <quote>-</quote>. The meaning of these symbols depends on the text - the flag itself, but contextually they could mean pass/fail, - accept/reject, approved/denied, or even a simple yes/no. If your site - allows requestable flags, then users may set a flag to <quote>?</quote> as a - request to another user that they look at the bug/attachment, and set - the flag to its correct status. - </para> - - <section id="flags-simpleexample"> - <title>A Simple Example</title> - - <para> - A developer might want to ask their manager, - <quote>Should we fix this bug before we release version 2.0?</quote> - They might want to do this for a <emphasis>lot</emphasis> of bugs, - so it would be nice to streamline the process... - </para> - <para> - In Bugzilla, it would work this way: - <orderedlist> - <listitem> - <para> - The Bugzilla administrator creates a flag type called - <quote>blocking2.0</quote> that shows up on all bugs in - your product. - </para> - - <para> - It shows up on the <quote>Show Bug</quote> screen - as the text <quote>blocking2.0</quote> with a drop-down box next - to it. The drop-down box contains four values: an empty space, - <quote>?</quote>, <quote>-</quote>, and <quote>+</quote>. - </para> - </listitem> - <listitem> - <para>The developer sets the flag to <quote>?</quote>.</para> - </listitem> - <listitem> - <para> - The manager sees the <computeroutput>blocking2.0</computeroutput> - flag with a <quote>?</quote> value. - </para> - </listitem> - <listitem> - <para> - If the manager thinks the feature should go into the product - before version 2.0 can be released, he sets the flag to - <quote>+</quote>. Otherwise, he sets it to <quote>-</quote>. - </para> - </listitem> - <listitem> - <para> - Now, every Bugzilla user who looks at the bug knows whether or - not the bug needs to be fixed before release of version 2.0. - </para> - </listitem> - </orderedlist> - </para> - - </section> - - <section id="flags-about"> - <title>About Flags</title> - - <section id="flag-values"> - <title>Values</title> - <para> - Flags can have three values: - <variablelist> - <varlistentry> - <term><computeroutput>?</computeroutput></term> - <listitem><simpara> - A user is requesting that a status be set. (Think of it as 'A question is being asked'.) - </simpara></listitem> - </varlistentry> - <varlistentry> - <term><computeroutput>-</computeroutput></term> - <listitem><simpara> - The status has been set negatively. (The question has been answered <quote>no</quote>.) - </simpara></listitem> - </varlistentry> - <varlistentry> - <term><computeroutput>+</computeroutput></term> - <listitem><simpara> - The status has been set positively. - (The question has been answered <quote>yes</quote>.) - </simpara></listitem> - </varlistentry> - </variablelist> - </para> - <para> - Actually, there's a fourth value a flag can have -- - <quote>unset</quote> -- which shows up as a blank space. This - just means that nobody has expressed an opinion (or asked - someone else to express an opinion) about this bug or attachment. - </para> - </section> - </section> - - <section id="flag-askto"> - <title>Using flag requests</title> - <para> - If a flag has been defined as 'requestable', and a user has enough privileges - to request it (see below), the user can set the flag's status to <quote>?</quote>. - This status indicates that someone (a.k.a. <quote>the requester</quote>) is asking - someone else to set the flag to either <quote>+</quote> or <quote>-</quote>. - </para> - <para> - If a flag has been defined as 'specifically requestable', - a text box will appear next to the flag into which the requester may - enter a Bugzilla username. That named person (a.k.a. <quote>the requestee</quote>) - will receive an email notifying them of the request, and pointing them - to the bug/attachment in question. - </para> - <para> - If a flag has <emphasis>not</emphasis> been defined as 'specifically requestable', - then no such text-box will appear. A request to set this flag cannot be made of - any specific individual, but must be asked <quote>to the wind</quote>. - A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank. - </para> - </section> - - <section id="flag-types"> - <title>Two Types of Flags</title> - - <para> - Flags can go in two places: on an attachment, or on a bug. - </para> - - <section id="flag-type-attachment"> - <title>Attachment Flags</title> - - <para> - Attachment flags are used to ask a question about a specific - attachment on a bug. - </para> - <para> - Many Bugzilla installations use this to - request that one developer <quote>review</quote> another - developer's code before they check it in. They attach the code to - a bug report, and then set a flag on that attachment called - <quote>review</quote> to - <computeroutput>review?boss@domain.com</computeroutput>. - boss@domain.com is then notified by email that - he has to check out that attachment and approve it or deny it. - </para> - - <para> - For a Bugzilla user, attachment flags show up in three places: - <orderedlist> - <listitem> - <para> - On the list of attachments in the <quote>Show Bug</quote> - screen, you can see the current state of any flags that - have been set to ?, +, or -. You can see who asked about - the flag (the requester), and who is being asked (the - requestee). - </para> - </listitem> - <listitem> - <para> - When you <quote>Edit</quote> an attachment, you can - see any settable flag, along with any flags that have - already been set. This <quote>Edit Attachment</quote> - screen is where you set flags to ?, -, +, or unset them. - </para> - </listitem> - <listitem> - <para> - Requests are listed in the <quote>Request Queue</quote>, which - is accessible from the <quote>My Requests</quote> link (if you are - logged in) or <quote>Requests</quote> link (if you are logged out) - visible in the footer of all pages. - </para> - </listitem> - </orderedlist> - </para> - - </section> - - <section id="flag-type-bug"> - <title>Bug Flags</title> - - <para> - Bug flags are used to set a status on the bug itself. You can - see Bug Flags in the <quote>Show Bug</quote> and <quote>Requests</quote> - screens, as described above. - </para> - <para> - Only users with enough privileges (see below) may set flags on bugs. - This doesn't necessarily include the assignee, reporter, or users with the - <computeroutput>editbugs</computeroutput> permission. - </para> - </section> - - </section> - - <section id="flags-admin"> - <title>Administering Flags</title> - - <para> - If you have the <quote>editcomponents</quote> permission, you can - edit Flag Types from the main administration page. Clicking the - <quote>Flags</quote> link will bring you to the <quote>Administer - Flag Types</quote> page. Here, you can select whether you want - to create (or edit) a Bug flag, or an Attachment flag. - </para> - <para> - No matter which you choose, the interface is the same, so we'll - just go over it once. - </para> - - <section id="flags-edit"> - <title>Editing a Flag</title> - <para> - To edit a flag's properties, just click on the <quote>Edit</quote> - link next to the flag's description. That will take you to the same - form as described below (<xref linkend="flags-create"/>). - </para> - </section> - - <section id="flags-create"> - <title>Creating a Flag</title> - - <para> - When you click on the <quote>Create a Flag Type for...</quote> - link, you will be presented with a form. Here is what the fields in - the form mean: - </para> - - <section id="flags-create-field-name"> - <title>Name</title> - <para> - This is the name of the flag. This will be displayed - to Bugzilla users who are looking at or setting the flag. - The name may contain any valid Unicode characters except commas - and spaces. - </para> - </section> - - <section id="flags-create-field-description"> - <title>Description</title> - <para> - The description describes the flag in more detail. It is visible - in a tooltip when hovering over a flag either in the <quote>Show Bug</quote> - or <quote>Edit Attachment</quote> pages. This field can be as - long as you like, and can contain any character you want. - </para> - </section> - - <section id="flags-create-field-category"> - <title>Category</title> - - <para> - Default behaviour for a newly-created flag is to appear on - products and all components, which is why <quote>__Any__:__Any__</quote> - is already entered in the <quote>Inclusions</quote> box. - If this is not your desired behaviour, you must either set some - exclusions (for products on which you don't want the flag to appear), - or you must remove <quote>__Any__:__Any__</quote> from the Inclusions box - and define products/components specifically for this flag. - </para> - - <para> - To create an Inclusion, select a Product from the top drop-down box. - You may also select a specific component from the bottom drop-down box. - (Setting <quote>__Any__</quote> for Product translates to, - <quote>all the products in this Bugzilla</quote>. - Selecting <quote>__Any__</quote> in the Component field means - <quote>all components in the selected product.</quote>) - Selections made, press <quote>Include</quote>, and your - Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right. - </para> - - <para> - To create an Exclusion, the process is the same; select a Product from the - top drop-down box, select a specific component if you want one, and press - <quote>Exclude</quote>. The Product/Component pairing will show up in the - <quote>Exclusions</quote> box on the right. - </para> - - <para> - This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any - products/components that appearing in the <quote>Inclusions</quote> box - (or which fall under the appropriate <quote>__Any__</quote>). - This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on - any products appearing in the <quote>Exclusions</quote> box. - <emphasis> IMPORTANT: Exclusions override inclusions.</emphasis> - </para> - - <para> - You may select a Product without selecting a specific Component, - but you can't select a Component without a Product, or to select a - Component that does not belong to the named Product. If you do so, - Bugzilla will display an error message, even if all your products - have a component by that name. - </para> - - <para><emphasis>Example:</emphasis> Let's say you have a product called - <quote>Jet Plane</quote> that has thousands of components. You want - to be able to ask if a problem should be fixed in the next model of - plane you release. We'll call the flag <quote>fixInNext</quote>. - But, there's one component in <quote>Jet Plane,</quote> - called <quote>Pilot.</quote> It doesn't make sense to release a - new pilot, so you don't want to have the flag show up in that component. - So, you include <quote>Jet Plane:__Any__</quote> and you exclude - <quote>Jet Plane:Pilot</quote>. - </para> - </section> - - <section id="flags-create-field-sortkey"> - <title>Sort Key</title> - <para> - Flags normally show up in alphabetical order. If you want them to - show up in a different order, you can use this key set the order on each flag. - Flags with a lower sort key will appear before flags with a higher - sort key. Flags that have the same sort key will be sorted alphabetically, - but they will still be after flags with a lower sort key, and before flags - with a higher sort key. - </para> - <para> - <emphasis>Example:</emphasis> I have AFlag (Sort Key 100), BFlag (Sort Key 10), - CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in - the order: DFlag, BFlag, CFlag, AFlag. - </para> - </section> - - <section id="flags-create-field-active"> - <title>Active</title> - <para> - Sometimes, you might want to keep old flag information in the - Bugzilla database, but stop users from setting any new flags of this type. - To do this, uncheck <quote>active</quote>. Deactivated - flags will still show up in the UI if they are ?, +, or -, but they - may only be cleared (unset), and cannot be changed to a new value. - Once a deactivated flag is cleared, it will completely disappear from a - bug/attachment, and cannot be set again. - </para> - </section> - - <section id="flags-create-field-requestable"> - <title>Requestable</title> - <para> - New flags are, by default, <quote>requestable</quote>, meaning that they - offer users the <quote>?</quote> option, as well as <quote>+</quote> - and <quote>-</quote>. - To remove the ? option, uncheck <quote>requestable</quote>. - </para> - </section> - - <section id="flags-create-field-specific"> - <title>Specifically Requestable</title> - <para> - By default this box is checked for new flags, meaning that users may make - flag requests of specific individuals. Unchecking this box will remove the - text box next to a flag; if it is still requestable, then requests may - only be made <quote>to the wind.</quote> Removing this after specific - requests have been made will not remove those requests; that data will - stay in the database (though it will no longer appear to the user). - </para> - </section> - - <section id="flags-create-field-multiplicable"> - <title>Multiplicable</title> - <para> - Any flag with <quote>Multiplicable</quote> set (default for new flags is 'on') - may be set more than once. After being set once, an unset flag - of the same type will appear below it with <quote>addl.</quote> (short for - <quote>additional</quote>) before the name. There is no limit to the number of - times a Multiplicable flags may be set on the same bug/attachment. - </para> - </section> - - <section id="flags-create-field-cclist"> - <title>CC List</title> - - <para> - If you want certain users to be notified every time this flag is - set to ?, -, +, or unset, add them here. This is a comma-separated - list of email addresses that need not be restricted to Bugzilla usernames. - </para> - </section> - - <section id="flags-create-grant-group"> - <title>Grant Group</title> - <para> - When this field is set to some given group, only users in the group - can set the flag to <quote>+</quote> and <quote>-</quote>. This - field does not affect who can request or cancel the flag. For that, - see the <quote>Request Group</quote> field below. If this field - is left blank, all users can set or delete this flag. This field is - useful for restricting which users can approve or reject requests. - </para> - </section> - - <section id="flags-create-request-group"> - <title>Request Group</title> - <para> - When this field is set to some given group, only users in the group - can request or cancel this flag. Note that this field has no effect - if the <quote>grant group</quote> field is empty. You can set the - value of this field to a different group, but both fields have to be - set to a group for this field to have an effect. - </para> - </section> - </section> <!-- flags-create --> - - <section id="flags-delete"> - <title>Deleting a Flag</title> - - <para> - When you are at the <quote>Administer Flag Types</quote> screen, - you will be presented with a list of Bug flags and a list of Attachment - Flags. - </para> - <para> - To delete a flag, click on the <quote>Delete</quote> link next to - the flag description. - </para> - <warning> - <para> - Once you delete a flag, it is <emphasis>gone</emphasis> from - your Bugzilla. All the data for that flag will be deleted. - Everywhere that flag was set, it will disappear, - and you cannot get that data back. If you want to keep flag data, - but don't want anybody to set any new flags or change current flags, - unset <quote>active</quote> in the flag Edit form. - </para> - </warning> - </section> - - </section> <!-- flags-admin --> - - <!-- XXX We should add a "Uses of Flags" section, here, with examples. --> - - </section> <!-- flags --> - - <section id="keywords"> - <title>Keywords</title> - - <para> - The administrator can define keywords which can be used to tag and - categorise bugs. For example, the keyword "regression" is commonly used. - A company might have a policy stating all regressions - must be fixed by the next release - this keyword can make tracking those - bugs much easier. - </para> - <para> - Keywords are global, rather than per-product. If the administrator changes - a keyword currently applied to any bugs, the keyword cache must be rebuilt - using the <xref linkend="sanitycheck"/> script. Currently keywords can not - be marked obsolete to prevent future usage. - </para> - <para> - Keywords can be created, edited or deleted by clicking the "Keywords" - link in the admin page. There are two fields for each keyword - the keyword - itself and a brief description. Once created, keywords can be selected - and applied to individual bugs in that bug's "Details" section. - </para> - </section> - - <section id="custom-fields"> - <title>Custom Fields</title> - - <para> - The release of Bugzilla 3.0 added the ability to create Custom Fields. - Custom Fields are treated like any other field - they can be set in bugs - and used for search queries. Administrators should keep in mind that - adding too many fields can make the user interface more complicated and - harder to use. Custom Fields should be added only when necessary and with - careful consideration. - </para> - <tip> - <para> - Before adding a Custom Field, make sure that Bugzilla can not already - do the desired behavior. Many Bugzilla options are not enabled by - default, and many times Administrators find that simply enabling - certain options that already exist is sufficient. - </para> - </tip> - <para> - Administrators can manage Custom Fields using the - <quote>Custom Fields</quote> link on the Administration page. The Custom - Fields administration page displays a list of Custom Fields, if any exist, - and a link to "Add a new custom field". - </para> - - <section id="add-custom-fields"> - <title>Adding Custom Fields</title> - - <para> - To add a new Custom Field, click the "Add a new custom field" link. This - page displays several options for the new field, described below. - </para> - - <para> - The following attributes must be set for each new custom field: - <itemizedlist> - <listitem> - <para> - <emphasis>Name:</emphasis> - The name of the field in the database, used internally. This name - MUST begin with <quote>cf_</quote> to prevent confusion with - standard fields. If this string is omitted, it will - be automatically added to the name entered. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Description:</emphasis> - A brief string which is used as the label for this Custom Field. - That is the string that users will see, and should be - short and explicit. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Type:</emphasis> - The type of field to create. There are - several types available: - <simplelist> - <member> - Large Text Box: A multiple line box for entering free text. - </member> - <member> - Free Text: A single line box for entering free text. - </member> - <member> - Multiple-Selection Box: A list box where multiple options - can be selected. After creating this field, it must be edited - to add the selection options. See - <xref linkend="edit-values-list" /> for information about - editing legal values. - </member> - <member> - Drop Down: A list box where only one option can be selected. - After creating this field, it must be edited to add the - selection options. See - <xref linkend="edit-values-list" /> for information about - editing legal values. - </member> - <member> - Date/Time: A date field. This field appears with a - calendar widget for choosing the date. - </member> - </simplelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Sortkey:</emphasis> - Integer that determines in which order Custom Fields are - displayed in the User Interface, especially when viewing a bug. - Fields with lower values are displayed first. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Can be set on bug creation:</emphasis> - Boolean that determines whether this field can be set on - bug creation. If not selected, then a bug must be created - before this field can be set. See <xref linkend="bugreports" /> - for information about filing bugs. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Displayed in bugmail for new bugs:</emphasis> - Boolean that determines whether the value set on this field - should appear in bugmail when the bug is filed. This attribute - has no effect if the field cannot be set on bug creation. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Is obsolete:</emphasis> - Boolean that determines whether this field should - be displayed at all. Obsolete Custom Fields are hidden. - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="edit-custom-fields"> - <title>Editing Custom Fields</title> - - <para> - As soon as a Custom Field is created, its name and type cannot be - changed. If this field is a drop down menu, its legal values can - be set as described in <xref linkend="edit-values-list" />. All - other attributes can be edited as described above. - </para> - </section> - - <section id="delete-custom-fields"> - <title>Deleting Custom Fields</title> - - <para> - It is only possible to delete obsolete Custom Fields - if the field has never been used in the database. - To remove a field which already has content, - mark it as obsolete. - </para> - </section> - </section> - - <section id="edit-values"> - <title>Legal Values</title> - - <para> - Since Bugzilla 2.20 RC1, legal values for Operating Systems, platforms, - bug priorities and severities can be edited from the User Interface - directly. This means that it is no longer required to manually edit - <filename>localconfig</filename>. Starting with Bugzilla 2.23.3, - the list of valid resolutions can be customized from the same interface. - Since Bugzilla 3.1.1 the list of valid bug statuses can be customized - as well. - </para> - - <section id="edit-values-list"> - <title>Viewing/Editing legal values</title> - <para> - Editing legal values requires <quote>admin</quote> privileges. - Select "Legal Values" from the Administration page. A list of all - fields, both system fields and Custom Fields, for which legal values - can be edited appears. Click a field name to edit its legal values. - </para> - <para> - There is no limit to how many values a field can have, but each value - must be unique to that field. The sortkey is important to display these - values in the desired order. - </para> - </section> - - <section id="edit-values-delete"> - <title>Deleting legal values</title> - <para> - Legal values from Custom Fields can be deleted, but only if the - following two conditions are respected: - </para> - - <orderedlist> - <listitem> - <para>The value is not used by default for the field.</para> - </listitem> - - <listitem> - <para>No bug is currently using this value.</para> - </listitem> - </orderedlist> - - <para> - If any of these conditions is not respected, the value cannot be deleted. - The only way to delete these values is to reassign bugs to another value - and to set another value as default for the field. - </para> - </section> - </section> - - <section id="bug_status_workflow"> - <title>Bug Status Workflow</title> - - <para> - The bug status workflow is no longer hardcoded but can be freely customized - from the web interface. Only one bug status cannot be renamed nor deleted, - UNCONFIRMED, but the workflow involving it is free. The configuration - page displays all existing bug statuses twice, first on the left for bug - statuses we come from and on the top for bug statuses we move to. - If the checkbox is checked, then the transition between the two bug statuses - is legal, else it's forbidden independently of your privileges. The bug status - used for the "duplicate_or_move_bug_status" parameter must be part of the - workflow as that is the bug status which will be used when duplicating or - moving a bug, so it must be available from each bug status. - </para> - <para> - When the workflow is set, the "View Current Triggers" link below the table - lets you set which transitions require a comment from the user. - </para> - </section> - - <section id="voting"> - <title>Voting</title> - - <para>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.</para> - - <para>To modify Voting settings:</para> - - <orderedlist> - <listitem> - <para>Navigate to the "Edit product" screen for the Product you - wish to modify</para> - </listitem> - - <listitem> - <para><emphasis>Maximum Votes per person</emphasis>: - Setting this field to "0" disables voting.</para> - </listitem> - - <listitem> - <para><emphasis>Maximum Votes a person can put on a single - bug</emphasis>: - 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.</para> - </listitem> - - <listitem> - <para><emphasis>Number of votes a bug in this product needs to - automatically get out of the UNCONFIRMED state</emphasis>: - Setting this field to "0" disables the automatic move of - bugs from UNCONFIRMED to NEW. - </para> - </listitem> - - <listitem> - <para>Once you have adjusted the values to your preference, click - "Update".</para> - </listitem> - </orderedlist> - </section> - - <section id="quips"> - <title>Quips</title> - - <para> - Quips are small text messages that can be configured to appear - next to search results. A Bugzilla installation can have its own specific - quips. Whenever a quip needs to be displayed, a random selection - is made from the pool of already existing quips. - </para> - - <para> - Quips are controlled by the <emphasis>enablequips</emphasis> parameter. - It has several possible values: on, approved, frozen or off. - In order to enable quips approval you need to set this parameter - to "approved". In this way, users are free to submit quips for - addition but an administrator must explicitly approve them before - they are actually used. - </para> - - <para> - In order to see the user interface for the quips, it is enough to click - on a quip when it is displayed together with the search results. Or - it can be seen directly in the browser by visiting the quips.cgi URL - (prefixed with the usual web location of the Bugzilla installation). - Once the quip interface is displayed, it is enough to click the - "view and edit the whole quip list" in order to see the administration - page. A page with all the quips available in the database will - be displayed. - </para> - - <para> - Next to each tip there is a checkbox, under the - "Approved" column. Quips who have this checkbox checked are - already approved and will appear next to the search results. - The ones that have it unchecked are still preserved in the - database but they will not appear on search results pages. - User submitted quips have initially the checkbox unchecked. - </para> - - <para> - Also, there is a delete link next to each quip, - which can be used in order to permanently delete a quip. - </para> - </section> - - <section id="groups"> - <title>Groups and Group Security</title> - - <para> - Groups allow for separating bugs into logical divisions. - Groups are typically used to - to isolate bugs that should only be seen by certain people. For - example, a company might create a different group for each one of its customers - or partners. Group permissions could be set so that each partner or customer would - only have access to their own bugs. Or, groups might be used to create - variable access controls for different departments within an organization. - Another common use of groups is to associate groups with products, - creating isolation and access control on a per-product basis. - </para> - - <para> - Groups and group behaviors are controlled in several places: - </para> - - <orderedlist> - - <listitem> - <para> - The group configuration page. To view or edit existing groups, or to - create new groups, access the "Groups" link from the "Administration" - page. This section of the manual deals primarily with the aspect of - group controls accessed on this page. - </para> - </listitem> - - <listitem> - <para> - Global configuration parameters. Bugzilla has several parameters - that control the overall default group behavior and restriction - levels. For more information on the parameters that control - group behavior globally, see <xref linkend="param-group-security"/>. - </para> - - </listitem> - - <listitem> - <para> - Product association with groups. Most of the functionality of groups - and group security is controlled at the product level. Some aspects - of group access controls for products are discussed in this section, - but for more detail see <xref linkend="product-group-controls"/>. - </para> - </listitem> - - <listitem> - <para> - Group access for users. See <xref linkend="users-and-groups"/> for - details on how users are assigned group access. - </para> - </listitem> - - </orderedlist> - - <para> - Group permissions are such that if a bug belongs to a group, only members - of that group can see the bug. If a bug is in more than one group, only - members of <emphasis>all</emphasis> the groups that the bug is in can see - the bug. For information on granting read-only access to certain people and - full edit access to others, see <xref linkend="product-group-controls"/>. - </para> - - <note> - <para> - By default, bugs can also be seen by the Assignee, the Reporter, and - by everyone on the CC List, regardless of whether or not the bug would - typically be viewable by them. Visibility to the Reporter and CC List can - be overridden (on a per-bug basis) by bringing up the bug, finding the - section that starts with <quote>Users in the roles selected below...</quote> - and un-checking the box next to either 'Reporter' or 'CC List' (or both). - </para> - </note> - - <section id="create-groups"> - <title>Creating Groups</title> - - <para> - To create a new group, follow the steps below: - </para> - - <orderedlist> - - <listitem> - <para> - Select the <quote>Administration</quote> link in the page footer, - and then select the <quote>Groups</quote> link from the - Administration page. - </para> - </listitem> - - <listitem> - <para> - A table of all the existing groups is displayed. Below the table is a - description of all the fields. To create a new group, select the - <quote>Add Group</quote> link under the table of existing groups. - </para> - </listitem> - - <listitem> - <para> - There are five fields to fill out. These fields are documented below - the form. Choose a name and description for the group. Decide whether - this group should be used for bugs (in all likelihood this should be - selected). Optionally, choose a regular expression that will - automatically add any matching users to the group, and choose an - icon that will help identify user comments for the group. The regular - expression can be useful, for example, to automatically put all users - from the same company into one group (if the group is for a specific - customer or partner). - </para> - <note> - <para> - If <quote>User RegExp</quote> is filled out, users whose email - addresses match the regular expression will automatically be - members of the group as long as their email addresses continue - to match the regular expression. If their email address changes - and no longer matches the regular expression, they will be removed - from the group. Versions 2.16 and older of Bugzilla did not automatically - remove users who's email addresses no longer matched the RegExp. - </para> - </note> - <warning> - <para> - If specifying a domain in the regular expression, end - the regexp with a "$". Otherwise, when granting access to - "@mycompany\.com", access will also be granted to - 'badperson@mycompany.com.cracker.net'. Use the syntax, - '@mycompany\.com$' for the regular expression. - </para> - </warning> - </listitem> - - <listitem> - <para> - After the new group is created, it can be edited for additional options. - The "Edit Group" page allows for specifying other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group. For more details, see <xref linkend="edit-groups"/>. - </para> - </listitem> - </orderedlist> - - </section> - - <section id="edit-groups"> - <title>Editing Groups and Assigning Group Permissions</title> - - <para> - To access the "Edit Groups" page, select the - <quote>Administration</quote> link in the page footer, - and then select the <quote>Groups</quote> link from the Administration page. - A table of all the existing groups is displayed. Click on a group name - you wish to edit or control permissions for. - </para> - - <para> - The "Edit Groups" page contains the same five fields present when - creating a new group. Below that are two additional sections, "Group - Permissions," and "Mass Remove". The "Mass Remove" option simply removes - all users from the group who match the regular expression entered. The - "Group Permissions" section requires further explanation. - </para> - - <para> - The "Group Permissions" section on the "Edit Groups" page contains four sets - of permissions that control the relationship of this group to other - groups. If the 'usevisibilitygroups' parameter is in use (see - <xref linkend="parameters"/>) two additional sets of permissions are displayed. - Each set consists of two select boxes. On the left, a select box - with a list of all existing groups. On the right, a select box listing - all groups currently selected for this permission setting (this box will - be empty for new groups). The way these controls allow groups to relate - to one another is called <emphasis>inheritance</emphasis>. - Each of the six permissions is described below. - </para> - - <variablelist> - - <varlistentry> - - <term> - <emphasis>Groups That Are a Member of This Group</emphasis> - </term> - - <listitem> - <para> - Members of any groups selected here will automatically have - membership in this group. In other words, members of any selected - group will inherit membership in this group. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - - <term> - <emphasis>Groups That This Group Is a Member Of</emphasis> - </term> - - <listitem> - <para> - Members of this group will inherit membership to any group - selected here. For example, suppose the group being edited is - an Admin group. If there are two products (Product1 and Product2) - and each product has its - own group (Group1 and Group2), and the Admin group - should have access to both products, - simply select both Group1 and Group2 here. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - - <term> - <emphasis>Groups That Can Grant Membership in This Group</emphasis> - </term> - - <listitem> - <para> - The members of any group selected here will be able add users - to this group, even if they themselves are not in this group. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - - <term> - <emphasis>Groups That This Group Can Grant Membership In</emphasis> - </term> - - <listitem> - <para> - Members of this group can add users to any group selected here, - even if they themselves are not in the selected groups. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - - <term> - <emphasis>Groups That Can See This Group</emphasis> - </term> - - <listitem> - <para> - Members of any selected group can see the users in this group. - This setting is only visible if the 'usevisibilitygroups' parameter - is enabled on the Bugzilla Configuration page. See - <xref linkend="parameters"/> for information on configuring Bugzilla. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - - <term> - <emphasis>Groups That This Group Can See</emphasis> - </term> - - <listitem> - <para> - Members of this group can see members in any of the selected groups. - This setting is only visible if the 'usevisibilitygroups' parameter - is enabled on the the Bugzilla Configuration page. See - <xref linkend="parameters"/> for information on configuring Bugzilla. - </para> - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="users-and-groups"> - <title>Assigning Users to Groups</title> - - <para> - A User can become a member of a group in several ways: - </para> - - <orderedlist> - - <listitem> - <para> - The user can be explicitly placed in the group by editing - the user's profile. This can be done by accessing the "Users" page - from the "Administration" page. Use the search form to find the user - you want to edit group membership for, and click on their email - address in the search results to edit their profile. The profile - page lists all the groups, and indicates if the user is a member of - the group either directly or indirectly. More information on indirect - group membership is below. For more details on User administration, - see <xref linkend="useradmin"/>. - </para> - </listitem> - - <listitem> - <para> - The group can include another group of which the user is - a member. This is indicated by square brackets around the checkbox - next to the group name in the user's profile. - See <xref linkend="edit-groups"/> for details on group inheritance. - </para> - </listitem> - - <listitem> - <para> - The user's email address can match the regular expression - that has been specified to automatically grant membership to - the group. This is indicated by "*" around the check box by the - group name in the user's profile. - See <xref linkend="create-groups"/> for details on - the regular expression option when creating groups. - </para> - </listitem> - - </orderedlist> - - </section> - - <section> - <title>Assigning Group Controls to Products</title> - - <para> - The primary functionality of groups is derived from the relationship of - groups to products. The concepts around segregating access to bugs with - product group controls can be confusing. For details and examples on this - topic, see <xref linkend="product-group-controls" />. - </para> - - </section> - - </section> - - <section id="sanitycheck"> - <title>Checking and Maintaining Database Integrity</title> - - <para> - Over time it is possible for the Bugzilla database to become corrupt - or to have anomalies. - This could happen through normal usage of Bugzilla, manual database - administration outside of the Bugzilla user interface, or from some - other unexpected event. Bugzilla includes a "Sanity Check" script that - can perform several basic database checks, and repair certain problems or - inconsistencies. - </para> - <para> - To run the "Sanity Check" script, log in as an Administrator and click the - "Sanity Check" link in the admin page. Any problems that are found will be - displayed in red letters. If the script is capable of fixing a problem, - it will present a link to initiate the fix. If the script can not - fix the problem it will require manual database administration or recovery. - </para> - <para> - The "Sanity Check" script can also be run from the command line via the perl - script <filename>sanitycheck.pl</filename>. The script can also be run as - a <command>cron</command> job. Results will be delivered by email. - </para> - <para> - The "Sanity Check" script should be run on a regular basis as a matter of - best practice. - </para> - <warning> - <para> - The "Sanity Check" script is no substitute for a competent database - administrator. It is only designed to check and repair basic database - problems. - </para> - </warning> - - </section> - - <section id="upgrading"> - <title>Upgrading to New Releases</title> - - <para> - 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: - </para> - - <itemizedlist> - <listitem> - <para> - If the new version is a revision or a new point release - </para> - </listitem> - <listitem> - <para> - How many local changes (if any) have been made - </para> - </listitem> - </itemizedlist> - - <section id="upgrading-version-defns"> - <title>Version Definitions</title> - - <para> - Bugzilla displays the version you are using at the top of the home - page <filename>index.cgi</filename>. It looks something like - '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is - the Major Version. This does not change very often; - Bugzilla was 1.x.x when it was first created, and went to 2.x.x - when it was re-written in perl in Sept 1998. The major version - 3.x.x, released in early 2007, is pretty far from what the 2.x.x - series looked like, both about its UI and its code. - </para> - - <para> - The second number in the version is called the 'minor number', and - a release that changes the minor number is called a 'point release'. - An even number in this position (2.18, 2.20, 2.22, 3.0, 3.2, etc.) - represents a stable version, while an odd number (2.19, 2.21, 2.23, etc.) - represents a development version. In the past, stable point releases - were feature-based, coming when certain enhancements had been - completed, or the Bugzilla development team felt that enough - progress had been made overall. As of version 2.18, however, - Bugzilla has moved to a time-based release schedule; current plans - are to create a stable point release every 6 months or so after - 2.18 is deployed. - </para> - - <para> - The third number in the Bugzilla version represents a bugfix version. - Bugfix Revisions are released only to address security vulnerabilities - and, for a limited period, bug fixes. Once enough of these - bugfixes have accumulated (or a new security vulnerability is - identified and closed), a bugfix release is made. As an - example, 2.20.3 was a bugfix release, and improved on 2.20.2. - </para> - - <note> - <para> - When reading version numbers, everything separated by a point ('.') - should be read as a single number. It is <emphasis>not</emphasis> - the same as decimal. 2.22 is newer than 2.8 because minor version - 22 is greater than minor version 8. The now unsupported release 2.16.11 - was newer than 2.16.9 (because bugfix 11 is greater than bugfix 9. This is - confusing to some people who aren't used to dealing with software. - </para> - </note> - </section> - - <section id="upgrading-notifications"> - <title>Upgrading - Notifications</title> - - <para> - Bugzilla 3.0 introduces the ability to automatically notify - administrators when new releases are available, based on the - <literal>upgrade_notification</literal> parameter, see - <xref linkend="parameters"/>. Administrators will see these - notifications when they access the <filename>index.cgi</filename> - page, i.e. generally when logging in. Bugzilla will check once per - day for new releases, unless the parameter is set to - <quote>disabled</quote>. If you are behind a proxy, you may have to set - the <literal>proxy_url</literal> parameter accordingly. If the proxy - requires authentication, use the - <literal>http://user:pass@proxy_url/</literal> syntax. - </para> - </section> - - <section id="upgrading-methods"> - <title>Upgrading - Methods and Procedure</title> - <para> - There are three different ways to upgrade your installation. - </para> - - <orderedlist> - <listitem> - <para> - Using CVS (<xref linkend="upgrade-cvs"/>) - </para> - </listitem> - <listitem> - <para> - Downloading a new tarball (<xref linkend="upgrade-tarball"/>) - </para> - </listitem> - <listitem> - <para> - Applying the relevant patches (<xref linkend="upgrade-patches"/>) - </para> - </listitem> - </orderedlist> - - <para> - Each of these options has its own pros and cons; the one that's - right for you depends on how long it has been since you last - installed, the degree to which you have customized your installation, - and/or your network configuration. (Some discussion of the various - methods of updating compared with degree and methods of local - customization can be found in <xref linkend="template-method"/>.) - </para> - - <para> - The larger the jump you are trying to make, the more difficult it - is going to be to upgrade if you have made local customizations. - Upgrading from 2.22 to 2.22.1 should be fairly painless even if - you are heavily customized, but going from 2.18 to 3.0 is going - to mean a fair bit of work re-writing your local changes to use - the new files, logic, templates, etc. If you have done no local - changes at all, however, then upgrading should be approximately - the same amount of work regardless of how long it has been since - your version was released. - </para> - - <warning> - <para> - 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. - </para> - </warning> - - <para> - The examples in the following sections are written as though the - user were updating to version 2.22.1, but the procedures are the - same regardless of whether one is updating to a new point release - or simply trying to obtain a new bugfix release. Also, in the - examples the user's Bugzilla installation is found at - <filename>/var/www/html/bugzilla</filename>. If that is not the - same as the location of your Bugzilla installation, simply - substitute the proper paths where appropriate. - </para> - - <section id="upgrade-cvs"> - <title>Upgrading using CVS</title> - - <para> - Every release of Bugzilla, whether it is a point release or a bugfix, - is tagged in CVS. Also, every tarball that has been distributed since - version 2.12 has been created in such a way that it can be used with - CVS once it is unpacked. Doing so, however, requires that you are able - to access cvs-mirror.mozilla.org on port 2401, which may not be an - option or a possibility for some users, especially those behind a - highly restrictive firewall. - </para> - - <tip> - <para> - If you can, updating using CVS is probably the most painless - method, especially if you have a lot of local changes. - </para> - </tip> - - <para> - The following shows the sequence of commands needed to update a - Bugzilla installation via CVS, and a typical series of results. - </para> - - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>cvs login</command> -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis> -bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command> -P checksetup.pl -P collectstats.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl -<emphasis>(etc.)</emphasis> - </programlisting> - - <caution> - <para> - If a line in the output from <command>cvs update</command> begins - with a <computeroutput>C</computeroutput>, then 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. - </para> - </caution> - </section> - - <section id="upgrade-tarball"> - <title>Upgrading using the tarball</title> - - <para> - If you are unable (or unwilling) to use CVS, another option that's - always available is to obtain the latest tarball from the <ulink - url="http://www.bugzilla.org/download/">Download Page</ulink> and - create a new Bugzilla installation from that. - </para> - - <para> - This sequence of commands shows how to get the tarball from the - command-line; it is also possible to download it from the site - directly in a web browser. If you go that route, save the file - to the <filename class="directory">/var/www/html</filename> - directory (or its equivalent, if you use something else) and - omit the first three lines of the example. - </para> - - <programlisting> -bash$ <command>cd /var/www/html</command> -bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command> -<emphasis>(Output omitted)</emphasis> -bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command> -bugzilla-2.22.1/ -bugzilla-2.22.1/.cvsignore -<emphasis>(Output truncated)</emphasis> -bash$ <command>cd bugzilla-2.22.1</command> -bash$ <command>cp ../bugzilla/localconfig* .</command> -bash$ <command>cp -r ../bugzilla/data .</command> -bash$ <command>cd ..</command> -bash$ <command>mv bugzilla bugzilla.old</command> -bash$ <command>mv bugzilla-2.22.1 bugzilla</command> - </programlisting> - - <warning> - <para> - The <command>cp</command> commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. - </para> - </warning> - - <para> - This upgrade method will give you a clean install of Bugzilla with the - same version as the tarball. That's fine if you don't have any local - customizations that you want to maintain, but if you do then you will - need to reapply them by hand to the appropriate files. - </para> - - <para> - It's worth noting that since 2.12, the Bugzilla tarballs come - CVS-ready, so if you decide at a later date that you'd rather use - CVS as an upgrade method, your code will already be set up for it. - </para> - </section> - - <section id="upgrade-patches"> - <title>Upgrading using patches</title> - - <para> - If you are doing a bugfix upgrade -- that is, one where only the - last number of the revision changes, such as from 2.22 to 2.22.1 - -- then you have the option of obtaining and applying a patch file - from the <ulink - url="http://www.bugzilla.org/download/">Download Page</ulink>. - This file is made available by the <ulink - url="http://www.bugzilla.org/developers/profiles.html">Bugzilla - Development Team</ulink>, and is a collection of all the bug fixes - and security patches that have been made since the last bugfix - release. If you are planning to upgrade via patches, it is safer - to grab this developer-made patch file than to read the patch - notes and apply all (or even just some of) the patches oneself, - as sometimes patches on bugs get changed before they get checked in. - </para> - - <para> - As above, this example starts with obtaining the file via the - command line. If you have already downloaded it, you can omit the - first two commands. - </para> - - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command> -<emphasis>(Output omitted)</emphasis> -bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command> -bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command> -patching file checksetup.pl -patching file collectstats.pl -<emphasis>(etc.)</emphasis> - </programlisting> - - <warning> - <para> - Be aware that upgrading from a patch file does not change the - entries in your <filename class="directory">CVS</filename> directory. - This could make it more difficult to upgrade using CVS - (<xref linkend="upgrade-cvs"/>) in the future. - </para> - </warning> - - </section> - </section> - - <section id="upgrading-completion"> - <title>Completing Your Upgrade</title> - - <para> - Regardless of which upgrade method you choose, you will need to - run <command>./checksetup.pl</command> before your Bugzilla - upgrade will be complete. - </para> - - <programlisting> -bash$ <command>cd bugzilla</command> -bash$ <command>./checksetup.pl</command> - </programlisting> - - <warning> - <para> - The period at the beginning of the command - <command>./checksetup.pl</command> is important and can not - be omitted. - </para> - </warning> - - <para> - If you have done a lot of local modifications, it wouldn't hurt - to run the Bugzilla Testing suite. This is not a required step, - but it isn't going to hurt anything, and might help point out - some areas that could be improved. (More information on the - test suite can be had by following this link to the appropriate - section in the <ulink - url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers' - Guide</ulink>.) - </para> - - </section> - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/conventions.xml b/docs/xml/conventions.xml deleted file mode 100644 index 70e6624f7..000000000 --- a/docs/xml/conventions.xml +++ /dev/null @@ -1,164 +0,0 @@ -<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<section id="conventions"> - <title>Document Conventions</title> - - <indexterm zone="conventions"> - <primary>conventions</primary> - </indexterm> - - <para>This document uses the following conventions:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Descriptions</entry> - - <entry>Appearance</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Caution</entry> - - <entry> - <caution> - <para>Don't run with scissors!</para> - </caution> - </entry> - </row> - - <row> - <entry>Hint or Tip</entry> - - <entry> - <tip> - <para>For best results... </para> - </tip> - </entry> - </row> - - <row> - <entry>Note</entry> - - <entry> - <note> - <para>Dear John...</para> - </note> - </entry> - </row> - - <row> - <entry>Warning</entry> - - <entry> - <warning> - <para>Read this or the cat gets it.</para> - </warning> - </entry> - </row> - - <row> - <entry>File or directory name</entry> - - <entry> - <filename>filename</filename> - </entry> - </row> - - <row> - <entry>Command to be typed</entry> - - <entry> - <command>command</command> - </entry> - </row> - - <row> - <entry>Application name</entry> - - <entry> - <application>application</application> - </entry> - </row> - - <row> - <entry> - Normal user's prompt under bash shell</entry> - - <entry>bash$</entry> - </row> - - <row> - <entry> - Root user's prompt under bash shell</entry> - - <entry>bash#</entry> - </row> - - <row> - <entry> - Normal user's prompt under tcsh shell</entry> - - <entry>tcsh$</entry> - </row> - - <row> - <entry>Environment variables</entry> - - <entry> - <envar>VARIABLE</envar> - </entry> - </row> - - <row> - <entry>Term found in the glossary</entry> - - <entry> - <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm> - </entry> - </row> - - <row> - <entry>Code example</entry> - - <entry> - <programlisting><sgmltag class="starttag">para</sgmltag> -Beginning and end of paragraph -<sgmltag class="endtag">para</sgmltag></programlisting> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - 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 &bzg-bugs; component. - </para> - -</section> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/customization.xml b/docs/xml/customization.xml deleted file mode 100644 index bb89cb12b..000000000 --- a/docs/xml/customization.xml +++ /dev/null @@ -1,820 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<chapter id="customization"> - <title>Customizing Bugzilla</title> - - <section id="cust-skins"> - <title>Custom Skins</title> - - <para> - Bugzilla allows you to have multiple skins. These are custom CSS and possibly - also custom images for Bugzilla. To create a new custom skin, you have two - choices: - <itemizedlist> - <listitem> - <para> - Make a single CSS file, and put it in the - <filename>skins/contrib</filename> directory. - </para> - </listitem> - <listitem> - <para> - Make a directory that contains all the same CSS file - names as <filename>skins/standard/</filename>, and put - your directory in <filename>skins/contrib/</filename>. - </para> - </listitem> - </itemizedlist> - </para> - - <para> - After you put the file or the directory there, make sure to run checksetup.pl - so that it can reset the file permissions correctly. - </para> - <para> - After you have installed the new skin, it will show up as an option in the - user's General Preferences. If you would like to force a particular skin on all - users, just select it in the Default Preferences and then uncheck "Enabled" on - the preference. - </para> - </section> - - <section id="cust-templates"> - <title>Template Customization</title> - - <para> - 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. - </para> - - <para> - 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 - <xref linkend="template-http-accept"/>. - </para> - - <section id="template-directory"> - <title>Template Directory Structure</title> - <para> - The template directory structure starts with top level directory - named <filename>template</filename>, which contains a directory - for each installed localization. The next level defines the - language used in the templates. Bugzilla comes with English - templates, so the directory name is <filename>en</filename>, - and we will discuss <filename>template/en</filename> throughout - the documentation. Below <filename>template/en</filename> is the - <filename>default</filename> directory, which contains all the - standard templates shipped with Bugzilla. - </para> - - <warning> - <para> - A directory <filename>data/templates</filename> also exists; - this is where Template Toolkit puts the compiled versions of - the templates from either the default or custom directories. - <emphasis>Do not</emphasis> directly edit the files in this - directory, or all your changes will be lost the next time - Template Toolkit recompiles the templates. - </para> - </warning> - </section> - - <section id="template-method"> - <title>Choosing a Customization Method</title> - <para> - If you want to edit Bugzilla's templates, the first decision - you must make is how you want to go about doing so. There are two - choices, and which you use depends mainly on the scope of your - modifications, and the method you plan to use to upgrade Bugzilla. - </para> - - <para> - The first method of making customizations is to directly edit the - templates found in <filename>template/en/default</filename>. - This is probably the best way to go about it if you are going to - be upgrading Bugzilla through CVS, because if you then execute - a <command>cvs update</command>, any changes you have made will - be merged automagically with the updated versions. - </para> - - <note> - <para> - If you use this method, and CVS conflicts occur during an - update, the conflicted templates (and possibly other parts - of your installation) will not work until they are resolved. - </para> - </note> - - <para> - The second method is to copy the templates to be modified - into a mirrored directory structure under - <filename>template/en/custom</filename>. Templates in this - directory structure automatically override any identically-named - and identically-located templates in the - <filename>default</filename> directory. - </para> - - <note> - <para> - The <filename>custom</filename> directory does not exist - at first and must be created if you want to use it. - </para> - </note> - - <para> - The second method of customization should be used if you - use the overwriting method of upgrade, because otherwise - your changes will be lost. This method may also be 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. - </para> - - <para> - Using this method, your installation may break if incompatible - changes are made to the template interface. Such changes should - 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. - </para> - - <note> - <para> - Regardless of which method you choose, it is recommended that - you run <command>./checksetup.pl</command> after creating or - editing any templates in the <filename>template/en/default</filename> - directory, and after editing any templates in the - <filename>custom</filename> directory. - </para> - </note> - - <warning> - <para> - It is <emphasis>required</emphasis> that you run - <command>./checksetup.pl</command> after creating a new - template in the <filename>custom</filename> directory. Failure - to do so will raise an incomprehensible error message. - </para> - </warning> - </section> - - <section id="template-edit"> - <title>How To Edit Templates</title> - - <note> - <para> - 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 - <ulink url="http://www.bugzilla.org/docs/developer.html">Developers' - Guide</ulink>. - </para> - </note> - - <para> - 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 - <ulink url="http://www.template-toolkit.org">Template Toolkit home - page</ulink>. - </para> - - <para> - 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, i.e. &lt;. 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. - </para> - - <para> - 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, i.e. %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. - </para> - - <para> - Editing templates is a good way of doing a <quote>poor man's custom - fields</quote>. - For example, if you don't use the Status Whiteboard, but want to have - a free-form text entry box for <quote>Build Identifier</quote>, - 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. - </para> - - </section> - - - <section id="template-formats"> - <title>Template Formats and Types</title> - - <para> - Some CGI's have the ability to use more than one template. For example, - <filename>buglist.cgi</filename> can output itself as RDF, or as two - formats of HTML (complex and simple). The mechanism that provides this - feature is extensible. - </para> - - <para> - Bugzilla can support different types of output, which again can have - multiple formats. In order to request a certain type, you can append - the &ctype=<contenttype> (such as rdf or html) to the - <filename><cginame>.cgi</filename> URL. If you would like to - retrieve a certain format, you can use the &format=<format> - (such as simple or complex) in the URL. - </para> - - <para> - To see if a CGI supports multiple output formats and types, grep the - CGI for <quote>get_format</quote>. If it's not present, adding - multiple format/type support isn't too hard - see how it's done in - other CGIs, e.g. config.cgi. - </para> - - <para> - 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. - </para> - - <para> - Write your template in whatever markup or text style is appropriate. - </para> - - <para> - You now need to decide what content type you want your template - served as. The content types are defined in the - <filename>Bugzilla/Constants.pm</filename> file in the - <filename>contenttypes</filename> - constant. If your content type is not there, add it. Remember - the three- or four-letter tag assigned to your content type. - This tag will be part of the template filename. - </para> - - <note> - <para> - After adding or changing a content type, it's suitable to edit - <filename>Bugzilla/Constants.pm</filename> in order to reflect - the changes. Also, the file should be kept up to date after an - upgrade if content types have been customized in the past. - </para> - </note> - - <para> - Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>. - Try out the template by calling the CGI as - <filename><cginame>.cgi?format=<formatname>&ctype=<type></filename> . - </para> - </section> - - - <section id="template-specific"> - <title>Particular Templates</title> - - <para> - There are a few templates you may be particularly interested in - customizing for your installation. - </para> - - <para> - <command>index.html.tmpl</command>: - This is the Bugzilla front page. - </para> - - <para> - <command>global/header.html.tmpl</command>: - 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. - </para> - - <para> - <command>global/banner.html.tmpl</command>: - This contains the <quote>banner</quote>, 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. - </para> - - <para> - <command>global/footer.html.tmpl</command>: - 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. - </para> - - <para> - <command>global/variables.none.tmpl</command>: - This defines a list of terms that may be changed in order to - <quote>brand</quote> the Bugzilla instance In this way, terms - like <quote>bugs</quote> can be replaced with <quote>issues</quote> - across the whole Bugzilla installation. The name - <quote>Bugzilla</quote> and other words can be customized as well. - </para> - - <para> - <command>list/table.html.tmpl</command>: - This template controls the appearance of the bug lists created - by Bugzilla. Editing this template allows per-column control of - the width and title of a column, the maximum display length of - each entry, and the wrap behaviour of long entries. - For long bug lists, Bugzilla inserts a 'break' every 100 bugs by - default; this behaviour is also controlled by this template, and - that value can be modified here. - </para> - - <para> - <command>bug/create/user-message.html.tmpl</command>: - 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. - </para> - - <para> - <command>bug/process/midair.html.tmpl</command>: - This is the page used if two people submit simultaneous changes to the - same bug. The second person to submit their changes will get this page - to tell them what the first person did, and ask if they wish to - overwrite those changes or go back and revisit the bug. The default - title and header on this page read "Mid-air collision detected!" If - you work in the aviation industry, or other environment where this - might be found offensive (yes, we have true stories of this happening) - you'll want to change this to something more appropriate for your - environment. - </para> - - <para> - <command>bug/create/create.html.tmpl</command> and - <command>bug/create/comment.txt.tmpl</command>: - You may not wish to go to the effort of creating custom fields in - Bugzilla, yet you want to make sure that each bug report contains - a number of pieces of important information for which there is not - a special field. The bug entry system has been designed in an - extensible fashion to enable you to add arbitrary HTML widgets, - such as drop-down lists or textboxes, to the bug entry page - and have their values appear formatted in the initial comment. - A hidden field that indicates the format should be added inside - the form in order to make the template functional. Its value should - be the suffix of the template filename. For example, if the file - is called <filename>create-cust.html.tmpl</filename>, then - <programlisting><input type="hidden" name="format" value="cust"></programlisting> - should be used inside the form. - </para> - - <para> - An example of this is the mozilla.org - <ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&format=guided">guided - bug submission form</ulink>. The code for this comes with the Bugzilla - distribution as an example for you to copy. It can be found in the - files - <filename>create-guided.html.tmpl</filename> and - <filename>comment-guided.html.tmpl</filename>. - </para> - - <para> - So to use this feature, create a custom template for - <filename>enter_bug.cgi</filename>. The default template, on which you - could base it, is - <filename>custom/bug/create/create.html.tmpl</filename>. - Call it <filename>create-<formatname>.html.tmpl</filename>, and - in it, add widgets for each piece of information you'd like - collected - such as a build number, or set of steps to reproduce. - </para> - - <para> - Then, create a template like - <filename>custom/bug/create/comment.txt.tmpl</filename>, and call it - <filename>comment-<formatname>.txt.tmpl</filename>. This - template should reference the form fields you have created using - the syntax <filename>[% form.<fieldname> %]</filename>. When a - bug report is - submitted, the initial comment attached to the bug report will be - formatted according to the layout of this template. - </para> - - <para> - For example, if your custom enter_bug template had a field - <programlisting><input type="text" name="buildid" size="30"></programlisting> - and then your comment.txt.tmpl had - <programlisting>BuildID: [% form.buildid %]</programlisting> - then something like - <programlisting>BuildID: 20020303</programlisting> - would appear in the initial comment. - </para> - </section> - - - <section id="template-http-accept"> - <title>Configuring Bugzilla to Detect the User's Language</title> - - <para>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 <ulink - url="http://www.bugzilla.org/download.html#localizations"/>. Instructions - for submitting new languages are also available from that location. - </para> - </section> - - </section> - - <section id="cust-hooks"> - <title>The Bugzilla Extension Mechanism</title> - - <warning> - <para> - Custom extensions require Template Toolkit version 2.12 or - above, or the application of a patch. See <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=239112">bug - 239112</ulink> for details. - </para> - </warning> - - <para> - Extensions are a way for extensions to Bugzilla to insert code - into the standard Bugzilla templates and source files - without modifying these files themselves. The extension mechanism - defines a consistent API for extending the standard templates and source files - 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. Furthermore, they make it easy to install - and remove extensions as each extension is nothing more than a - simple directory structure. - </para> - - <para> - There are two main types of hooks: code hooks and template hooks. Code - hooks allow extensions to invoke code at specific points in various - source files, while template hooks allow extensions to add elements to - the Bugzilla user interface. - </para> - - <para> - A hook is just a named place in a standard source or template file - where extension source code or template files for that hook get processed. - Each extension has a corresponding directory in the Bugzilla directory - tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>). Hooking - an extension source file or template to a hook is as simple as putting - the extension file into extension's template or code directory. - When Bugzilla processes the source file or template and reaches the hook, - it will process all extension files in the hook's directory. - The hooks themselves can be added into any source file or standard template - upon request by extension authors. - </para> - - <para> - To use hooks to extend Bugzilla, first make sure there is - a hook at the appropriate place within the source file or template you - want to extend. The exact appearance of a hook depends on if the hook - is a code hook or a template hook. - </para> - - <para> - Code hooks appear in Bugzilla source files as a single method call - in the format <literal role="code">Bugzilla::Hook->process("<varname>name</varname>");</literal>. - For instance, <filename>enter_bug.cgi</filename> may invoke the hook - "<varname>enter_bug-entrydefaultvars</varname>". Thus, a source file at - <filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename> - will be automatically invoked when the code hook is reached. - </para> - - <para> - Template hooks appear in the standard Bugzilla templates as a - single directive in the format - <literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>, - where <varname>name</varname> is the unique name of the hook. - </para> - - <para> - If you aren't sure what you want to extend or just want to browse the - available hooks, either use your favorite multi-file search - tool (e.g. <command>grep</command>) to search the standard templates - for occurrences of <methodname>Hook.process</methodname> or the source - files for occurrences of <methodname>Bugzilla::Hook::process</methodname>. - </para> - - <para> - If there is no hook at the appropriate place within the Bugzilla - source file or template you want to extend, - <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface">file - a bug requesting one</ulink>, specifying: - </para> - - <simplelist> - <member>the source or template file for which you are - requesting a hook;</member> - <member> - where in the file you would like the hook to be placed - (line number/position for latest version of the file in CVS - or description of location); - </member> - <member>the purpose of the hook;</member> - <member>a link to information about your extension, if any.</member> - </simplelist> - - <para> - The Bugzilla reviewers will promptly review each hook request, - name the hook, add it to the template or source file, and check - the new version of the template into CVS. - </para> - - <para> - 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. - </para> - - <para> - After making sure the hook you need exists (or getting it added if not), - add your extension to the directory within the Bugzilla - extensions tree corresponding to the hook. - </para> - - <para> - That's it! Now, when the source file or template containing the hook - is processed, your extension file will be processed at the point - where the hook appears. - </para> - - <para> - For example, let's say you have an extension named Projman that adds - project management capabilities to Bugzilla. Projman has an - administration interface <filename>edit-projects.cgi</filename>, - 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. - </para> - - <para> - The navigation bar is generated by the template file - <filename>useful-links.html.tmpl</filename>, which is located in - the <filename>global/</filename> subdirectory on the standard Bugzilla - template path - <filename>BUGZILLA_ROOT/template/en/default/</filename>. - Looking in <filename>useful-links.html.tmpl</filename>, you find - the following hook at the end of the list of standard Bugzilla - administration links: - </para> - - <programlisting><![CDATA[... - [% ', <a href="editkeywords.cgi">keywords</a>' - IF user.groups.editkeywords %] - [% Hook.process("edit") %] -...]]></programlisting> - - <para> - The corresponding extension file for this hook is - <filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl</filename>. - You then create that template file and add the following constant: - </para> - - <programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting> - - <para> - Voila! The link now appears after the other administration links in the - navigation bar for users in the <literal>projman_admins</literal> group. - </para> - - <para> - Now, let us say your extension adds a custom "project_manager" field - to enter_bug.cgi. You want to modify the CGI script to set the default - project manager to be productname@company.com. Looking at - <filename>enter_bug.cgi</filename>, you see the enter_bug-entrydefaultvars - hook near the bottom of the file before the default form values are set. - The corresponding extension source file for this hook is located at - <filename>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</filename>. - You then create that file and add the following: - </para> - - <programlisting>$default{'project_manager'} = $product.'@company.com';</programlisting> - - <para> - This code will be invoked whenever enter_bug.cgi is executed. - Assuming that the rest of the customization was completed (e.g. the - custom field was added to the enter_bug template and the required hooks - were used in process_bug.cgi), the new field will now have this - default value. - </para> - - <para> - Notes: - </para> - - <itemizedlist> - <listitem> - <para> - If your extension includes entirely new templates in addition to - extensions of standard templates, it should store those new - templates in its - <filename>BUGZILLA_ROOT/extensions/template/en/</filename> - directory. Extension template directories, like the - <filename>default/</filename> and <filename>custom/</filename> - directories, are part of the template search path, so putting templates - there enables them to be found by the template processor. - </para> - - <para> - The template processor looks for templates first in the - <filename>custom/</filename> directory (i.e. templates added by the - specific installation), then in the <filename>extensions/</filename> - directory (i.e. templates added by extensions), and finally in the - <filename>default/</filename> directory (i.e. the standard Bugzilla - templates). Thus, installation-specific templates override both - default and extension templates. - </para> - </listitem> - - <listitem> - <para> - If you are looking to customize Bugzilla, you can also take advantage - of template hooks. To do so, create a directory in - <filename>BUGZILLA_ROOT/template/en/custom/hook/</filename> - that corresponds to the hook you wish to use, then place your - customization templates into those directories. For example, - if you wanted to use the hook "end" in - <filename>global/useful-links.html.tmpl</filename>, you would - create the directory <filename>BUGZILLA_ROOT/template/en/custom/hook/ - global/useful-links.html.tmpl/end/</filename> and add your customization - template to this directory. - </para> - - <para> - Obviously this method of customizing Bugzilla only lets you add code - to the standard source files and 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. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="cust-change-permissions"> - <title>Customizing Who Can Change What</title> - - <warning> - <para> - 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. - </para> - </warning> - - <para> - 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. - </para> - - <para> - By default, assignees, QA owners and users - with <emphasis>editbugs</emphasis> privileges can edit all fields of bugs, - except group restrictions (unless they are members of the groups they - are trying to change). Bug reporters also have the ability to edit some - fields, but in a more restrictive manner. Other users, without - <emphasis>editbugs</emphasis> privileges, can not edit - bugs, except to comment and add themselves to the CC list. - </para> - - <para> - 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 method is called - <filename>check_can_change_field()</filename>, - and is found in <filename>Bug.pm</filename> in your - Bugzilla/ directory. If you open that file and search for - <quote>sub check_can_change_field</quote>, you'll find it. - </para> - - <para> - 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 <quote>plumbing</quote> which makes the rest of the function work. - In between those sections, you'll find snippets of code like: - <programlisting> # Allow the assignee to change anything. - if ($ownerid eq $whoid) { - return 1; - }</programlisting> - It's fairly obvious what this piece of code does. - </para> - - <para> - So, how does one go about changing this function? Well, simple changes - can be made just by removing pieces - for example, if you wanted to - prevent any user adding a comment to a bug, just remove the lines marked - <quote>Allow anyone to change comments.</quote> If you don't want the - Reporter to have any special rights on bugs they have filed, just - remove the entire section that deals with the Reporter. - </para> - - <para> - 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.: - <programlisting> if ($field eq "qacontact") { - if (Bugzilla->user->groups("quality_assurance")) { - return 1; - } - else { - return 0; - } - }</programlisting> - This says that only users in the group "quality_assurance" can change - the QA Contact field of a bug. - </para> - - <para> - Getting more weird: - <programlisting><![CDATA[ if (($field eq "priority") && - (Bugzilla->user->email =~ /.*\@example\.com$/)) - { - if ($oldvalue eq "P1") { - return 1; - } - else { - return 0; - } - }]]></programlisting> - 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. - </para> - - <warning> - <para> - If you are modifying <filename>process_bug.cgi</filename> in any - way, do not change the code that is bounded by DO_NOT_CHANGE blocks. - Doing so could compromise security, or cause your installation to - stop working entirely. - </para> - </warning> - - <para> - For a list of possible field names, look at the bugs table in the - database. If you need help writing custom rules for your organization, - ask in the newsgroup. - </para> - </section> - - <!-- Integrating Bugzilla with Third-Party Tools --> - &integration; - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/dbschema.mysql b/docs/xml/dbschema.mysql deleted file mode 100644 index 8b1378917..000000000 --- a/docs/xml/dbschema.mysql +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/xml/faq.xml b/docs/xml/faq.xml deleted file mode 100644 index 22f0144ab..000000000 --- a/docs/xml/faq.xml +++ /dev/null @@ -1,1659 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> - -<appendix id="faq"> - <title>The Bugzilla FAQ</title> - - <para> - This FAQ includes questions not covered elsewhere in the Guide. - </para> - - <qandaset> - - - <qandadiv id="faq-general"> - <title>General Questions</title> - - <qandaentry> - <question id="faq-general-tryout"> - <para> - Can I try out Bugzilla somewhere? - </para> - </question> - <answer> - <para> - If you want to take a test ride, there are test installations - at <ulink url="http://landfill.bugzilla.org/"/>, - ready to play with directly from your browser. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-license"> - <para> - What license is Bugzilla distributed under? - </para> - </question> - <answer> - <para> - Bugzilla is covered by the Mozilla Public License. - See details at <ulink url="http://www.mozilla.org/MPL/"/>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-support"> - <para> - How do I get commercial support for Bugzilla? - </para> - </question> - <answer> - <para> - <ulink url="http://www.bugzilla.org/support/consulting.html"/> - is a list of companies and individuals who have asked us to - list them as consultants for Bugzilla. - </para> - <para> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-companies"> - <para> - What major companies or projects are currently using Bugzilla - for bug-tracking? - </para> - </question> - <answer> - <para> - There are <emphasis>dozens</emphasis> of major companies with public - Bugzilla sites to track bugs in their products. We have a fairly - complete list available on our website at - <ulink url="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 <email>gerv@mozilla.org</email>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-maintainers"> - <para> - Who maintains Bugzilla? - </para> - </question> - <answer> - <para> - A <ulink url="http://www.bugzilla.org/developers/profiles.html">core - team</ulink>, led by Dave Miller (justdave@bugzilla.org). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-compare"> - <para> - How does Bugzilla stack up against other bug-tracking databases? - </para> - </question> - <answer> - <para> - 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. In the experience of Matthew Barnson (the original - author of this FAQ), though, 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, - greater flexibility, and superior ease-of-use when compared - to commercial bug-tracking software. - </para> - <para> - If you happen to be a vendor for commercial bug-tracking - software, and would like to submit a list of advantages your - product has over Bugzilla, simply send it to - <email>documentation@bugzilla.org</email> and we'd be happy to - include the comparison in our documentation. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-bzmissing"> - <para> - Why doesn't Bugzilla offer this or that feature or compatibility - with this other tracking software? - </para> - </question> - <answer> - <para> - It may be that the support has not been built yet, or that you - have not yet found it. While Bugzilla makes strides in usability, - customizability, scalability, and user interface with each release, - that doesn't mean it can't still use improvement! - </para> - <para> - The best way to make an enhancement request is to <ulink - url="https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">file - a bug at bugzilla.mozilla.org</ulink> and set the Severity - to 'enhancement'. Your 'request for enhancement' (RFE) will - start out in the UNCONFIRMED state, and will stay there until - someone with the ability to CONFIRM the bug reviews it. - If that person feels it to be a good request that fits in with - Bugzilla's overall direction, the status will be changed to - NEW; if not, they will probably explain why and set the bug - to RESOLVED/WONTFIX. If someone else has made the same (or - almost the same) request before, your request will be marked - RESOLVED/DUPLICATE, and a pointer to the previous RFE will be - added. - </para> - <para> - Even if your RFE gets approved, that doesn't mean it's going - to make it right into the next release; there are a limited - number of developers, and a whole lot of RFEs... some of - which are <emphasis>quite</emphasis> complex. If you're a - code-hacking sort of person, you can help the project along - by making a patch yourself that supports the functionality - you require. If you have never contributed anything to - Bugzilla before, please be sure to read the - <ulink url="http://www.bugzilla.org/docs/developer.html">Developers' Guide</ulink> - and - <ulink url="http://www.bugzilla.org/docs/contributor.html">Contributors' Guide</ulink> - before going ahead. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-db"> - <para> - What databases does Bugzilla run on? - </para> - </question> - <answer> - <para> - MySQL is the default database for Bugzilla. It was originally chosen - because it is free, easy to install, and was available for the hardware - Netscape intended to run it on. - </para> - <para> - As of Bugzilla 2.22, complete support for PostgreSQL - is included. With this release using PostgreSQL with Bugzilla - should be as stable as using MySQL. If you experience any problems - with PostgreSQL compatibility, they will be taken as - seriously as if you were running MySQL. - </para> - <para> - There are plans to include an Oracle driver for Bugzilla 3.1.2. - Track progress at - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=189947"> - Bug 189947</ulink>. - </para> - <para> - Sybase support was worked on for a time. However, several - complicating factors have prevented Sybase support from - being realized. There are currently no plans to revive it. - </para> - <para> - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=237862"> - Bug 237862</ulink> is a good bug to read through if you'd - like to see what progress is being made on general database - compatibility. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-perlpath"> - <para> - My perl is located at <filename>/usr/local/bin/perl</filename> - and not <filename>/usr/bin/perl</filename>. Is there an easy - to change that in all the files that have this hard-coded? - </para> - </question> - <answer> - <para> - The easiest way to get around this is to create a link from - one to the other: - <command>ln -s /usr/local/bin/perl /usr/bin/perl</command>. - If that's not an option for you, the following bit of perl - magic will change all the shebang lines (that is to say, - the line at the top of each file that starts with '#!' - and contains the path) to something else: - </para> - <programlisting> -perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl - </programlisting> - <para> - Sadly, this command-line won't work on Windows unless you - also have Cygwin. However, MySQL comes with a binary called - <command>replace</command> which can do the job: - </para> - <programlisting> -C:\mysql\bin\replace "#!/usr/bin/perl" "#!C:\perl\bin\perl" -- *.cgi *.pl - </programlisting> - <note> - <para> - If your perl path is something else again, just follow the - above examples and replace - <filename>/usr/local/bin/perl</filename> with your own perl path. - </para> - </note> - <para> - Once you've modified all your files, you'll also need to modify the - <filename>t/002goodperl.t</filename> test, as it tests that all - shebang lines are equal to <filename>/usr/bin/perl</filename>. - (For more information on the test suite, please check out the - appropriate section in the <ulink - url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers' - Guide</ulink>.) Having done this, run the test itself: - <programlisting> - perl runtests.pl 2 --verbose - </programlisting> - to ensure that you've modified all the relevant files. - </para> - <para> - If using Apache on Windows, you can avoid the whole problem - by setting the <ulink - url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource"> - ScriptInterpreterSource</ulink> directive to 'Registry'. - (If using Apache 2 or higher, set it to 'Registry-Strict'.) - ScriptInterperterSource requires a registry entry - <quote>HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command</quote> to - associate .cgi files with your perl executable. If one does - not already exist, create it with a default value of - <quote><full path to perl> -T</quote>, e.g. - <quote>C:\Perl\bin\perl.exe -T</quote>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-cookie"> - <para> - Is there an easy way to change the Bugzilla cookie name? - </para> - </question> - <answer> - <para> - At present, no. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-selinux"> - <para> - How can Bugzilla be made to work under SELinux? - </para> - </question> - <answer> - <para> - As a web application, Bugzilla simply requires its root - directory to have the httpd context applied for it to work - properly under SELinux. This should happen automatically - on distributions that use SELinux and that package Bugzilla - (if it is installed with the native package management tools). - Information on how to view and change SELinux file contexts - can be found at the - <ulink url="http://docs.fedoraproject.org/selinux-faq-fc5/"> - SELinux FAQ</ulink>. - - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-phb"> - <title>Managerial Questions</title> - - <qandaentry> - <question id="faq-phb-client"> - <para> - Is Bugzilla web-based, or do you have to have specific software or - a specific operating system on your machine? - </para> - </question> - <answer> - <para> - It is web and e-mail based. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-priorities"> - <para> - 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? - </para> - </question> - <answer> - <para> - Yes. However, modifying some fields, notably those related to bug - progression states, also require adjusting the program logic to - compensate for the change. - </para> - <para> - As of Bugzilla 3.0 custom fields can be created via the - "Custom Fields" admin page. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-reporting"> - <para> - Does Bugzilla provide any reporting features, metrics, graphs, - etc? You know, the type of stuff that management likes to see. :) - </para> - </question> - <answer> - <para> - Yes. Look at <ulink url="https://bugzilla.mozilla.org/report.cgi"/> - for samples of what Bugzilla can do in reporting and graphing. - Fuller documentation is provided in <xref linkend="reporting"/>. - </para> - <para> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-email"> - <para> - Is there email notification? If so, what do you see - when you get an email? - </para> - </question> - <answer> - <para> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-emailapp"> - <para> - Do users have to have any particular type of email application? - </para> - </question> - <answer> - <para> - Bugzilla email is sent in plain text, the most compatible - mail format on the planet. - <note> - <para> - 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 <quote>respond to messages in the format in - which they were sent</quote>. 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. - </para> - </note> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-data"> - <para> - 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 <quote>matching</quote> - fields? If I wanted to take the results of a query and export - that data to MS Excel, could I do that? - </para> - </question> - <answer> - <para> - 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. - </para> - <para> - To use the RDF format of the buglist it is necessary to append a - <computeroutput>&ctype=rdf</computeroutput> to the URL. RDF - is meant to be machine readable and thus it is assumed that the - URL would be generated programmatically so there is no user visible - link to this format. - </para> - <para> - Currently the only script included with Bugzilla that can import - data is <filename>importxml.pl</filename> which is intended to be - used for importing the data generated by the XML ctype of - <filename>show_bug.cgi</filename> in association with bug moving. - Any other use is left as an exercise for the user. - </para> - <para> - There are also scripts included in the <filename>contrib/</filename> - directory for using e-mail to import information into Bugzilla, - but these scripts are not currently supported and included for - educational purposes. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-l10n"> - <para> - Has anyone converted Bugzilla to another language to be - used in other countries? Is it localizable? - </para> - </question> - <answer> - <para> - Yes. For more information including available translated templates, - see <ulink - url="http://www.bugzilla.org/download.html#localizations"/>. - Some admin interfaces have been templatized (for easy localization) - but many of them are still available in English only. Also, there - may be issues with the charset not being declared. See <ulink - url="https://bugzilla.mozilla.org/show_bug.cgi?id=126266">bug 126226</ulink> - for more information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-reports"> - <para> - Can a user create and save reports? - Can they do this in Word format? Excel format? - </para> - </question> - <answer> - <para> - Yes. No. Yes (using the CSV format). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-backup"> - <para> - Are there any backup features provided? - </para> - </question> - <answer> - <para> - You should use the backup options supplied by your database platform. - Vendor documentation for backing up a MySQL database can be found at - <ulink url="http://www.mysql.com/doc/B/a/Backup.html"/>. - PostgreSQL backup documentation can be found at - <ulink url="http://www.postgresql.org/docs/8.0/static/backup.html"/>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-maintenance"> - <para> - 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 what types of individuals - would we need to hire and how much would that cost if we were to - go with Bugzilla vs. buying an <quote>out-of-the-box</quote> - solution. - </para> - </question> - <answer> - <para> - If Bugzilla is set up correctly from the start, continuing - maintenance needs are minimal and can be done easily using - the web interface. - </para> - <para> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-installtime"> - <para> - 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 days 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? - </para> - </question> - <answer> - <para> - 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 to who has reasonable Perl skills, and a familiarity - with the operating system on which Bugzilla will be running, - and have them handle your process management, bug-tracking - maintenance, and local customization. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-cost"> - <para> - Is there any licensing fee or other fees for using Bugzilla? Any - out-of-pocket cost other than the bodies needed as identified above? - </para> - </question> - <answer> - <para> - No. Bugzilla, Perl, the Template Toolkit, and all other support - software needed to make Bugzilla work can be downloaded for free. - MySQL and PostgreSQL -- the databases supported by Bugzilla -- - are also open-source. MySQL asks that if you find their product - valuable, you purchase a support contract from them that suits your needs. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-renameBugs"> - <para> - We don't like referring to problems as 'bugs'. Can we change that? - </para> - </question> - <answer> - <para> - Yes! As of Bugzilla 2.18, it is a simple matter to change the - word 'bug' into whatever word/phrase is used by your organization. - See the documentation on Customization for more details, - specifically <xref linkend="template-specific"/>. - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-admin"> - <title>Administrative Questions</title> - - <qandaentry> - <question id="faq-admin-midair"> - <para> - 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? - </para> - </question> - <answer> - <para> - Bugzilla does not lock records. It provides mid-air collision - detection -- which means that it warns a user when a commit is - about to conflict with commits recently made by another user, - and offers the second user a choice of options to deal with - the conflict. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-admin-livebackup"> - <para> - Can users be on the system while a backup is in progress? - </para> - </question> - <answer> - <para> - Refer to your database platform documentation for details on how to do hot - backups. - Vendor documentation for backing up a MySQL database can be found at - <ulink url="http://www.mysql.com/doc/B/a/Backup.html"/>. - PostgreSQL backup documentation can be found at - <ulink url="http://www.postgresql.org/docs/8.0/static/backup.html"/>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-admin-cvsupdate"> - <para> - How can I update the code and the database using CVS? - </para> - </question> - <answer> - <para> - <orderedlist> - <listitem> - <para> - Make a backup of both your Bugzilla directory and the - database. For the Bugzilla directory this is as easy as - doing <command>cp -rp bugzilla bugzilla.bak</command>. - For the database, there's a number of options - see the - MySQL docs and pick the one that fits you best (the easiest - is to just make a physical copy of the database on the disk, - but you have to have the database server shut down to do - that without risking dataloss). - </para> - </listitem> - - <listitem> - <para> - Make the Bugzilla directory your current directory. - </para> - </listitem> - - <listitem> - <para> - Use <command>cvs -q update -AdP</command> if you want to - update to the tip or - <command>cvs -q update -dP -rTAGNAME</command> - if you want a specific version (in that case you'll have to - replace TAGNAME with a CVS tag name such as BUGZILLA-2_16_5). - </para> - - <para> - If you've made no local changes, this should be very clean. - If you have made local changes, then watch the cvs output - for C results. If you get any lines that start with a C - it means there were conflicts between your local changes - and what's in CVS. You'll need to fix those manually before - continuing. - </para> - </listitem> - - <listitem> - <para> - After resolving any conflicts that the cvs update operation - generated, running <command>./checksetup.pl</command> will - take care of updating the database for you as well as any - other changes required for the new version to operate. - </para> - - <warning> - <para> - Once you run checksetup.pl, the only way to go back is - to restore the database backups. You can't - <quote>downgrade</quote> the system cleanly under most - circumstances. - </para> - </warning> - </listitem> - </orderedlist> - </para> - <para> - See also the instructions in <xref linkend="upgrade-cvs"/>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-admin-enable-unconfirmed"> - <para> - How do I make it so that bugs can have an UNCONFIRMED status? - </para> - </question> - <answer> - <para> - To use the UNCONFIRMED status, you must have the 'usevotes' - parameter set to <quote>On</quote>. You must then visit the - <filename>editproducts.cgi</filename> page and set the <quote> - Number of votes a bug in this product needs to automatically - get out of the UNCONFIRMED state</quote> to be a non-zero number. - (You will have to do this for each product that wants to use - the UNCONFIRMED state.) If you do not actually want users to be - able to vote for bugs entered against this product, leave the - <quote>Maximum votes per person</quote> value at '0'. - </para> - <para> - There is work being done to decouple the UNCONFIRMED state from - the 'usevotes' parameter for future versions of Bugzilla. - Follow the discussion and progress at <ulink - url="https://bugzilla.mozilla.org/show_bug.cgi?id=162060">bug - 162060</ulink>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-admin-moving"> - <para> - How do I move a Bugzilla installation from one machine to another? - </para> - </question> - - <answer> - <para> - Reference your database vendor's documentation for information on - backing up and restoring your Bugzilla database on to a different server. - Vendor documentation for backing up a MySQL database can be found at - <ulink url="http://dev.mysql.com/doc/mysql/en/mysqldump.html"/>. - PostgreSQL backup documentation can be found at - <ulink url="http://www.postgresql.org/docs/8.0/static/backup.html"/>. - </para> - - <para> - On your new machine, follow the instructions found in <xref - linkend="installing-bugzilla"/> as far as setting up the physical - environment of the new machine with perl, webserver, modules, etc. - Having done that, you can either: copy your entire Bugzilla - directory from the old machine to a new one (if you want to keep - your existing code and modifications), or download a newer version - (if you are planning to upgrade at the same time). Even if you are - upgrading to clean code, you will still want to bring over the - <filename>localconfig</filename> file, and the - <filename class="directory">data</filename> directory from the - old machine, as they contain configuration information that you - probably won't want to re-create. - </para> - - <note> - <para> - If the hostname or port number of your database server changed - as part of the move, you'll need to update the appropriate - variables in localconfig before taking the next step. - </para> - </note> - - <para> - Once you have your code in place, and your database has - been restored from the backup you made in step 1, run - <command>checksetup.pl</command>. This will upgrade your - database (if necessary), rebuild your templates, etc. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-admin-makeadmin"> - <para> - How do I make a new Bugzilla administrator? - The previous administrator is gone... - </para> - </question> - <answer> - <para> - Run <command>checksetup.pl</command> with - <option>--make-admin</option> option. - Its usage is <option>--make-admin=user@example.org</option>. - The user account must be exist in the Bugzilla database. - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-security"> - <title>Bugzilla Security</title> - <qandaentry> - <question id="faq-security-mysql"> - <para> - 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...) - </para> - </question> - - <answer> - <para> - You can run MySQL like this: <command>mysqld --skip-grant-tables</command>. - However, doing so disables all MySQL security. This is a bad idea. - Please consult <xref linkend="security-mysql"/> of this guide - and the MySQL documentation for better solutions. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-security-knownproblems"> - <para> - Are there any security problems with Bugzilla? - </para> - </question> - <answer> - <para> - 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. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-email"> - <title>Bugzilla Email</title> - - <qandaentry> - <question id="faq-email-nomail"> - <para> - I have a user who doesn't want to receive any more email - from Bugzilla. How do I stop it entirely for this user? - </para> - </question> - <answer> - <para> - The user can stop Bugzilla from sending any mail by unchecking - all boxes on the 'Edit prefs' -> 'Email settings' page. - (As of 2.18,this is made easier by the addition of a 'Disable - All Mail' button.) Alternately, you can add their email address - to the <filename>data/nomail</filename> file (one email address - per line). This will override their personal preferences, and - they will never be sent mail again. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-testing"> - <para> - I'm evaluating/testing Bugzilla, and don't want it to send email - to anyone but me. How do I do it? - </para> - </question> - <answer> - <para> - To disable email, set the - <option>mail_delivery_method</option> parameter to - <literal>none</literal> (2.20 and later), or - <programlisting>$enableSendMail</programlisting> parameter to '0' - in either <filename>BugMail.pm</filename> (2.18 and later) or - <filename>processmail</filename> (up to 2.16.x). - </para> - <note> - <para> - Up to 2.16.x, changing - <programlisting>$enableSendMail</programlisting> - will only affect bugmail; email related to password changes, - email address changes, bug imports, flag changes, etc. will - still be sent out. As of the final release of 2.18, however, - the above step will disable <emphasis>all</emphasis> mail - sent from Bugzilla for any purpose. - </para> - </note> - <para> - To have bugmail (and only bugmail) redirected to you instead of - its intended recipients, leave - <programlisting>$enableSendMail</programlisting> alone; - instead, edit the <quote>newchangedmail</quote> parameter - as follows: - </para> - <itemizedlist> - <listitem> - <para> - Replace <quote>To:</quote> with <quote>X-Real-To:</quote> - </para> - </listitem> - <listitem> - <para> - Replace <quote>Cc:</quote> with <quote>X-Real-CC:</quote> - </para> - </listitem> - <listitem> - <para> - Add a <quote>To: %lt;your_email_address></quote> - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-whine"> - <para> - I want whineatnews.pl to whine at something other than new and - reopened bugs. How do I do it? - </para> - </question> - <answer> - <para> - For older versions of Bugzilla, you may be able to apply - Klaas Freitag's patch for <quote>whineatassigned</quote>, - which can be found in - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=6679">bug - 6679</ulink>. Note that this patch was made in 2000, so it may take - some work to apply cleanly to any releases of Bugzilla newer than - that, but you can use it as a starting point. - </para> - - <para> - An updated (and much-expanded) version of this functionality is - due to be released as part of Bugzilla 2.20; see - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=185090">bug - 185090</ulink> for the discussion, and for more up-to-date patches - if you just can't wait. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-in"> - <para> - How do I set up the email interface to submit or change bugs via email? - </para> - </question> - <answer> - <para> - Bugzilla 3.0 and later offers the ability submit or change - bugs via email, using the <filename>email_in.pl</filename> - script within the root directory of the Bugzilla installation. - More information on the script can be found in - <ulink url="api/email_in.html">docs/html/api/email_in.html</ulink>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-sendmailnow"> - <para> - Email takes FOREVER to reach me from Bugzilla -- it's - extremely slow. What gives? - </para> - </question> - <answer> - <para> - If you are using <application>sendmail</application>, try - enabling <option>sendmailnow</option> in - <filename>editparams.cgi</filename>. For earlier versions of - <application>sendmail</application>, one could achieve - significant performance improvement in the UI (at the cost of - delaying the sending of mail) by setting this parameter to - <literal>off</literal>. Sites with - <application>sendmail</application> version 8.12 (or higher) - should leave this <literal>on</literal>, as they will not see - any performance benefit. - </para> - <para> - If you are using an alternate - <glossterm linkend="gloss-mta">MTA</glossterm>, make sure the - options given in <filename>Bugzilla/BugMail.pm</filename> - and any other place where <application>sendmail</application> - is called are correct for your MTA. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-nonreceived"> - <para> - How come email from Bugzilla changes never reaches me? - </para> - </question> - <answer> - <para> - Double-check that you have not turned off email in your user - preferences. Confirm that Bugzilla is able to send email by - visiting the <quote>Log In</quote> link of your Bugzilla - installation and clicking the <quote>Submit Request</quote> - button after entering your email address. - </para> - <para> - 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". - </para> - <para> - If you are using an MTA other than - <application>sendmail</application> the - <option>sendmailnow</option> param must be set to - <literal>on</literal> or no mail will be sent. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-db"> - <title>Bugzilla Database</title> - - <qandaentry> - <question id="faq-db-corrupted"> - <para> - I think my database might be corrupted, or contain - invalid entries. What do I do? - </para> - </question> - <answer> - <para> - Run the <quote>sanity check</quote> utility - (<filename>sanitycheck.cgi</filename>) from your web browser - to see! If it finishes without errors, you're - <emphasis>probably</emphasis> 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-manualedit"> - <para> - I want to manually edit some entries in my database. How? - </para> - </question> - <answer> - <para> - 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. If you understand SQL, though, you can use the - <command>mysql</command> or <command>psql</command> command line - utilities to manually insert, delete and modify table information. - There are also more intuitive GUI clients available for both MySQL - and PostgreSQL. For MySQL, we recommend - <ulink url="http://www.phpmyadmin.net/">phpMyAdmin</ulink>. - </para> - - <para> - Remember, backups are your friend. Everyone makes mistakes, and - it's nice to have a safety net in case you mess something up. - </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-permissions"> - <para> - I think I've set up MySQL permissions correctly, but Bugzilla still - can't connect. - </para> - </question> - <answer> - <para> - Try running MySQL from its binary: - <command>mysqld --skip-grant-tables</command>. - 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 - <filename>localconfig</filename>. - </para> - <warning> - <para> - 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. Please do not run your production - database in this mode. - </para> - </warning> - <para> - You may also be suffering from a client version mismatch: - </para> - <para> - MySQL 4.1 and up uses an authentication protocol based on - a password hashing algorithm that is incompatible with that - used by older clients. If you upgrade the server to 4.1, - attempts to connect to it with an older client may fail - with the following message: - </para> - <para> - <screen><prompt>shell></prompt> mysql - Client does not support authentication protocol requested - by server; consider upgrading MySQL client - </screen> - </para> - <para> - To solve this problem, you should use one of the following - approaches: - </para> - <para> - <itemizedlist> - <listitem> - <para> - Upgrade all client programs to use a 4.1.1 or newer - client library. - </para> - </listitem> - <listitem> - <para> - When connecting to the server with a pre-4.1 client - program, use an account that still has a - pre-4.1-style password. - </para> - </listitem> - <listitem> - <para> - Reset the password to pre-4.1 style for each user - that needs to use a pre-4.1 client program. - This can be done using the SET PASSWORD statement - and the OLD_PASSWORD() function: - <screen> - <prompt>mysql></prompt> SET PASSWORD FOR - <prompt> -></prompt> ' some_user '@' some_host ' = OLD_PASSWORD(' newpwd '); - </screen> - </para> - </listitem> - </itemizedlist> - - </para> - - - <para> - </para> - - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-synchronize"> - <para> - How do I synchronize bug information among multiple - different Bugzilla databases? - </para> - </question> - <answer> - <para> - 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. - </para> - <para> - MySQL has some synchronization features built-in 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. - </para> - <para> - If you simply need to transfer bugs from one Bugzilla to another, - checkout the <quote>move.pl</quote> script in the Bugzilla - distribution. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-nt"> - <title>Can Bugzilla run on a Windows server?</title> - - <qandaentry> - <question id="faq-nt-easiest"> - <para> - What is the easiest way to run Bugzilla on Win32 (Win98+/NT/2K)? - </para> - </question> - <answer> - <para> - Making Bugzilla work easily with Windows - was one of the major goals of the 2.18 milestone. If the - necessary components are in place (perl, a webserver, an MTA, etc.) - then installation of Bugzilla on a Windows box should be no more - difficult than on any other platform. As with any installation, - we recommend that you carefully and completely follow the - installation instructions in <xref linkend="os-win32"/>. - </para> - <para> - While doing so, don't forget to check out the very excellent guide - to <ulink url="http://www.bugzilla.org/docs/win32install.html"> - Installing Bugzilla on Microsoft Windows</ulink> written by - Byron Jones. Thanks, Byron! - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-bundle"> - <para> - Is there a "Bundle::Bugzilla" equivalent for Win32? - </para> - </question> - <answer> - <para> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-mappings"> - <para> - CGI's are failing with a <quote>something.cgi is not a valid - Windows NT application</quote> error. Why? - </para> - </question> - <answer> - <para> - 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 <path>\perl.exe %s %s as the executable. - </para> - <para> - Microsoft has some advice on this matter, as well: - <blockquote> - <para> - <quote>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: - <command>c:\perl\bin\perl.exe %s %s</command></quote> - </para> - </blockquote> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-dbi"> - <para> - I'm having trouble with the perl modules for NT not being - able to talk to the database. - </para> - </question> - <answer> - <para> - Your modules may be outdated or inaccurate. Try: - <orderedlist> - <listitem> - <para> - Hitting <ulink url="http://www.activestate.com/ActivePerl"/> - </para> - </listitem> - <listitem> - <para> - Download ActivePerl - </para> - </listitem> - <listitem> - <para> - Go to your prompt - </para> - </listitem> - <listitem> - <para> - Type 'ppm' - </para> - </listitem> - <listitem> - <para> - <prompt>PPM></prompt> <command>install DBI DBD-mysql GD</command> - </para> - </listitem> - </orderedlist> - I reckon TimeDate comes with the activeperl. - You can check the ActiveState site for packages for installation - through PPM. <ulink url="http://www.activestate.com/Packages/"/>. - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-use"> - <title>Bugzilla Usage</title> - - <qandaentry> - <question id="faq-use-changeaddress"> - <para> - How do I change my user name (email address) in Bugzilla? - </para> - </question> - <answer> - <para> - You can change your email address from the Name and Password - section in Preferences. You will be emailed at both the old - and new addresses for confirmation. 'Administrative Policies' - must have the 'allowemailchange' parameter set to <quote>On</quote>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-query"> - <para> - The query page is very confusing. - Isn't there a simpler way to query? - </para> - </question> - <answer> - <para> - 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. - </para> - <para> - As of 2.18, there is also a 'simpler' search available. At the top - of the search page are two links; <quote>Advanced Search</quote> - will take you to the familiar full-power/full-complexity search - page. The <quote>Find a Specific Bug</quote> link will take you - to a much-simplified page where you can pick a product and - status (open,closed, or both), then enter words that appear in - the bug you want to find. This search will scour the 'Summary' - and 'Comment' fields, and return a list of bugs sorted so that - the bugs with the most hits/matches are nearer to the top. - </para> - <note> - <para> - Matches in the Summary will 'trump' matches in comments, - and bugs with summary-matches will be placed higher in - the buglist -- even if a lower-ranked bug has more matches - in the comments section. - </para> - </note> - <para> - Bugzilla uses a cookie to remember which version of the page - you visited last, and brings that page up when you next do a - search. The default page for new users (or after an upgrade) - is the 'simple' search. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-accept"> - <para> - I'm confused by the behavior of the <quote>Accept</quote> - button in the Show Bug form. Why doesn't it assign the bug - to me when I accept it? - </para> - </question> - <answer> - <para> - The current behavior is acceptable to bugzilla.mozilla.org and - most users. If you want to change this behavior, though, you - have your choice of patches: - <simplelist> - <member> - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=35195">Bug 35195</ulink> - seeks to add an <quote>...and accept the bug</quote> checkbox - to the UI. It has two patches attached to it: - <ulink url="https://bugzilla.mozilla.org/showattachment.cgi?attach_id=8029">attachment 8029</ulink> - was originally created for Bugzilla 2.12, while - <ulink url="https://bugzilla.mozilla.org/showattachment.cgi?attach_id=91372">attachment 91372</ulink> - is an updated version for Bugzilla 2.16 - </member> - <member> - <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=37613">Bug - 37613</ulink> also provides two patches (against Bugzilla - 2.12): one to add a 'Take Bug' option, and the other to - automatically reassign the bug on 'Accept'. - </member> - </simplelist> - These patches are all somewhat dated now, and cannot be applied - directly, but they are simple enough to provide a guide on how - Bugzilla can be customized and updated to suit your needs. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-attachment"> - <para> - I can't upload anything into the database via the - <quote>Create Attachment</quote> link. What am I doing wrong? - </para> - </question> - <answer> - <para> - The most likely cause is a very old browser or a browser that is - incompatible with file upload via POST. Download the latest version - of your favourite browser to handle uploads correctly. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-keyword"> - <para> - How do I change a keyword in Bugzilla, once some bugs are using it? - </para> - </question> - <answer> - <para> - 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 - <command>sanitycheck.cgi</command> to fix it. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-close"> - <para> - Why can't I close bugs from the <quote>Change Several Bugs - at Once</quote> page? - </para> - </question> - <answer> - <para> - Simple answer; you can. - </para> - - <para> - The logic behind the page checks every bug in the list to - determine legal state changes, and then only shows you controls - to do things that could apply to <emphasis>every</emphasis> bug - on the list. The reason for this is that if you try to do something - illegal to a bug, the whole process will grind to a halt, and all - changes after the failed one will <emphasis>also</emphasis> fail. - Since that isn't a good outcome, the page doesn't even present - you with the option. - </para> - - <para> - In practical terms, that means that in order to mark - multiple bugs as CLOSED, then every bug on the page has to be - either RESOLVED or VERIFIED already; if this is not the case, - then the option to close the bugs will not appear on the page. - </para> - - <para> - The rationale 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. - </para> - </answer> - </qandaentry> - - - </qandadiv> - - <qandadiv id="faq-hacking"> - <title>Bugzilla Hacking</title> - - <qandaentry> - <question id="faq-hacking-templatestyle"> - <para> - What kind of style should I use for templatization? - </para> - </question> - <answer> - <para> - Gerv and Myk suggest a 2-space indent, with embedded code sections on - their own line, in line with outer tags. Like this:</para> - <programlisting><![CDATA[ -<fred> -[% IF foo %] - <bar> - [% FOREACH x = barney %] - <tr> - <td> - [% x %] - </td> - <tr> - [% END %] -[% END %] -</fred> -]]></programlisting> - - <para> Myk also recommends you turn on PRE_CHOMP in the template - initialization to prevent bloating of HTML with unnecessary whitespace. - </para> - - <para>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.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-bugzillabugs"> - <para> - What bugs are in Bugzilla right now? - </para> - </question> - <answer> - <para> - Try <ulink url="https://bugzilla.mozilla.org/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=Bugzilla"> - this link</ulink> to view current bugs or requests for - enhancement for Bugzilla. - </para> - <para> - You can view bugs marked for &bz-nextver; release - <ulink url="https://bugzilla.mozilla.org/buglist.cgi?product=Bugzilla&target_milestone=Bugzilla+&bz-nextver;">here</ulink>. - This list includes bugs for the &bz-nextver; release that have already - been fixed and checked into CVS. Please consult the - <ulink url="http://www.bugzilla.org/"> - Bugzilla Project Page</ulink> for details on how to - check current sources out of CVS so you can have these - bug fixes early! - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-priority"> - <para> - How can I change the default priority to a null value? - For instance, have the default priority be <quote>---</quote> - instead of <quote>P2</quote>? - </para> - </question> - <answer> - <para> - This is well-documented in <ulink - url="https://bugzilla.mozilla.org/show_bug.cgi?id=49862">bug - 49862</ulink>. Ultimately, it's as easy as adding the - <quote>---</quote> priority field to your localconfig file - in the appropriate area, re-running checksetup.pl, and then - changing the default priority in your browser using - <command>editparams.cgi</command>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-patches"> - <para> - What's the best way to submit patches? What guidelines - should I follow? - </para> - </question> - <answer> - <blockquote> - <orderedlist> - <listitem> - <para> - Enter a bug into bugzilla.mozilla.org for the <quote><ulink - url="https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">Bugzilla</ulink></quote> - product. - </para> - </listitem> - <listitem> - <para> - Upload your patch as a unified diff (having used <quote>diff - -u</quote> against the <emphasis>current sources</emphasis> - checked out of CVS), or new source file by clicking - <quote>Create a new attachment</quote> 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 <quote>Patch</quote> checkbox - to indicate the text you are sending is a patch! - </para> - </listitem> - <listitem> - <para> - Announce your patch and the associated URL - (https://bugzilla.mozilla.org/show_bug.cgi?id=XXXXXX) - for discussion in the newsgroup - (mozilla.support.bugzilla). 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. - </para> - </listitem> - <listitem> - <para> - 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. - </para> - </listitem> - <listitem> - <para> - Bask in the glory of the fact that you helped write - the most successful open-source bug-tracking software - on the planet :) - </para> - </listitem> - </orderedlist> - </blockquote> - </answer> - </qandaentry> - - - </qandadiv> - - </qandaset> - -</appendix> - - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/xml/filetemp.patch b/docs/xml/filetemp.patch deleted file mode 100644 index 9fb70adce..000000000 --- a/docs/xml/filetemp.patch +++ /dev/null @@ -1,18 +0,0 @@ ---- 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; - }; diff --git a/docs/xml/gfdl.xml b/docs/xml/gfdl.xml deleted file mode 100644 index 1d84d1255..000000000 --- a/docs/xml/gfdl.xml +++ /dev/null @@ -1,445 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="gfdl"> - <title>GNU Free Documentation License</title> - -<!-- - GNU Project - Free Software Foundation (FSF) --> -<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" --> -<!-- section> - <title>GNU Free Documentation License</title --> - <para>Version 1.1, March 2000</para> - - <blockquote> - <para>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.</para> - </blockquote> - - <section label="0" id="gfdl-0"> - <title>Preamble</title> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="1" id="gfdl-1"> - <title>Applicability and Definition</title> - - <para>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".</para> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - - <para>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".</para> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="2" id="gfdl-2"> - <title>Verbatim Copying</title> - - <para>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.</para> - - <para>You may also lend copies, under the same conditions stated above, - and you may publicly display copies.</para> - </section> - - <section label="3" id="gfdl-3"> - <title>Copying in Quantity</title> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="4" id="gfdl-4"> - <title>Modifications</title> - - <para>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:</para> - - <orderedlist numeration="upperalpha"> - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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).</para> - </listitem> - - <listitem> - <para>State on the Title page the name of the publisher of the - Modified Version, as the publisher.</para> - </listitem> - - <listitem> - <para>Preserve all the copyright notices of the Document.</para> - </listitem> - - <listitem> - <para>Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice.</para> - </listitem> - - <listitem> - <para>Include an unaltered copy of this License.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>Delete any section entitled "Endorsements". Such a section may - not be included in the Modified Version.</para> - </listitem> - - <listitem> - <para>Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section.</para> - </listitem> - </orderedlist> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="5" id="gfdl-5"> - <title>Combining Documents</title> - - <para>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.</para> - - <para>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.</para> - - <para>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."</para> - </section> - - <section label="6" id="gfdl-6"> - <title>Collections of Documents</title> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="7" id="gfdl-7"> - <title>Aggregation with Independent Works</title> - - <para>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.</para> - - <para>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.</para> - </section> - - <section label="8" id="gfdl-8"> - <title>Translation</title> - - <para>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.</para> - </section> - - <section label="9" id="gfdl-9"> - <title>Termination</title> - - <para>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.</para> - </section> - - <section label="10" id="gfdl-10"> - <title>Future Revisions of this License</title> - - <para>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 - <ulink url="http://www.gnu.org/copyleft/"/>.</para> - - <para>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.</para> - </section> - - <section label="" id="gfdl-howto"> - <title>How to use this License for your documents</title> - - <para>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:</para> - - <blockquote> - <para>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".</para> - </blockquote> - - <para>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.</para> - - <para>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.</para> - </section> -</appendix> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/glossary.xml b/docs/xml/glossary.xml deleted file mode 100644 index 5b6d1a6e7..000000000 --- a/docs/xml/glossary.xml +++ /dev/null @@ -1,551 +0,0 @@ -<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> -<glossary id="glossary"> - <glossdiv> - <title>0-9, high ascii</title> - - <glossentry id="gloss-htaccess"> - <glossterm>.htaccess</glossterm> - - <glossdef> - <para>Apache web server, and other NCSA-compliant web servers, - observe the convention of using files in directories called - <filename>.htaccess</filename> - - to restrict access to certain files. In Bugzilla, they are used - to keep secret files which would otherwise - compromise your installation - e.g. the - <filename>localconfig</filename> - file contains the password to your database. - curious.</para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-a"> - <title>A</title> - - <glossentry id="gloss-apache"> - <glossterm>Apache</glossterm> - - <glossdef> - <para>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 - <quote>a patchy</quote> - version of the original - <acronym>NCSA</acronym> - world-wide-web server.</para> - - <variablelist> - <title>Useful Directives when configuring Bugzilla</title> - - <varlistentry> - <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#addhandler">AddHandler</ulink></computeroutput></term> - <listitem> - <para>Tell Apache that it's OK to run CGI scripts.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#allowoverride">AllowOverride</ulink></computeroutput></term> - <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#options">Options</ulink></computeroutput></term> - <listitem> - <para>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 <filename>.htaccess</filename> - overrides. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/mod_dir.html#directoryindex">DirectoryIndex</ulink></computeroutput></term> - <listitem> - <para>Used to tell Apache what files are indexes. If you can - not add <filename>index.cgi</filename> to the list of valid files, - you'll need to set <computeroutput>$index_html</computeroutput> to - 1 in <filename>localconfig</filename> so - <command>./checksetup.pl</command> will create an - <filename>index.html</filename> that redirects to - <filename>index.cgi</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink></computeroutput></term> - <listitem> - <para>Used when running Apache on windows so the shebang line - doesn't have to be changed in every Bugzilla script. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about how to configure Apache for Bugzilla, - see <xref linkend="http-apache"/>. - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-b"> - <title>B</title> - - <glossentry> - <glossterm>Bug</glossterm> - - <glossdef> - <para>A - <quote>bug</quote> - - in Bugzilla refers to an issue entered into the database which has an - associated number, assignments, comments, etc. Some also refer to a - <quote>tickets</quote> - or - <quote>issues</quote>; - in the context of Bugzilla, they are synonymous.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Bug Number</glossterm> - - <glossdef> - <para>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.</para> - </glossdef> - </glossentry> - - <glossentry id="gloss-bugzilla"> - <glossterm>Bugzilla</glossterm> - - <glossdef> - <para>Bugzilla is the world-leading free software bug tracking system. - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-c"> - <title>C</title> - - <glossentry id="gloss-cgi"> - <glossterm>Common Gateway Interface</glossterm> - <acronym>CGI</acronym> - <glossdef> - <para><acronym>CGI</acronym> 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 <acronym>CGI</acronym> application. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-component"> - <glossterm>Component</glossterm> - - <glossdef> - <para>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).</para> - </glossdef> - </glossentry> - - <glossentry id="gloss-cpan"> - <glossterm>Comprehensive Perl Archive Network</glossterm> - <acronym>CPAN</acronym> - - <!-- TODO: Rewrite def for CPAN --> - <glossdef> - <para> - <acronym>CPAN</acronym> - - stands for the - <quote>Comprehensive Perl Archive Network</quote>. - CPAN maintains a large number of extremely useful - <glossterm>Perl</glossterm> - modules - encapsulated chunks of code for performing a - particular task.</para> - </glossdef> - </glossentry> - - <glossentry id="gloss-contrib"> - <glossterm><filename class="directory">contrib</filename></glossterm> - - <glossdef> - <para>The <filename class="directory">contrib</filename> 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 official distribution. - <note> - <para>Scripts in the <filename class="directory">contrib</filename> - directory are not officially supported by the Bugzilla team and may - break in between versions. - </para> - </note> - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-d"> - <title>D</title> - - <glossentry id="gloss-daemon"> - <glossterm>daemon</glossterm> - - <glossdef> - <para>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. - <glossterm>mysqld</glossterm>, - the MySQL server, and - <glossterm>apache</glossterm>, - a web server, are generally run as daemons.</para> - </glossdef> - </glossentry> - - <glossentry id="gloss-dos"> - <glossterm>DOS Attack</glossterm> - - <glossdef> - <para>A DOS, or Denial of Service attack, is when a user attempts to - deny access to a web server by repeatedly accessing a page or sending - malformed requests to a webserver. A D-DOS, or - Distributed Denial of Service attack, is when these requests come - from multiple sources at the same time. Unfortunately, these are much - more difficult to defend against. - </para> - </glossdef> - </glossentry> - - </glossdiv> - - <glossdiv id="gloss-g"> - <title>G</title> - - <glossentry id="gloss-groups"> - <glossterm>Groups</glossterm> - - <glossdef> - <para>The word - <quote>Groups</quote> - - 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 - <glossterm>Products</glossterm> - in the - <glossterm>Bugzilla</glossterm> - database.</para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-j"> - <title>J</title> - - <glossentry id="gloss-javascript"> - <glossterm>JavaScript</glossterm> - <glossdef> - <para>JavaScript is cool, we should talk about it. - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-m"> - <title>M</title> - - <glossentry id="gloss-mta"> - <glossterm>Message Transport Agent</glossterm> - <acronym>MTA</acronym> - - <glossdef> - <para>A Message Transport Agent is used to control the flow of email on a system. - The <ulink url="http://search.cpan.org/dist/Email-Send/lib/Email/Send.pm">Email::Send</ulink> - Perl module, which Bugzilla uses to send email, can be configured to - use many different underlying implementations for actually sending the - mail using the <option>mail_delivery_method</option> parameter. - Implementations other than <literal>sendmail</literal> require that the - <option>sendmailnow</option> param be set to <literal>on</literal>. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-mysql"> - <glossterm>MySQL</glossterm> - - <glossdef> - <para>MySQL is currently the required - <glossterm linkend="gloss-rdbms">RDBMS</glossterm> for Bugzilla. MySQL - can be downloaded from <ulink url="http://www.mysql.com"/>. While you - should familiarize yourself with all of the documentation, some high - points are: - </para> - <variablelist> - <varlistentry> - <term><ulink url="http://www.mysql.com/doc/en/Backup.html">Backup</ulink></term> - <listitem> - <para>Methods for backing up your Bugzilla database. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><ulink url="http://www.mysql.com/doc/en/Option_files.html">Option Files</ulink></term> - <listitem> - <para>Information about how to configure MySQL using - <filename>my.cnf</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><ulink url="http://www.mysql.com/doc/en/Privilege_system.html">Privilege System</ulink></term> - <listitem> - <para>Much more detailed information about the suggestions in - <xref linkend="security-mysql"/>. - </para> - </listitem> - </varlistentry> - </variablelist> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-p"> - <title>P</title> - - <glossentry id="gloss-ppm"> - <glossterm>Perl Package Manager</glossterm> - <acronym>PPM</acronym> - - <glossdef> - <para><ulink url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/"/> - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm id="gloss-product">Product</glossterm> - - <glossdef> - <para>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.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Perl</glossterm> - - <glossdef> - <para>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. - <glossterm>Bugzilla</glossterm> - - is maintained in Perl.</para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-q"> - <title>Q</title> - - <glossentry> - <glossterm>QA</glossterm> - - <glossdef> - <para> - <quote>QA</quote>, - <quote>Q/A</quote>, and - <quote>Q.A.</quote> - are short for - <quote>Quality Assurance</quote>. - 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 - <quote>QA Contact</quote> - - field in a bug.</para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-r"> - <title>R</title> - - <glossentry id="gloss-rdbms"> - <glossterm>Relational DataBase Management System</glossterm> - <acronym>RDBMS</acronym> - - <glossdef> - <para>A relational database management system is a database system - that stores information in tables that are related to each other. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-regexp"> - <glossterm>Regular Expression</glossterm> - <acronym>regexp</acronym> - - <glossdef> - <para>A regular expression is an expression used for pattern matching. - <ulink url="http://perldoc.com/perl5.6/pod/perlre.html#Regular-Expressions">Documentation</ulink> - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-s"> - <title>S</title> - - <glossentry id="gloss-service"> - <glossterm>Service</glossterm> - - <glossdef> - <para>In Windows NT environment, a boot-time background application - is referred to as a service. These are generally managed through the - control panel while logged in as an account with - <quote>Administrator</quote> level capabilities. For more - information, consult your Windows manual or the MSKB. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm> - <acronym>SGML</acronym> - </glossterm> - - <glossdef> - <para> - <acronym>SGML</acronym> - - stands for - <quote>Standard Generalized Markup Language</quote>. - Created in the 1980's to provide an extensible means to maintain - documentation based upon content instead of presentation, - <acronym>SGML</acronym> - - has withstood the test of time as a robust, powerful language. - <glossterm> - <acronym>XML</acronym> - </glossterm> - - is the - <quote>baby brother</quote> - - of SGML; any valid - <acronym>XML</acronym> - - document it, by definition, a valid - <acronym>SGML</acronym> - - document. The document you are reading is written and maintained in - <acronym>SGML</acronym>, - and is also valid - <acronym>XML</acronym> - - if you modify the Document Type Definition.</para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-t"> - <title>T</title> - - <glossentry id="gloss-target-milestone" xreflabel="Target Milestone"> - <glossterm>Target Milestone</glossterm> - - <glossdef> - <para>Target Milestones are Product goals. They are configurable on a - per-Product basis. Most software development houses have a concept of - - <quote>milestones</quote> - - 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.</para> - </glossdef> - </glossentry> - - <glossentry id="gloss-tcl"> - <glossterm>Tool Command Language</glossterm> - <acronym>TCL</acronym> - <glossdef> - <para>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. - </para> - </glossdef> - </glossentry> - </glossdiv> - - <glossdiv id="gloss-z"> - <title>Z</title> - - <glossentry id="gloss-zarro"> - <glossterm>Zarro Boogs Found</glossterm> - - <glossdef> - <para>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: - </para> - - <blockquote> - <attribution>Terry Weissman</attribution> - <para>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. - </para> - - <para>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... - </para> - </blockquote> - - </glossdef> - </glossentry> - </glossdiv> -</glossary> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/xml/index.xml b/docs/xml/index.xml deleted file mode 100644 index 7fc1a4c14..000000000 --- a/docs/xml/index.xml +++ /dev/null @@ -1,21 +0,0 @@ -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml deleted file mode 100644 index 3815f6753..000000000 --- a/docs/xml/installation.xml +++ /dev/null @@ -1,2040 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: installation.xml,v 1.155 2008/02/24 19:23:06 lpsolit%gmail.com Exp $ --> -<chapter id="installing-bugzilla"> - <title>Installing Bugzilla</title> - - <section id="installation"> - <title>Installation</title> - - <note> - <para>If you just want to <emphasis>use</emphasis> 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 from - your web browser. - </para> - </note> - - <para>The Bugzilla server software is usually installed on Linux or - Solaris. - If you are installing on another OS, check <xref linkend="os-specific"/> - before you start your installation to see if there are any special - instructions. - </para> - - <para> - As an alternative to following these instructions, you may wish to - try Arne Schirmacher's unofficial and unsupported - <ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla - Installer</ulink>, which installs Bugzilla and all its prerequisites - on Linux or Solaris systems. - </para> - - <para>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. - </para> - - <warning> - <para>The installation process may make your machine insecure for - short periods of time. Make sure there is a firewall between you - and the Internet. - </para> - </warning> - - <para> - You are strongly recommended to make a backup of your system - before installing Bugzilla (and at regular intervals thereafter :-). - </para> - - <para>In outline, the installation proceeds as follows: - </para> - - <procedure> - <step> - <para><link linkend="install-perl">Install Perl</link> - (&min-perl-ver; or above) - </para> - </step> - <step> - <para><link linkend="install-database">Install a Database Engine</link> - </para> - </step> - <step> - <para><link linkend="install-webserver">Install a Webserver</link> - </para> - </step> - <step> - <para><link linkend="install-bzfiles">Install Bugzilla</link> - </para> - </step> - <step> - <para><link linkend="install-perlmodules">Install Perl modules</link> - </para> - </step> - <step> - <para> - <link linkend="install-MTA">Install a Mail Transfer Agent</link> - (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) - </para> - </step> - <step> - <para>Configure all of the above. - </para> - </step> - </procedure> - - <section id="install-perl"> - <title>Perl</title> - - <para>Installed Version Test: <filename>perl -v</filename></para> - - <para>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 <ulink url="http://www.perl.com"/>. - Although Bugzilla runs with Perl &min-perl-ver;, - it's a good idea to be using the latest stable version. - </para> - </section> - - <section id="install-database"> - <title>Database Engine</title> - - <para>From Bugzilla 2.20, support is included for using both the MySQL and - PostgreSQL database servers. You only require one of these systems to make - use of Bugzilla.</para> - - <section id="install-mysql"> - <title>MySQL</title> - <para>Installed Version Test: <filename>mysql -V</filename></para> - - <para> - If you don't have it and your OS doesn't provide official packages, - visit <ulink url="http://www.mysql.com"/>. You need MySQL version - &min-mysql-ver; or higher. - </para> - - <note> - <para> Many of the binary - versions of MySQL store their data files in - <filename class="directory">/var</filename>. - 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 <filename>configure</filename>.</para> - </note> - - <para>If you install from something other than a packaging/installation - system, such as .rpm (Redhat Package), .deb (Debian Package), .exe - (Windows Executable), or .msi (Microsoft Installer), make sure the MySQL - server is started when the machine boots. - </para> - </section> - - <section id="install-pg"> - <title>PostgreSQL</title> - <para>Installed Version Test: <filename>psql -V</filename></para> - - <para> - If you don't have it and your OS doesn't provide official packages, - visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL - version &min-pg-ver; or higher. - </para> - - <para>If you install from something other than a packaging/installation - system, such as .rpm (Redhat Package), .deb (Debian Package), .exe - (Windows Executable), or .msi (Microsoft Installer), make sure the - PostgreSQL server is started when the machine boots. - </para> - </section> - - </section> - - <section id="install-webserver"> - <title>Web Server</title> - - <para>Installed Version Test: view the default welcome page at - http://<your-machine>/</para> - - <para>You have freedom of choice here, pretty much any web server that - is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm> - 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 web server, - please share your experiences with us by filing a bug in &bzg-bugs;. - </para> - - <para> - If you don't have Apache and your OS doesn't provide official packages, - visit <ulink url="http://httpd.apache.org/"/>. - </para> - - </section> - - <section id="install-bzfiles"> - <title>Bugzilla</title> - - <para> - Download a Bugzilla tarball (or check it out from CVS) and place - it in a suitable directory, accessible by the default web server user - (probably <quote>apache</quote> or <quote>www</quote>). - Good locations are either directly in the web server's document directories or - in <filename>/usr/local</filename> with a symbolic link to the web server's - document directories or an alias in the web server's configuration. - </para> - - <caution> - <para>The default Bugzilla distribution is NOT designed to be placed - in a <filename class="directory">cgi-bin</filename> directory. This - includes any directory which is configured using the - <option>ScriptAlias</option> directive of Apache. - </para> - </caution> - - <para>Once all the files are in a web accessible directory, make that - directory writable by your web server's user. This is a temporary step - until you run the - <filename>checksetup.pl</filename> - script, which locks down your installation.</para> - </section> - - <section id="install-perlmodules"> - <title>Perl Modules</title> - - <para>Bugzilla's installation process is based - on a script called <filename>checksetup.pl</filename>. - 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, proceed to <xref linkend="configuration"/>. - </para> - - <para> - At this point, you need to <filename>su</filename> to root. You should - remain as root until the end of the install. To check you have the - required modules, run: - </para> - - <screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen> - - <para> - <filename>checksetup.pl</filename> 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. - </para> - - <para> - 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. - </para> - - <para> - The preferred way of installing Perl modules is via CPAN on Unix, - or PPM on Windows (see <xref linkend="win32-perl-modules"/>). These - instructions assume you are using CPAN; if for some reason you need - to install the Perl modules manually, see - <xref linkend="install-perlmodules-manual"/>. - </para> - - <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'</screen> - - <para> - If you using Bundle::Bugzilla, invoke the magic CPAN command on it. - Otherwise, you need to work down the - list of modules that <filename>checksetup.pl</filename> says are - required, in the order given, invoking the command on each. - </para> - - <tip> - <para>Many people complain that Perl modules will not install for - them. Most times, the error messages complain that they are missing a - file in - <quote>@INC</quote>. - 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 - <emphasis>are</emphasis> - the local UNIX sysadmin, please consult the newsgroup/mailing list - for further assistance or hire someone to help you out.</para> - </tip> - - <note> - <para>If you are using a package-based system, and attempting to install the - Perl modules from CPAN, you may need to install the "development" packages for - MySQL and GD before attempting to install the related Perl modules. The names of - these packages will vary depending on the specific distribution you are using, - but are often called <filename><packagename>-devel</filename>.</para> - </note> - - <para> - Here is a complete list of modules and their minimum versions. - Some modules have special installation notes, which follow. - </para> - - <para>Required Perl modules: - <orderedlist> - - <listitem> - <para> - CGI &min-cgi-ver; or CGI &min-mp-cgi-ver; if using mod_perl - </para> - </listitem> - - <listitem> - <para> - Date::Format (&min-date-format-ver;) - </para> - </listitem> - - <listitem> - <para> - DBI (&min-dbi-ver;) - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-dbd-mysql">DBD::mysql</link> - (&min-dbd-mysql-ver;) if using MySQL - </para> - </listitem> - - <listitem> - <para> - DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL - </para> - </listitem> - - <listitem> - <para> - File::Spec (&min-file-spec-ver;) - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-template">Template</link> - (&min-template-ver;) - </para> - </listitem> - - <listitem> - <para> - Email::Send (&min-email-send-ver;) - </para> - </listitem> - - <listitem> - <para> - Email::MIME::Modifier (&min-email-mime-modifier-ver;) - </para> - </listitem> - </orderedlist> - - Optional Perl modules: - <orderedlist> - <listitem> - <para> - <link linkend="install-modules-gd">GD</link> - (&min-gd-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - Template::Plugin::GD::Image - (&min-gd-ver;) for Graphical Reports - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-chart-base">Chart::Base</link> - (&min-chart-base-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-gd-graph">GD::Graph</link> - (&min-gd-graph-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-gd-text">GD::Text</link> - (&min-gd-text-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-xml-twig">XML::Twig</link> - (&min-xml-twig-ver;) for bug import/export - </para> - </listitem> - - <listitem> - <para> - MIME::Parser (&min-mime-parser-ver;) for bug import/export - </para> - </listitem> - - <listitem> - <para> - LWP::UserAgent - (&min-lwp-useragent-ver;) for Automatic Update Notifications - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-patchreader">PatchReader</link> - (&min-patchreader-ver;) for pretty HTML view of patches - </para> - </listitem> - - <listitem> - <para> - Image::Magick (&min-image-magick-ver;) for converting BMP image attachments to PNG - </para> - </listitem> - - <listitem> - <para> - Net::LDAP - (&min-net-ldap-ver;) for LDAP Authentication - </para> - </listitem> - - <listitem> - <para> - Authen::Radius - (&min-authen-radius-ver;) for RADIUS Authentication - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-soap-lite">SOAP::Lite</link> - (&min-soap-lite-ver;) for the web service interface - </para> - </listitem> - - <listitem> - <para> - HTML::Parser - (&min-html-parser-ver;) for More HTML in Product/Group Descriptions - </para> - </listitem> - - <listitem> - <para> - HTML::Scrubber - (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions - </para> - </listitem> - - <listitem> - <para> - Email::MIME::Attachment::Stripper - (&min-email-mime-attachment-stripper-ver;) for Inbound Email - </para> - </listitem> - - <listitem> - <para> - Email::Reply - (&min-email-reply-ver;) for Inbound Email - </para> - </listitem> - - <listitem> - <para> - mod_perl2 - (&min-mod_perl2-ver;) for mod_perl - </para> - </listitem> - - <listitem> - <para> - CGI - (&min-cgi-ver;) for mod_perl - </para> - </listitem> - - </orderedlist> - </para> - - <section id="install-modules-dbd-mysql"> - <title>DBD::mysql</title> - - <para>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.</para> - - <para>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. - </para> - </section> - - <section id="install-modules-template"> - <title>Template Toolkit (&min-template-ver;)</title> - - <para>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. - </para> - </section> - - <section id="install-modules-gd"> - <title>GD (&min-gd-ver;)</title> - - <para>The GD module is only required if you want graphical reports. - </para> - - <note> - <para>The Perl GD module requires some other libraries that may or - may not be installed on your system, including - <classname>libpng</classname> - and - <classname>libgd</classname>. - 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.</para> - </note> - - <tip> - <para>The version of the GD module you need is very closely tied - to the <classname>libgd</classname> version installed on your system. - If you have a version 1.x of <classname>libgd</classname> the 2.x - versions of the GD module won't work for you. - </para> - </tip> - </section> - - <section id="install-modules-chart-base"> - <title>Chart::Base (&min-chart-base-ver;)</title> - - <para>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.</para> - </section> - - <section id="install-modules-gd-graph"> - <title>GD::Graph (&min-gd-graph-ver;)</title> - - <para>The GD::Graph module is only required if you want graphical - reports. - </para> - </section> - - <section id="install-modules-gd-text"> - <title>GD::Text (&min-gd-text-ver;)</title> - - <para>The GD::Text module is only required if you want graphical - reports. - </para> - </section> - - <section id="install-modules-xml-twig"> - <title>XML::Twig (&min-xml-twig-ver;)</title> - - <para>The XML::Twig module is only required if you want to import - XML bugs using the <filename>importxml.pl</filename> - script. This is required to use Bugzilla's "move bugs" feature; - you may also want to use it for migrating from another bug database. - </para> - </section> - - <section id="install-modules-soap-lite"> - <title>SOAP::Lite (&min-soap-lite-ver;)</title> - <para>Installing SOAP::Lite enables your Bugzilla installation to be - accessible at a standardized Web Service interface (SOAP/XML-RPC) - by third-party applications via HTTP(S). - </para> - </section> - - <section id="install-modules-patchreader"> - <title>PatchReader (&min-patchreader-ver;)</title> - - <para>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. - </para> - </section> - </section> - <section id="install-MTA"> - <title>Mail Transfer Agent (MTA)</title> - - <para> - Bugzilla is dependent on the availability of an e-mail system for its - user authentication and for other tasks. - </para> - - <note> - <para> - This is not entirely true. It is possible to completely disable - email sending, or to have Bugzilla store email messages in a - file instead of sending them. However, this is mainly intended - for testing, as disabling or diverting email on a production - machine would mean that users could miss important events (such - as bug changes or the creation of new accounts). - </para> - - <para> - For more information, see the <quote>mail_delivery_method</quote> parameter - in <xref linkend="parameters" />. - </para> - </note> - - <para> - On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will - suffice. Sendmail, Postfix, qmail and Exim are examples of common - MTAs. Sendmail is the original Unix MTA, but the others are easier to - configure, and therefore many people replace Sendmail with Postfix or - Exim. They are drop-in replacements, so Bugzilla will not - distinguish between them. - </para> - - <para> - If you are using Sendmail, version 8.7 or higher is required. - If you are using a Sendmail-compatible MTA, it must be congruent with - at least version 8.7 of Sendmail. - </para> - - <para> - Consult the manual for the specific MTA you choose for detailed - installation instructions. Each of these programs will have their own - configuration files where you must configure certain parameters to - ensure that the mail is delivered properly. They are implemented - as services, and you should ensure that the MTA is in the auto-start - list of services for the machine. - </para> - - <para> - If a simple mail sent with the command-line 'mail' program - succeeds, then Bugzilla should also be fine. - </para> - - </section> - <section id="using-mod_perl-with-bugzilla"> - <title>Installing Bugzilla on mod_perl</title> - <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on - Apache. <literal>mod_perl</literal> has some additional requirements to that of running - Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para> - - <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be - obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires - version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para> - - <para>Bugzilla also requires a more up-to-date version of the CGI - perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver; - </para> - </section> - </section> - - <section id="configuration"> - <title>Configuration</title> - - <warning> - <para> - 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. Be certain to read - <xref linkend="security"/> for some important security tips. - </para> - </warning> - - <section id="localconfig"> - <title>localconfig</title> - - <para> - You should now run <filename>checksetup.pl</filename> again, this time - without the <literal>--check-modules</literal> switch. - </para> - <screen><prompt>bash#</prompt> ./checksetup.pl</screen> - <para> - This time, <filename>checksetup.pl</filename> should tell you that all - the correct modules are installed and will display a message about, and - write out a file called, <filename>localconfig</filename>. This file - contains the default settings for a number of Bugzilla parameters. - </para> - - <para> - Load this file in your editor. The only value you - <emphasis>need</emphasis> 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. - </para> - - <para> - You may need to change the value of - <emphasis>webservergroup</emphasis> if your web server does not - run in the "apache" group. On Debian, for example, Apache runs in - the "www-data" group. If you are going to run Bugzilla on a - machine where you do not have root access (such as on a shared web - hosting account), you will need to leave - <emphasis>webservergroup</emphasis> empty, ignoring the warnings - that <filename>checksetup.pl</filename> will subsequently display - every time it is run. - </para> - - <caution> - <para> - If you are using suexec, you should use your own primary group - for <emphasis>webservergroup</emphasis> rather than leaving it - empty, and see the additional directions in the suexec section - <xref linkend="suexec" />. - </para> - </caution> - - <para> - The other options in the <filename>localconfig</filename> 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. - </para> - - <para> - 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 <filename>checksetup.pl</filename>, - the changes will get picked up. - </para> - </section> - - <section id="database-engine"> - <title>Database Server</title> - <para> - This section deals with configuring your database server for use - with Bugzilla. Currently, MySQL (<xref linkend="mysql"/>) and - PostgreSQL (<xref linkend="postgresql"/>) are available. - </para> - - <section id="database-schema"> - <title>Bugzilla Database Schema</title> - - <para> - The Bugzilla database schema is available at - <ulink url="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">Ravenbrook</ulink>. - This very valuable tool can generate a written description of - the Bugzilla database schema for any version of Bugzilla. It - can also generate a diff between two versions to help someone - see what has changed. - </para> - </section> - - <section id="mysql"> - <title>MySQL</title> - - <caution> - <para> - MySQL's default configuration is very insecure. - <xref linkend="security-mysql"/> has some good information for - improving your installation's security. - </para> - </caution> - - <section id="install-setupdatabase"> - <title>Allow large attachments</title> - - <para> - By default, MySQL will only accept packets up to 64Kb in size. - If you want to have attachments larger than this, you will need - to modify your <filename>/etc/my.cnf</filename> as below. - </para> - - <screen> [mysqld] - # Allow packets up to 1M - max_allowed_packet=1M</screen> - - <para> - There is also a parameter in Bugzilla called 'maxattachmentsize' - (default = 1000 Kb) that controls the maximum allowable attachment - size. Attachments larger than <emphasis>either</emphasis> the - 'max_allowed_packet' or 'maxattachmentsize' value will not be - accepted by Bugzilla. - </para> - - <note> - <para> - This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. Their maximum size is - controlled using the 'maxlocalattachment' parameter. - </para> - </note> - </section> - - <section> - <title>Allow small words in full-text indexes</title> - - <para>By default, words must be at least four characters in length - in order to be indexed by MySQL's full-text indexes. This causes - a lot of Bugzilla specific words to be missed, including "cc", - "ftp" and "uri".</para> - - <para>MySQL can be configured to index those words by setting the - ft_min_word_len param to the minimum size of the words to index. - This can be done by modifying the <filename>/etc/my.cnf</filename> - according to the example below:</para> - - <screen> [mysqld] - # Allow small words in full-text indexes - ft_min_word_len=2</screen> - - <para>Rebuilding the indexes can be done based on documentation found at - <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>. - </para> - </section> - - <section id="install-setupdatabase-adduser"> - <title>Add a user to MySQL</title> - - <para> - 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 - <filename>localconfig</filename>; if you changed those, - you need to modify the SQL command appropriately. You will - need the <replaceable>$db_pass</replaceable> password you - set in <filename>localconfig</filename> in - <xref linkend="localconfig"/>. - </para> - - <para> - We use an SQL <command>GRANT</command> command to create - a <quote>bugs</quote> user. This also restricts the - <quote>bugs</quote>user to operations within a database - called <quote>bugs</quote>, and only allows the account - to connect from <quote>localhost</quote>. Modify it to - reflect your setup if you will be connecting from another - machine or as a different user. - </para> - - <para> - Run the <filename>mysql</filename> command-line client and enter: - </para> - - <screen> <prompt>mysql></prompt> GRANT SELECT, INSERT, - UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, - CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* - TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>'; - <prompt>mysql></prompt> FLUSH PRIVILEGES;</screen> - - </section> - - <section> - <title>Permit attachments table to grow beyond 4GB</title> - - <para> - By default, MySQL will limit the size of a table to 4GB. - This limit is present even if the underlying filesystem - has no such limit. To set a higher limit, follow these - instructions. - </para> - - <para> - After you have completed the rest of the installation (or at least the - database setup parts), you should run the <filename>MySQL</filename> - command-line client and enter the following, replacing <literal>$bugs_db</literal> - with your Bugzilla database name (<emphasis>bugs</emphasis> by default): - </para> - - <screen> - <prompt>mysql></prompt> use <replaceable>$bugs_db</replaceable> - <prompt>mysql></prompt> ALTER TABLE attachments - AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; - </screen> - - <para> - The above command will change the limit to 20GB. Mysql will have - to make a temporary copy of your entire table to do this. Ideally, - you should do this when your attachments table is still small. - </para> - - <note> - <para> - This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. - </para> - </note> - </section> - </section> - - <section id="postgresql"> - <title>PostgreSQL</title> - <section> - <title>Add a User to PostgreSQL</title> - - <para>You need to add a new user to PostgreSQL for the Bugzilla - application to use when accessing the database. The following instructions - assume the defaults in <filename>localconfig</filename>; if you - changed those, you need to modify the commands appropriately. You will - need the <replaceable>$db_pass</replaceable> password you - set in <filename>localconfig</filename> in - <xref linkend="localconfig"/>.</para> - - <para>On most systems, to create the user in PostgreSQL, you will need to - login as the root user, and then</para> - - <screen> <prompt>bash#</prompt> su - postgres</screen> - - <para>As the postgres user, you then need to create a new user: </para> - - <screen> <prompt>bash$</prompt> createuser -U postgres -dAP bugs</screen> - - <para>When asked for a password, provide the password which will be set as - <replaceable>$db_pass</replaceable> in <filename>localconfig</filename>. - The created user will have the ability to create databases and will not be - able to create new users.</para> - </section> - - <section> - <title>Configure PostgreSQL</title> - - <para>Now, you will need to edit <filename>pg_hba.conf</filename> which is - usually located in <filename>/var/lib/pgsql/data/</filename>. In this file, - you will need to add a new line to it as follows:</para> - - <para> - <computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput> - </para> - - <para>This means that for TCP/IP (host) connections, allow connections from - '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use - password authentication (md5) for that user.</para> - - <para>Now, you will need to restart PostgreSQL, but you will need to fully - stop and start the server rather than just restarting due to the possibility - of a change to <filename>postgresql.conf</filename>. After the server has - restarted, you will need to edit <filename>localconfig</filename>, finding - the <literal>$db_driver</literal> variable and setting it to - <literal>Pg</literal> and changing the password in <literal>$db_pass</literal> - to the one you picked previously, while setting up the account.</para> - </section> - </section> - </section> - - <section> - <title>checksetup.pl</title> - - <para> - Next, rerun <filename>checksetup.pl</filename>. 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. - </para> - - <para> - 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. - </para> - - <para> - <filename>checksetup.pl</filename> will then finish. You may rerun - <filename>checksetup.pl</filename> at any time if you wish. - </para> - </section> - - - <section id="http"> - <title>Web server</title> - <para> - Configure your web server according to the instructions in the - appropriate section. (If it makes a difference in your choice, - the Bugzilla Team recommends Apache.) To check whether your web server - is correctly configured, try to access <filename>testagent.cgi</filename> - from your web server. If "OK" is displayed, then your configuration - is successful. Regardless of which web server - you are using, however, ensure that sensitive information is - not remotely available by properly applying the access controls in - <xref linkend="security-webserver-access"/>. You can run - <filename>testserver.pl</filename> to check if your web server serves - Bugzilla files as expected. - </para> - - <section id="http-apache"> - <title>Bugzilla using Apache</title> - <para>You have two options for running Bugzilla under Apache - - <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and - <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla - 2.23) - </para> - <section id="http-apache-mod_cgi"> - <title>Apache <productname>httpd</productname> with mod_cgi</title> - - <para> - To configure your Apache web server to work with Bugzilla while using - mod_cgi, do the following: - </para> - - <procedure> - <step> - <para> - Load <filename>httpd.conf</filename> in your editor. - In Fedora and Red Hat Linux, this file is found in - <filename class="directory">/etc/httpd/conf</filename>. - </para> - </step> - - <step> - <para> - Apache uses <computeroutput><Directory></computeroutput> - directives to permit fine-grained permission setting. Add the - following lines to a directive that applies to the location - of your Bugzilla installation. (If such a section does not - exist, you'll want to add one.) In this example, Bugzilla has - been installed at - <filename class="directory">/var/www/html/bugzilla</filename>. - </para> - - <programlisting> - <Directory /var/www/html/bugzilla> - AddHandler cgi-script .cgi - Options +Indexes +ExecCGI - DirectoryIndex index.cgi - AllowOverride Limit - </Directory> - </programlisting> - - <para> - These instructions: allow apache to run .cgi files found - within the bugzilla directory; instructs the server to look - for a file called <filename>index.cgi</filename> if someone - only types the directory name into the browser; and allows - Bugzilla's <filename>.htaccess</filename> files to override - global permissions. - </para> - - <note> - <para> - It is possible to make these changes globally, or to the - directive controlling Bugzilla's parent directory (e.g. - <computeroutput><Directory /var/www/html/></computeroutput>). - Such changes would also apply to the Bugzilla directory... - but they would also apply to many other places where they - may or may not be appropriate. In most cases, including - this one, it is better to be as restrictive as possible - when granting extra access. - </para> - </note> - </step> - - <step> - <para> - <filename>checksetup.pl</filename> can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the <computeroutput>Group</computeroutput> - line in <filename>httpd.conf</filename>, place the value found - there in the <replaceable>$webservergroup</replaceable> variable - in <filename>localconfig</filename>, then rerun - <filename>checksetup.pl</filename>. - </para> - </step> - - <step> - <para> - Optional: If Bugzilla does not actually reside in the webspace - directory, but instead has been symbolically linked there, you - will need to add the following to the - <computeroutput>Options</computeroutput> line of the Bugzilla - <computeroutput><Directory></computeroutput> directive - (the same one as in the step above): - </para> - - <programlisting> - +FollowSymLinks - </programlisting> - - <para> - Without this directive, Apache will not follow symbolic links - to places outside its own directory structure, and you will be - unable to run Bugzilla. - </para> - </step> - </procedure> - </section> - <section id="http-apache-mod_perl"> - <title>Apache <productname>httpd</productname> with mod_perl</title> - - <para>Some configuration is required to make Bugzilla work with Apache - and mod_perl</para> - - <procedure> - <step> - <para> - Load <filename>httpd.conf</filename> in your editor. - In Fedora and Red Hat Linux, this file is found in - <filename class="directory">/etc/httpd/conf</filename>. - </para> - </step> - - <step> - <para>Add the following information to your httpd.conf file, substituting - where appropriate with your own local paths.</para> - - <note> - <para>This should be used instead of the <Directory> block - shown above. This should also be above any other <literal>mod_perl</literal> - directives within the <filename>httpd.conf</filename> and must be specified - in the order as below.</para> - </note> - <warning> - <para>You should also ensure that you have disabled <literal>KeepAlive</literal> - support in your Apache install when utilizing Bugzilla under mod_perl</para> - </warning> - - <programlisting> - PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl - </programlisting> - </step> - - <step> - <para> - <filename>checksetup.pl</filename> can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the <computeroutput>Group</computeroutput> - line in <filename>httpd.conf</filename>, place the value found - there in the <replaceable>$webservergroup</replaceable> variable - in <filename>localconfig</filename>, then rerun - <filename>checksetup.pl</filename>. - </para> - </step> - </procedure> - - <para>On restarting Apache, Bugzilla should now be running within the - mod_perl environment. Please ensure you have run checksetup.pl to set - permissions before you restart Apache.</para> - - <note> - <para>Please bear the following points in mind when looking at using - Bugzilla under mod_perl: - <itemizedlist> - <listitem> - <para> - mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be - looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM. - The more RAM you can get, the better. mod_perl is basically trading RAM for - speed. At least 2GB total system RAM is recommended for running Bugzilla under - mod_perl. - </para> - </listitem> - <listitem> - <para> - Under mod_perl, you have to restart Apache if you make any manual change to - any Bugzilla file. You can't just reload--you have to actually - <emphasis>restart</emphasis> the server (as in make sure it stops and starts - again). You <emphasis>can</emphasis> change localconfig and the params file - manually, if you want, because those are re-read every time you load a page. - </para> - </listitem> - <listitem> - <para> - You must run in Apache's Prefork MPM (this is the default). The Worker MPM - may not work--we haven't tested Bugzilla's mod_perl support under threads. - (And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.) - </para> - </listitem> - <listitem> - <para> - Bugzilla generally expects to be the only mod_perl application running on - your entire server. It may or may not work if there are other applications also - running under mod_perl. It does try its best to play nice with other mod_perl - applications, but it still may have conflicts. - </para> - </listitem> - <listitem> - <para> - It is recommended that you have one Bugzilla instance running under mod_perl - on your server. Bugzilla has not been tested with more than one instance running. - </para> - </listitem> - </itemizedlist> - </para> - </note> - </section> - </section> - - <section id="http-iis"> - <title>Microsoft <productname>Internet Information Services</productname></title> - - <para> - If you are running Bugzilla on Windows and choose to use - Microsoft's <productname>Internet Information Services</productname> - or <productname>Personal Web Server</productname> you will need - to perform a number of other configuration steps as explained below. - You may also want to refer to the following Microsoft Knowledge - Base articles: - <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink> - <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0, - 5.0, and 5.1</quote> (for <productname>Internet Information - Services</productname>) and - <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink> - <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web - Server on Windows 95/98</quote> (for <productname>Personal Web - Server</productname>). - </para> - - <para> - You will need to create a virtual directory for the Bugzilla - install. Put the Bugzilla files in a directory that is named - something <emphasis>other</emphasis> than what you want your - end-users accessing. That is, if you want your users to access - your Bugzilla installation through - <quote>http://<yourdomainname>/Bugzilla</quote>, then do - <emphasis>not</emphasis> put your Bugzilla files in a directory - named <quote>Bugzilla</quote>. Instead, place them in a different - location, and then use the IIS Administration tool to create a - Virtual Directory named "Bugzilla" that acts as an alias for the - actual location of the files. When creating that virtual directory, - make sure you add the <quote>Execute (such as ISAPI applications or - CGI)</quote> access permission. - </para> - - <para> - You will also need to tell IIS how to handle Bugzilla's - .cgi files. Using the IIS Administration tool again, open up - the properties for the new virtual directory and select the - Configuration option to access the Script Mappings. Create an - entry mapping .cgi to: - </para> - - <programlisting> -<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s - </programlisting> - - <para> - For example: - </para> - - <programlisting> -c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s - </programlisting> - - <note> - <para> - The ActiveState install may have already created an entry for - .pl files that is limited to <quote>GET,HEAD,POST</quote>. If - so, this mapping should be <emphasis>removed</emphasis> as - Bugzilla's .pl files are not designed to be run via a web server. - </para> - </note> - - <para> - IIS will also need to know that the index.cgi should be treated - as a default document. On the Documents tab page of the virtual - directory properties, you need to add index.cgi as a default - document type. If you wish, you may remove the other default - document types for this particular virtual directory, since Bugzilla - doesn't use any of them. - </para> - - <para> - Also, and this can't be stressed enough, make sure that files - such as <filename>localconfig</filename> and your - <filename class="directory">data</filename> directory are - secured as described in <xref linkend="security-webserver-access"/>. - </para> - - </section> - - </section> - - <section id="install-config-bugzilla"> - <title>Bugzilla</title> - - <para> - Your Bugzilla should now be working. Access - <filename>http://<your-bugzilla-server>/</filename> - - you should see the Bugzilla - front page. If not, consult the Troubleshooting section, - <xref linkend="troubleshooting"/>. - </para> - - <note> - <para> - The URL above may be incorrect if you installed Bugzilla into a - subdirectory or used a symbolic link from your web site root to - the Bugzilla directory. - </para> - </note> - - <para> - Log in with the administrator account you defined in the last - <filename>checksetup.pl</filename> 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 <xref linkend="parameters"/>; - you should certainly alter - <command>maintainer</command> and <command>urlbase</command>; - you may also want to alter - <command>cookiepath</command> or <command>requirelogin</command>. - </para> - - <para> - This would also be a good time to revisit the - <filename>localconfig</filename> 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 <filename>checksetup.pl</filename> if you change it. - </para> - - <para> - Bugzilla has several optional features which require extra - configuration. You can read about those in - <xref linkend="extraconfig"/>. - </para> - </section> - </section> - - <section id="extraconfig"> - <title>Optional Additional Configuration</title> - - <para> - Bugzilla has a number of optional features. This section describes how - to configure or enable them. - </para> - - <section> - <title>Bug Graphs</title> - - <para>If you have installed the necessary Perl modules you - can start collecting statistics for the nifty Bugzilla - graphs.</para> - - <screen><prompt>bash#</prompt> <command>crontab -e</command></screen> - - <para> - This should bring up the crontab file in your editor. - Add a cron entry like this to run - <filename>collectstats.pl</filename> - daily at 5 after midnight: - </para> - - <programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting> - - <para> - After two days have passed you'll be able to view bug graphs from - the Reports page. - </para> - - <para> - When upgrading Bugzilla, this format may change. - To create new status data, (re)move old data and run the following - commands: - </para> - - <screen> - <prompt>bash$</prompt> - <command>cd <your-bugzilla-directory></command> - <prompt>bash$</prompt> - <command>./collectstats.pl --regenerate</command> - </screen> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="installation-whining-cron"> - <title>The Whining Cron</title> - - <para>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. - </para> - <para> - 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. - </para> - - <programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="installation-whining"> - <title>Whining</title> - - <para> - As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy - them at regular intervals, by having Bugzilla execute saved searches - at certain times and emailing the results to the user. This is known - as "Whining". The process of configuring Whining is described - in <xref linkend="whining"/>, but for it to work a Perl script must be - executed at regular intervals. - </para> - - <para> - 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 every 15 minutes. - </para> - - <programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting> - - <note> - <para> - Whines can be executed as often as every 15 minutes, so if you specify - longer intervals between executions of whine.pl, some users may not - be whined at as often as they would expect. Depending on the person, - this can either be a very Good Thing or a very Bad Thing. - </para> - </note> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="apache-addtype"> - <title>Serving Alternate Formats with the right MIME type</title> - - <para> - Some Bugzilla pages have alternate formats, other than just plain - <acronym>HTML</acronym>. In particular, a few Bugzilla pages can - output their contents as either <acronym>XUL</acronym> (a special - Mozilla format, that looks like a program <acronym>GUI</acronym>) - or <acronym>RDF</acronym> (a type of structured <acronym>XML</acronym> - that can be read by various programs). - </para> - <para> - In order for your users to see these pages correctly, Apache must - send them with the right <acronym>MIME</acronym> type. To do this, - add the following lines to your Apache configuration, either in the - <computeroutput><VirtualHost></computeroutput> section for your - Bugzilla, or in the <computeroutput><Directory></computeroutput> - section for your Bugzilla: - </para> - <para> - <screen>AddType application/vnd.mozilla.xul+xml .xul -AddType application/rdf+xml .rdf</screen> - </para> - </section> - </section> - - <section id="multiple-bz-dbs"> - <title>Multiple Bugzilla databases with a single installation</title> - - <para>The previous instructions referred to a standard installation, with - one unique Bugzilla database. However, you may want to host several - distinct installations, without having several copies of the code. This is - possible by using the PROJECT environment variable. When accessed, - Bugzilla checks for the existence of this variable, and if present, uses - its value to check for an alternative configuration file named - <filename>localconfig.<PROJECT></filename> in the same location as - the default one (<filename>localconfig</filename>). It also checks for - customized templates in a directory named - <filename><PROJECT></filename> in the same location as the - default one (<filename>template/<langcode></filename>). By default - this is <filename>template/en/default</filename> so PROJECT's templates - would be located at <filename>template/en/PROJECT</filename>.</para> - - <para>To set up an alternate installation, just export PROJECT=foo before - running <command>checksetup.pl</command> for the first time. It will - result in a file called <filename>localconfig.foo</filename> instead of - <filename>localconfig</filename>. Edit this file as described above, with - reference to a new database, and re-run <command>checksetup.pl</command> - to populate it. That's all.</para> - - <para>Now you have to configure the web server to pass this environment - variable when accessed via an alternate URL, such as virtual host for - instance. The following is an example of how you could do it in Apache, - other Webservers may differ. -<programlisting> -<VirtualHost 212.85.153.228:80> - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla -</VirtualHost> -</programlisting> - </para> - - <para>Don't forget to also export this variable before accessing Bugzilla - by other means, such as cron tasks for instance.</para> - </section> - - <section id="os-specific"> - <title>OS-Specific Installation Notes</title> - - <para>Many aspects of the Bugzilla installation can be affected by 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. - </para> - - <para>If you have anything to add or notes for an operating system not - covered, please file a bug in &bzg-bugs;. - </para> - - <section id="os-win32"> - <title>Microsoft Windows</title> - <para> - Making Bugzilla work on Windows is more difficult than making it - work on Unix. For that reason, we still recommend doing so on a Unix - based system such as GNU/Linux. That said, if you do want to get - Bugzilla running on Windows, you will need to make the following - adjustments. A detailed step-by-step - <ulink url="http://www.bugzilla.org/docs/win32install.html"> - installation guide for Windows</ulink> is also available - if you need more help with your installation. - </para> - - <section id="win32-perl"> - <title>Win32 Perl</title> - <para> - Perl for Windows can be obtained from - <ulink url="http://www.activestate.com/">ActiveState</ulink>. - You should be able to find a compiled binary at <ulink - url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />. - The following instructions assume that you are using version - 5.8.1 of ActiveState. - </para> - - <note> - <para> - These instructions are for 32-bit versions of Windows. If you are - using a 64-bit version of Windows, you will need to install 32-bit - Perl in order to install the 32-bit modules as described below. - </para> - </note> - - </section> - - <section id="win32-perl-modules"> - <title>Perl Modules on Win32</title> - - <para> - Bugzilla on Windows requires the same perl modules found in - <xref linkend="install-perlmodules"/>. The main difference is that - windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead - of CPAN. ActiveState provides a GUI to manage Perl modules. We highly - recommend that you use it. If you prefer to use ppm from the - command-line, type: - </para> - - <programlisting> -C:\perl> <command>ppm install <module name></command> - </programlisting> - - <para> - The best source for the Windows PPM modules needed for Bugzilla - is probably the theory58S website, which you can add to your list - of repositories as follows (for Perl 5.8.x): - </para> - - <programlisting> -<command>ppm repo add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> - </programlisting> - - <para> - If you are using Perl 5.10.x, you cannot use the same PPM modules as Perl - 5.8.x as they are incompatible. In this case, you should add the following - repository: - </para> - <programlisting> -<command>ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/</command> - </programlisting> - - <note> - <para> - In versions prior to 5.8.8 build 819 of PPM the command is - <programlisting> -<command>ppm repository add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> - </programlisting> - </para> - </note> - <note> - <para> - The PPM repository stores modules in 'packages' that may have - a slightly different name than the module. If retrieving these - modules from there, you will need to pay attention to the information - provided when you run <command>checksetup.pl</command> as it will - tell you what package you'll need to install. - </para> - </note> - - <tip> - <para> - If you are behind a corporate firewall, you will need to let the - ActiveState PPM utility know how to get through it to access - the repositories by setting the HTTP_proxy system environmental - variable. For more information on setting that variable, see - the ActiveState documentation. - </para> - </tip> - </section> - - <section id="win32-code-changes"> - <title>Code changes required to run on Win32</title> - - <para> - Bugzilla on Win32 is supported out of the box from version 2.20; this - means that no code changes are required to get Bugzilla running. - </para> - - </section> - - <section id="win32-http"> - <title>Serving the web pages</title> - - <para> - 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 <xref linkend="security-webserver-access"/>. More - information on configuring specific web servers can be found - in <xref linkend="http"/>. - </para> - - <note> - <para> - If using Apache on windows, you can set the <ulink - url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> - directive in your Apache config to avoid having to modify - the first line of every script to contain your path to Perl - instead of <filename>/usr/bin/perl</filename>. When setting - <filename>ScriptInterpreterSource</filename>, do not forget - to specify the <command>-T</command> flag to enable the taint - mode. For example: <command>C:\Perl\bin\perl.exe -T</command>. - </para> - </note> - - </section> - - <section id="win32-email"> - <title>Sending Email</title> - - <para> - To enable Bugzilla to send email on Windows, the server running the - Bugzilla code must be able to connect to, or act as, an SMTP server. - </para> - - </section> - </section> - - <section id="os-macosx"> - <title><productname>Mac OS X</productname></title> - - <para>Making Bugzilla work on Mac OS X requires the following - adjustments.</para> - - <section id="macosx-sendmail"> - <title>Sendmail</title> - - <para>In Mac OS X 10.3 and later, - <ulink url="http://www.postfix.org/">Postfix</ulink> - is used as the built-in email server. Postfix provides an executable - that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can - find it.</para> - - <para>As of version 2.20, Bugzilla will be able to find the fake - sendmail executable without any assistance. However, you will have - to turn on the sendmailnow parameter before you do anything that would - result in email being sent. For more information, see the description - of the sendmailnow parameter in <xref linkend="parameters"/>.</para> - - </section> - - <section id="macosx-libraries"> - <title>Libraries & Perl Modules on Mac OS X</title> - - <para>Apple does not include the GD library with Mac OS X. Bugzilla - needs this for bug graphs.</para> - - <para>You can use DarwinPorts (<ulink url="http://darwinports.com/"/>) - or Fink (<ulink url="http://sourceforge.net/projects/fink/"/>), both - of which are similar in nature to the CPAN installer, but install - common unix programs.</para> - - <para>Follow the instructions for setting up DarwinPorts or Fink. - Once you have one installed, you'll want to use it to install the - <filename>gd2</filename> package. - </para> - - <para>Fink 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 <glossterm linkend="gloss-cpan">CPAN</glossterm> to - install the GD Perl module. - </para> - - <note> - <para>To prevent creating conflicts with the software that Apple - installs by default, Fink creates its own directory tree at - <filename class="directory">/sw</filename> where it installs most of - the software that it installs. This means your libraries and headers - will be at <filename class="directory">/sw/lib</filename> and - <filename class="directory">/sw/include</filename> instead of - <filename class="directory">/usr/lib</filename> and - <filename class="directory">/usr/include</filename>. When the - Perl module config script asks where your <filename>libgd</filename> - is, be sure to tell it - <filename class="directory">/sw/lib</filename>. - </para> - </note> - - <para>Also available via DarwinPorts and Fink is - <filename>expat</filename>. After installing the expat package, you - will be able to install XML::Parser using CPAN. If you use fink, 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: - </para> - - <screen> -# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/> -# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include -# make; make test; make install <co id="macosx-make"/> -# exit <co id="macosx-exit"/> - </screen> - <calloutlist> - <callout arearefs="macosx-look macosx-exit"> - <para>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. - </para> - </callout> - <callout arearefs="macosx-make"> - <para>You should watch the output from these make commands, - especially <quote>make test</quote> as errors may prevent - XML::Parser from functioning correctly with Bugzilla. - </para> - </callout> - </calloutlist> - </section> - </section> - - <section id="os-linux"> - <title>Linux Distributions</title> - <para>Many Linux distributions include Bugzilla and its - dependencies in their native package management systems. - Installing Bugzilla with root access on any Linux system - should be as simple as finding the Bugzilla package in the - package management application and installing it using the - normal command syntax. Several distributions also perform - the proper web server configuration automatically on installation. - </para> - <para>Please consult the documentation of your Linux - distribution for instructions on how to install packages, - or for specific instructions on installing Bugzilla with - native package management tools. There is also a - <ulink url="http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation"> - Bugzilla Wiki Page</ulink> for distro-specific installation - notes. - </para> - </section> - </section> - - - <section id="nonroot"> - <title>UNIX (non-root) Installation Notes</title> - - <section> - <title>Introduction</title> - - <para>If you are running a *NIX OS as non-root, either due - to lack of access (web hosts, for example) or for security - reasons, this will detail how to install Bugzilla on such - a setup. It is recommended that you read through the - <xref linkend="installation" /> - first to get an idea on the installation steps required. - (These notes will reference to steps in that guide.)</para> - - </section> - - <section> - <title>MySQL</title> - - <para>You may have MySQL installed as root. If you're - setting up an account with a web host, a MySQL account - needs to be set up for you. From there, you can create - the bugs account, or use the account given to you.</para> - - <warning> - <para>You may have problems trying to set up - <command>GRANT</command> permissions to the database. - If you're using a web host, chances are that you have a - separate database which is already locked down (or one big - database with limited/no access to the other areas), but you - may want to ask your system administrator what the security - settings are set to, and/or run the <command>GRANT</command> - command for you.</para> - - <para>Also, you will probably not be able to change the MySQL - root user password (for obvious reasons), so skip that - step.</para> - </warning> - - <section> - <title>Running MySQL as Non-Root</title> - <section> - <title>The Custom Configuration Method</title> - <para>Create a file .my.cnf in your - home directory (using /home/foo in this example) - as follows....</para> - <programlisting> -[mysqld] -datadir=/home/foo/mymysql -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql] -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql.server] -user=mysql -basedir=/var/lib - -[safe_mysqld] -err-log=/home/foo/mymysql/the.log -pid-file=/home/foo/mymysql/the.pid - </programlisting> - </section> - <section> - <title>The Custom Built Method</title> - - <para>You can install MySQL as a not-root, if you really need to. - Build it with PREFIX set to <filename class="directory">/home/foo/mysql</filename>, - or use pre-installed executables, specifying that you want - to put all of the data files in <filename class="directory">/home/foo/mysql/data</filename>. - If there is another MySQL server running on the system that you - do not own, use the -P option to specify a TCP port that is not - in use.</para> - </section> - - <section> - <title>Starting the Server</title> - <para>After your mysqld program is built and any .my.cnf file is - in place, you must initialize the databases (ONCE).</para> - <screen> - <prompt>bash$</prompt> - <command>mysql_install_db</command> - </screen> - <para>Then start the daemon with</para> - <screen> - <prompt>bash$</prompt> - <command>safe_mysql &</command> - </screen> - <para>After you start mysqld the first time, you then connect to - it as "root" and <command>GRANT</command> permissions to other - users. (Again, the MySQL root account has nothing to do with - the *NIX root account.)</para> - - <note> - <para>You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed.</para> - </note> - - <warning> - <para>Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user!</para> - </warning> - </section> - </section> - - </section> - - <section> - <title>Perl</title> - - <para> - On the extremely rare chance that you don't have Perl on - the machine, you will have to build the sources - yourself. The following commands should get your system - installed with your own personal version of Perl: - </para> - - <screen> - <prompt>bash$</prompt> - <command>wget http://perl.com/CPAN/src/stable.tar.gz</command> - <prompt>bash$</prompt> - <command>tar zvxf stable.tar.gz</command> - <prompt>bash$</prompt> - <command>cd perl-5.8.1</command> (or whatever the version of Perl is called) - <prompt>bash$</prompt> - <command>sh Configure -de -Dprefix=/home/foo/perl</command> - <prompt>bash$</prompt> - <command>make && make test && make install</command> - </screen> - - <para> - Once you have Perl installed into a directory (probably - in <filename class="directory">~/perl/bin</filename>), you will need to - install the Perl Modules, described below. - </para> - </section> - - <section id="install-perlmodules-nonroot"> - <title>Perl Modules</title> - - <para> - Installing the Perl modules as a non-root user is accomplished by - running the <filename>install-module.pl</filename> - script. For more details on this script, see - <ulink url="api/install-module.html"><filename>install-module.pl</filename> - documentation</ulink> - </para> - </section> - - <section> - <title>HTTP Server</title> - - <para>Ideally, this also needs to be installed as root and - run under a special web server account. As long as - the web server will allow the running of *.cgi files outside of a - cgi-bin, and a way of denying web access to certain files (such as a - .htaccess file), you should be good in this department.</para> - - <section> - <title>Running Apache as Non-Root</title> - - <para>You can run Apache as a non-root user, but the port will need - to be set to one above 1024. If you type <command>httpd -V</command>, - you will get a list of the variables that your system copy of httpd - uses. One of those, namely HTTPD_ROOT, tells you where that - installation looks for its config information.</para> - - <para>From there, you can copy the config files to your own home - directory to start editing. When you edit those and then use the -d - option to override the HTTPD_ROOT compiled into the web server, you - get control of your own customized web server.</para> - - <note> - <para>You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed.</para> - </note> - - <warning> - <para>Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user!</para> - </warning> - </section> - </section> - - <section> - <title>Bugzilla</title> - - <para> - When you run <command>./checksetup.pl</command> to create - the <filename>localconfig</filename> file, it will list the Perl - modules it finds. If one is missing, go back and double-check the - module installation from <xref linkend="install-perlmodules-nonroot"/>, - then delete the <filename>localconfig</filename> file and try again. - </para> - - <warning> - <para>One option in <filename>localconfig</filename> you - might have problems with is the web server group. If you can't - successfully browse to the <filename>index.cgi</filename> (like - a Forbidden error), you may have to relax your permissions, - and blank out the web server group. Of course, this may pose - as a security risk. Having a properly jailed shell and/or - limited access to shell accounts may lessen the security risk, - but use at your own risk.</para> - </warning> - - <section id="suexec"> - <title>suexec or shared hosting</title> - - <para>If you are running on a system that uses suexec (most shared - hosting environments do this), you will need to set the - <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename> - to match <emphasis>your</emphasis> primary group, rather than the one - the web server runs under. You will need to run the following - shell commands after running <command>./checksetup.pl</command>, - every time you run it (or modify <filename>checksetup.pl</filename> - to do them for you via the system() command). - <programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done - for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done - find . -name .htaccess -exec chmod o+r {} \; - chmod o+x . data data/webdot</programlisting> - Pay particular attention to the number of semicolons and dots. - They are all important. A future version of Bugzilla will - hopefully be able to do this for you out of the box.</para> - </section> - </section> - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/xml/integration.xml b/docs/xml/integration.xml deleted file mode 100644 index 485a03dcd..000000000 --- a/docs/xml/integration.xml +++ /dev/null @@ -1,120 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> -<!-- Keep these tools listings in alphabetical order please. -MPB --> -<section id="integration"> - <title>Integrating Bugzilla with Third-Party Tools</title> - - <section id="bonsai" - xreflabel="Bonsai, the Mozilla automated CVS management system"> - <title>Bonsai</title> - - <para>Bonsai is a web-based tool for managing - <xref linkend="cvs" /> - - . 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 - <xref linkend="tinderbox" />. - </para> - </section> - - <section id="cvs" xreflabel="CVS, the Concurrent Versioning System"> - <title>CVS</title> - - <para>CVS integration is best accomplished, at this point, using the - Bugzilla Email Gateway.</para> - - <para>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 - <quote>[Bug XXXX]</quote>, - 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 <filename>contrib/bugzilla_email_append.pl</filename> script. - </para> - - <para>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: <ulink url="http://www.cvszilla.org/"/>. - </para> - - <para>Another system capable of CVS integration with Bugzilla is - Scmbug. This system provides generic integration of Source code - Configuration Management with Bugtracking. Check it out at: <ulink - url="http://freshmeat.net/projects/scmbug/"/>. - </para> - - </section> - - <section id="scm" - xreflabel="Perforce SCM (Fast Software Configuration Management System, a powerful commercial alternative to CVS"> - - <title>Perforce SCM</title> - - <para>You can find the project page for Bugzilla and Teamtrack Perforce - integration (p4dti) at: - <ulink url="http://www.ravenbrook.com/project/p4dti/"/> - - . - <quote>p4dti</quote> - - is now an officially supported product from Perforce, and you can find - the "Perforce Public Depot" p4dti page at - <ulink url="http://public.perforce.com/public/perforce/p4dti/index.html"/> - - .</para> - - <para>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.</para> - </section> - - <section id="svn" - xreflabel="Subversion, a compelling replacement for CVS"> - <title>Subversion</title> - <para>Subversion is a free/open-source version control system, - designed to overcome various limitations of CVS. Integration of - Subversion with Bugzilla is possible using Scmbug, a system - providing generic integration of Source Code Configuration - Management with Bugtracking. Scmbug is available at <ulink - url="http://freshmeat.net/projects/scmbug/"/>.</para> - </section> - - <section id="tinderbox" - xreflabel="Tinderbox, the Mozilla automated build management system"> - <title>Tinderbox/Tinderbox2</title> - - <para>Tinderbox is a continuous-build system which can integrate with - Bugzilla - see - <ulink url="http://www.mozilla.org/projects/tinderbox"/> for details - of Tinderbox, and - <ulink url="http://tinderbox.mozilla.org/showbuilds.cgi"/> to see it - in action.</para> - </section> -</section> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/introduction.xml b/docs/xml/introduction.xml deleted file mode 100644 index 3968702c6..000000000 --- a/docs/xml/introduction.xml +++ /dev/null @@ -1,121 +0,0 @@ -<chapter id="introduction"> - <title>Introduction</title> - - <section id="what-is-bugzilla"> - <title>What is Bugzilla?</title> - - <para> - Bugzilla is a bug- or issue-tracking system. Bug-tracking - systems allow individual or groups of developers effectively to keep track - of outstanding problems with their products. - </para> - - <para><emphasis>Do we need more here?</emphasis></para> - - </section> - - <section id="why-tracking"> - <title>Why use a bug-tracking system?</title> - - <para>Those who do not use a bug-tracking system tend to rely on - shared lists, email, spreadsheets and/or Post-It notes to monitor the - status of defects. This procedure - is usually error-prone and tends to cause those bugs judged least - significant by developers to be dropped or ignored.</para> - - <para>Integrated defect-tracking systems make sure that nothing gets - swept under the carpet; they provide a method of creating, storing, - arranging and processing defect reports and enhancement requests.</para> - - </section> - - <section id="why-bugzilla"> - <title>Why use Bugzilla?</title> - - <para>Bugzilla is the leading open-source/free software bug tracking - system. It boasts many advanced features, including: - <itemizedlist> - <listitem> - <para>Powerful searching</para> - </listitem> - - <listitem> - <para>User-configurable email notifications of bug changes</para> - </listitem> - - <listitem> - <para>Full change history</para> - </listitem> - - <listitem> - <para>Inter-bug dependency tracking and graphing</para> - </listitem> - - <listitem> - <para>Excellent attachment management</para> - </listitem> - - <listitem> - <para>Integrated, product-based, granular security schema</para> - </listitem> - - <listitem> - <para>Fully security-audited, and runs under Perl's taint mode</para> - </listitem> - - <listitem> - <para>A robust, stable RDBMS back-end</para> - </listitem> - - <listitem> - <para>Completely customizable and/or localizable web user - interface</para> - </listitem> - - <listitem> - <para>Additional XML, email and console interfaces</para> - </listitem> - - <listitem> - <para>Extensive configurability</para> - </listitem> - - <listitem> - <para>Smooth upgrade pathway between versions</para> - </listitem> - </itemizedlist> - </para> - - <para>Bugzilla is very adaptable to various situations. Known uses - currently include IT support queues, Systems Administration deployment - management, chip design and development problem tracking (both - pre-and-post fabrication), and software and hardware bug tracking for - luminaries such as Redhat, NASA, Linux-Mandrake, and VA Systems. - Combined with systems such as - <ulink url="http://www.cvshome.org">CVS</ulink>, - <ulink url="http://www.mozilla.org/bonsai.html">Bonsai</ulink>, or - <ulink url="http://www.perforce.com">Perforce SCM</ulink>, Bugzilla - provides a powerful, easy-to-use configuration management solution.</para> - </section> -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/xml/modules.xml b/docs/xml/modules.xml deleted file mode 100644 index 3d4f6e556..000000000 --- a/docs/xml/modules.xml +++ /dev/null @@ -1,193 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="install-perlmodules-manual"> - <title>Manual Installation of Perl Modules</title> - - <section id="modules-manual-instructions"> - <title>Instructions</title> - <para> - 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: - </para> - - <para> - <screen><prompt>bash#</prompt> tar -xzvf <module>.tar.gz -<prompt>bash#</prompt> cd <module> -<prompt>bash#</prompt> perl Makefile.PL -<prompt>bash#</prompt> make -<prompt>bash#</prompt> make test -<prompt>bash#</prompt> make install</screen> - </para> - <note> - <para> - In order to compile source code under Windows you will need to obtain - a 'make' utility. The <command>nmake</command> utility provided with - Microsoft Visual C++ may be used. As an alternative, there is a - utility called <command>dmake</command> available from CPAN which is - written entirely in Perl. - </para> - <para> - As described in <xref linkend="modules-manual-download" />, however, most - packages already exist and are available from ActiveState or theory58S. - We highly recommend that you install them using the ppm GUI available with - ActiveState and to add the theory58S repository to your list of repositories. - </para> - </note> - </section> - - <section id="modules-manual-download"> - <title>Download Locations</title> - - <note> - <para> - Running Bugzilla on Windows requires the use of ActiveState - Perl 5.8.1 or higher. Many modules already exist in the core - distribution of ActiveState Perl. Additional modules can be downloaded - from <ulink url="http://theoryx5.uwinnipeg.ca/ppms/" /> if you use - Perl 5.8.x or from <ulink url="http://cpan.uwinnipeg.ca/PPMPackages/10xx/" /> - if you use Perl 5.10.x. - </para> - </note> - - <para> - CGI: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/> - Documentation: <ulink url="http://perldoc.perl.org/CGI.html"/> - </literallayout> - </para> - - <para> - Data-Dumper: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/> - Documentation: <ulink url="http://search.cpan.org/dist/Data-Dumper/Dumper.pm"/> - </literallayout> - </para> - - <para> - Date::Format (part of TimeDate): - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/> - Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/> - </literallayout> - </para> - - <para> - DBI: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/> - Documentation: <ulink url="http://dbi.perl.org/docs/"/> - </literallayout> - </para> - - <para> - DBD::mysql: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/> - Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm"/> - </literallayout> - </para> - - <para> - DBD::Pg: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-Pg/"/> - Documentation: <ulink url="http://search.cpan.org/dist/DBD-Pg/Pg.pm"/> - </literallayout> - </para> - - <para> - File::Spec: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/> - Documentation: <ulink url="http://perldoc.perl.org/File/Spec.html"/> - </literallayout> - </para> - - <para> - Template-Toolkit: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/> - Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/> - </literallayout> - </para> - - <para> - GD: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/> - Documentation: <ulink url="http://search.cpan.org/dist/GD/GD.pm"/> - </literallayout> - </para> - - <para> - Template::Plugin::GD: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-GD/" /> - Documentation: <ulink url="http://www.template-toolkit.org/docs/aqua/Modules/index.html" /> - </literallayout> - </para> - - <para> - MIME::Parser (part of MIME-tools): - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/> - Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/> - </literallayout> - </para> - - </section> - - <section id="modules-manual-optional"> - <title>Optional Modules</title> - - <para> - Chart::Base: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/> - Documentation: <ulink url="http://search.cpan.org/dist/Chart/Chart.pod"/> - </literallayout> - </para> - - <para> - GD::Graph: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/> - Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/> - </literallayout> - </para> - - <para> - GD::Text::Align (part of GD::Text::Util): - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/> - Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/> - </literallayout> - </para> - - <para> - XML::Twig: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Twig/"/> - Documentation: <ulink url="http://standards.ieee.org/resources/spasystem/twig/twig_stable.html"/> - </literallayout> - </para> - - <para> - PatchReader: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/> - Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/> - </literallayout> - </para> - - <para> - Image::Magick: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/PerlMagick/"/> - Documentation: <ulink url="http://www.imagemagick.org/script/resources.php"/> - </literallayout> - </para> - </section> -</appendix> diff --git a/docs/xml/patches.xml b/docs/xml/patches.xml deleted file mode 100644 index 12efb0ca4..000000000 --- a/docs/xml/patches.xml +++ /dev/null @@ -1,131 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla"> - <title>Contrib</title> - - <para> - There are a number of unofficial Bugzilla add-ons in the - <filename class="directory">$BUGZILLA_ROOT/contrib/</filename> - directory. This section documents them. - </para> - - <section id="cmdline"> - <title>Command-line Search Interface</title> - - <para> - There are a suite of Unix utilities for searching Bugzilla from the - command line. They live in the - <filename class="directory">contrib/cmdline</filename> directory. - There are three files - <filename>query.conf</filename>, - <filename>buglist</filename> and <filename>bugs</filename>. - </para> - - <warning> - <para> - These files pre-date the templatization work done as part of the - 2.16 release, and have not been updated. - </para> - </warning> - - <para> - <filename>query.conf</filename> contains the mapping from - options to field names and comparison types. Quoted option names - are <quote>grepped</quote> 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 <quote>option</quote>. - </para> - - <para> - <filename>buglist</filename> is a shell script that submits a - Bugzilla query and writes the resulting HTML page to stdout. - It supports both short options, (such as <quote>-Afoo</quote> - or <quote>-Rbar</quote>) and long options (such - as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>). - If the first character of an option is not <quote>-</quote>, it is - treated as if it were prefixed with <quote>--default=</quote>. - </para> - - <para> - The column list is taken from the COLUMNLIST environment variable. - This is equivalent to the <quote>Change Columns</quote> option - that is available 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. - </para> - - <para> - <filename>bugs</filename> is a simple shell script which calls - <filename>buglist</filename> and extracts the - bug numbers from the output. Adding the prefix - <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote> - turns the bug list into a working link if any bugs are found. - Counting bugs is easy. Pipe the results through - <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command> - </para> - - <para> - Akkana Peck says she has good results piping - <filename>buglist</filename> output through - <command>w3m -T text/html -dump</command> - </para> - - </section> - - <section id="cmdline-bugmail"> - <title>Command-line 'Send Unsent Bug-mail' tool</title> - - <para> - Within the <filename class="directory">contrib</filename> directory - exists a utility with the descriptive (if compact) name - of <filename>sendunsentbugmail.pl</filename>. The purpose of this - script is, simply, to send out any bug-related mail that should - have been sent by now, but for one reason or another has not. - </para> - - <para> - To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses - the same mechanism as the <filename>sanitycheck.cgi</filename> script; - it scans through the entire database looking for bugs with changes that - were made more than 30 minutes ago, but where there is no record of - anyone related to that bug having been sent mail. Having compiled a list, - it then uses the standard rules to determine who gets mail, and sends it - out. - </para> - - <para> - As the script runs, it indicates the bug for which it is currently - sending mail; when it has finished, it gives a numerical count of how - many mails were sent and how many people were excluded. (Individual - user names are not recorded or displayed.) If the script produces - no output, that means no unsent mail was detected. - </para> - - <para> - <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script - up into the main directory, ensure it has execute permission, and run it - from the command line (or from a cron job) with no parameters. - </para> - </section> - -</appendix> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/requiredsoftware.xml b/docs/xml/requiredsoftware.xml deleted file mode 100644 index 4a751c0c7..000000000 --- a/docs/xml/requiredsoftware.xml +++ /dev/null @@ -1,77 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="downloadlinks"> - <title>Software Download Links</title> - - <para>All of these sites are current as of April, 2001. Hopefully they'll - stay current for a while.</para> - - <para>Apache Web Server: - <ulink url="http://www.apache.org/"/> - - Optional web server for Bugzilla, but recommended because of broad user - base and support.</para> - - <para>Bugzilla: - <ulink url="http://www.bugzilla.org/"/> - </para> - - <para>MySQL: - <ulink url="http://www.mysql.com/"/> - </para> - - <para>Perl: - <ulink url="http://www.perl.org/"/> - </para> - - <para>CPAN: - <ulink url="http://www.cpan.org/"/> - </para> - - <para>DBI Perl module: - <ulink url="http://www.cpan.org/modules/by-module/DBI/"/> - </para> - - <para>MySQL related Perl modules: - <ulink url="http://www.cpan.org/modules/by-module/Mysql/"/> - </para> - - <para>TimeDate Perl module collection: - <ulink url="http://www.cpan.org/modules/by-module/Date/"/> - </para> - - <para>GD Perl module: - <ulink url="http://www.cpan.org/modules/by-module/GD/"/> - - Alternately, you should be able to find the latest version of GD at - <ulink url="http://www.boutell.com/gd/"/> - </para> - - <para>Chart::Base module: - <ulink url="http://www.cpan.org/modules/by-module/Chart/"/> - </para> - - <para>(But remember, Bundle::Bugzilla will install all the modules for you.) - </para> -</appendix> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/xml/security.xml b/docs/xml/security.xml deleted file mode 100644 index 651b45241..000000000 --- a/docs/xml/security.xml +++ /dev/null @@ -1,367 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: security.xml,v 1.18 2007/09/03 10:12:04 lpsolit%gmail.com Exp $ --> - -<chapter id="security"> -<title>Bugzilla Security</title> - - <para>While some of the items in this chapter are related to the operating - system Bugzilla is running on or some of the support software required to - run Bugzilla, it is all related to protecting your data. This is not - intended to be a comprehensive guide to securing Linux, Apache, MySQL, or - any other piece of software mentioned. There is no substitute for active - administration and monitoring of a machine. The key to good security is - actually right in the middle of the word: <emphasis>U R It</emphasis>. - </para> - - <para>While programmers in general always strive to write secure code, - accidents can and do happen. The best approach to security is to always - assume that the program you are working with isn't 100% secure and restrict - its access to other parts of your machine as much as possible. - </para> - - <section id="security-os"> - <title>Operating System</title> - - <section id="security-os-ports"> - <title>TCP/IP Ports</title> - - <!-- TODO: Get exact number of ports --> - <para>The TCP/IP standard defines more than 65,000 ports for sending - and receiving traffic. Of those, Bugzilla needs exactly one to operate - (different configurations and options may require up to 3). You should - audit your server and make sure that you aren't listening on any ports - you don't need to be. It's also highly recommended that the server - Bugzilla resides on, along with any other machines you administer, be - placed behind some kind of firewall. - </para> - - </section> - - <section id="security-os-accounts"> - <title>System User Accounts</title> - - <para>Many <glossterm linkend="gloss-daemon">daemons</glossterm>, such - as Apache's <filename>httpd</filename> or MySQL's - <filename>mysqld</filename>, run as either <quote>root</quote> or - <quote>nobody</quote>. This is even worse on Windows machines where the - majority of <glossterm linkend="gloss-service">services</glossterm> - run as <quote>SYSTEM</quote>. While running as <quote>root</quote> or - <quote>SYSTEM</quote> introduces obvious security concerns, the - problems introduced by running everything as <quote>nobody</quote> may - not be so obvious. Basically, if you run every daemon as - <quote>nobody</quote> and one of them gets compromised it can - compromise every other daemon running as <quote>nobody</quote> on your - machine. For this reason, it is recommended that you create a user - account for each daemon. - </para> - - <note> - <para>You will need to set the <option>webservergroup</option> option - in <filename>localconfig</filename> to the group your web server runs - as. This will allow <filename>./checksetup.pl</filename> to set file - permissions on Unix systems so that nothing is world-writable. - </para> - </note> - - </section> - - <section id="security-os-chroot"> - <title>The <filename>chroot</filename> Jail</title> - - <para> - If your system supports it, you may wish to consider running - Bugzilla inside of a <filename>chroot</filename> jail. This option - provides unprecedented security by restricting anything running - inside the jail from accessing any information outside of it. If you - wish to use this option, please consult the documentation that came - with your system. - </para> - - </section> - - </section> - - - - <section id="security-mysql"> - <title>MySQL</title> - - <section id="security-mysql-account"> - <title>The MySQL System Account</title> - - <para>As mentioned in <xref linkend="security-os-accounts"/>, the MySQL - daemon should run as a non-privileged, unique user. Be sure to consult - the MySQL documentation or the documentation that came with your system - for instructions. - </para> - </section> - - <section id="security-mysql-root"> - <title>The MySQL <quote>root</quote> and <quote>anonymous</quote> Users</title> - - <para>By default, MySQL comes with a <quote>root</quote> user with a - blank password and an <quote>anonymous</quote> user, also with a blank - password. In order to protect your data, the <quote>root</quote> user - should be given a password and the anonymous user should be disabled. - </para> - - <example id="security-mysql-account-root"> - <title>Assigning the MySQL <quote>root</quote> User a Password</title> - - <screen> -<prompt>bash$</prompt> mysql mysql -<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root'; -<prompt>mysql></prompt> FLUSH PRIVILEGES; - </screen> - </example> - - <example id="security-mysql-account-anonymous"> - <title>Disabling the MySQL <quote>anonymous</quote> User</title> - <screen> -<prompt>bash$</prompt> mysql -u root -p mysql <co id="security-mysql-account-anonymous-mysql"/> -<prompt>Enter Password:</prompt> <replaceable>new_password</replaceable> -<prompt>mysql></prompt> DELETE FROM user WHERE user = ''; -<prompt>mysql></prompt> FLUSH PRIVILEGES; - </screen> - <calloutlist> - <callout arearefs="security-mysql-account-anonymous-mysql"> - <para>This command assumes that you have already completed - <xref linkend="security-mysql-account-root"/>. - </para> - </callout> - </calloutlist> - </example> - - </section> - - <section id="security-mysql-network"> - <title>Network Access</title> - - <para>If MySQL and your web server both run on the same machine and you - have no other reason to access MySQL remotely, then you should disable - the network access. This, along with the suggestion in - <xref linkend="security-os-ports"/>, will help protect your system from - any remote vulnerabilities in MySQL. - </para> - - <example id="security-mysql-network-ex"> - <title>Disabling Networking in MySQL</title> - - <para>Simply enter the following in <filename>/etc/my.cnf</filename>: - <screen> -[mysqld] -# Prevent network access to MySQL. -skip-networking - </screen> - </para> - </example> - - </section> - - -<!-- For possible addition in the future: How to better control the bugs user - <section id="security-mysql-bugs"> - <title>The bugs User</title> - - </section> ---> - - </section> - - - - <section id="security-webserver"> - <title>Web server</title> - - <section id="security-webserver-access"> - <title>Disabling Remote Access to Bugzilla Configuration Files</title> - - <para> - There are many files that are placed in the Bugzilla directory - area that should not be accessible from the web server. Because of the way - Bugzilla is currently layed out, the list of what should and should not - be accessible is rather complicated. A quick way is to run - <filename>testserver.pl</filename> to check if your web server serves - Bugzilla files as expected. If not, you may want to follow the few - steps below. - </para> - - <tip> - <para>Bugzilla ships with the ability to create - <glossterm linkend="gloss-htaccess"><filename>.htaccess</filename></glossterm> - files that enforce these rules. Instructions for enabling these - directives in Apache can be found in <xref linkend="http-apache"/> - </para> - </tip> - - <itemizedlist spacing="compact"> - <listitem> - <para>In the main Bugzilla directory, you should:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block: - <simplelist type="inline"> - <member><filename>*.pl</filename></member> - <member><filename>*localconfig*</filename></member> - </simplelist> - </para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>In <filename class="directory">data</filename>:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - <listitem> - <para>But allow: - <simplelist type="inline"> - <member><filename>duplicates.rdf</filename></member> - </simplelist> - </para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>In <filename class="directory">data/webdot</filename>:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>If you use a remote webdot server:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - <listitem> - <para>But allow - <simplelist type="inline"> - <member><filename>*.dot</filename></member> - </simplelist> - only for the remote webdot server</para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para>Otherwise, if you use a local GraphViz:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - <listitem> - <para>But allow: - <simplelist type="inline"> - <member><filename>*.png</filename></member> - <member><filename>*.gif</filename></member> - <member><filename>*.jpg</filename></member> - <member><filename>*.map</filename></member> - </simplelist> - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para>And if you don't use any dot:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>In <filename class="directory">Bugzilla</filename>:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>In <filename class="directory">template</filename>:</para> - <itemizedlist spacing="compact"> - <listitem> - <para>Block everything</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - - <para>Be sure to test that data that should not be accessed remotely is - properly blocked. Of particular interest is the localconfig file which - contains your database password. Also, be aware that many editors - create temporary and backup files in the working directory and that - those should also not be accessible. For more information, see - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug 186383</ulink> - or - <ulink url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>. - To test, simply run <filename>testserver.pl</filename>, as said above. - </para> - - <tip> - <para>Be sure to check <xref linkend="http"/> for instructions - specific to the web server you use. - </para> - </tip> - - </section> - - - </section> - - - <section id="security-bugzilla"> - <title>Bugzilla</title> - - <section id="security-bugzilla-charset"> - <title>Prevent users injecting malicious Javascript</title> - - <para>If you installed Bugzilla version 2.22 or later from scratch, - then the <emphasis>utf8</emphasis> parameter is switched on by default. - This makes Bugzilla explicitly set the character encoding, following - <ulink - url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">a - CERT advisory</ulink> recommending exactly this. - The following therefore does not apply to you; just keep - <emphasis>utf8</emphasis> turned on. - </para> - - <para>If you've upgraded from an older version, then it may be possible - for a Bugzilla user to take advantage of character set encoding - ambiguities to inject HTML into Bugzilla comments. - This could include malicious scripts. - This is because due to internationalization concerns, we are unable to - turn the <emphasis>utf8</emphasis> parameter on by default for upgraded - installations. - Turning it on manually will prevent this problem. - </para> - </section> - - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: --> - diff --git a/docs/xml/troubleshooting.xml b/docs/xml/troubleshooting.xml deleted file mode 100644 index c6c185993..000000000 --- a/docs/xml/troubleshooting.xml +++ /dev/null @@ -1,307 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: troubleshooting.xml,v 1.13 2007/07/24 18:22:02 timeless%mozdev.org Exp $ --> - -<appendix id="troubleshooting"> -<title>Troubleshooting</title> - - <para>This section gives solutions to common Bugzilla installation - problems. If none of the section headings seems to match your - problem, read the general advice. - </para> - - <section id="general-advice"> - <title>General Advice</title> - <para>If you can't get <filename>checksetup.pl</filename> 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 - <ulink url="news://news.mozilla.org/mozilla.support.bugzilla">mozilla.support.bugzilla</ulink> - newsgroup. - </para> - - <para>If you have made it all the way through - <xref linkend="installation"/> (Installation) and - <xref linkend="configuration"/> (Configuration) but accessing the Bugzilla - URL doesn't work, the first thing to do is to check your web server error - log. For Apache, this is often located at - <filename>/etc/logs/httpd/error_log</filename>. 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. - </para> - - <para> - Bugzilla can also log all user-based errors (and many code-based errors) - that occur, without polluting the web server's error log. To enable - Bugzilla error logging, create a file that Bugzilla can write to, named - <filename>errorlog</filename>, in the Bugzilla <filename>data</filename> - directory. Errors will be logged as they occur, and will include the type - of the error, the IP address and username (if available) of the user who - triggered the error, and the values of all environment variables; if a - form was being submitted, the data in the form will also be included. - To disable error logging, delete or rename the - <filename>errorlog</filename> file. - </para> - </section> - - <section id="trbl-testserver"> - <title>The Apache web server is not serving Bugzilla pages</title> - <para>After you have run <command>checksetup.pl</command> twice, - run <command>testserver.pl http://yoursite.yourdomain/yoururl</command> - to confirm that your web server is configured properly for - Bugzilla. - </para> - <programlisting> -<prompt>bash$</prompt> ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip -TEST-OK Webserver is running under group id in $webservergroup. -TEST-OK Got ant picture. -TEST-OK Webserver is executing CGIs. -TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig. -</programlisting> - </section> - - <section id="trbl-perlmodule"> - <title>I installed a Perl module, but - <filename>checksetup.pl</filename> claims it's not installed!</title> - - <para>This could be caused by one of two things:</para> - <orderedlist> - <listitem> - <para>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 <filename>checksetup.pl</filename>. This will make sure you - are installing the modules in the right place. - </para> - </listitem> - <listitem> - <para>The permissions on your library directories are set incorrectly. - They must, at the very least, be readable by the web server user or - group. It is recommended that they be world readable. - </para> - </listitem> - </orderedlist> - </section> - - <section id="trbl-dbdSponge"> - <title>DBD::Sponge::db prepare failed</title> - - <para>The following error message may appear due to a bug in DBD::mysql - (over which the Bugzilla team have no control): - </para> - -<programlisting><![CDATA[ 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) -]]></programlisting> - - <para>To fix this, go to - <filename><path-to-perl>/lib/DBD/sponge.pm</filename> - in your Perl installation and replace - </para> - -<programlisting><![CDATA[ my $numFields; - if ($attribs->{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } elsif ($attribs->{'NAME'}) { - $numFields = @{$attribs->{NAME}}; -]]></programlisting> - - <para>with</para> - -<programlisting><![CDATA[ my $numFields; - if ($attribs->{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } elsif ($attribs->{'NAMES'}) { - $numFields = @{$attribs->{NAMES}}; -]]></programlisting> - - <para>(note the S added to NAME.)</para> - </section> - - <section id="paranoid-security"> - <title>cannot chdir(/var/spool/mqueue)</title> - - <para>If you are installing Bugzilla on SuSE Linux, or some other - distributions with <quote>paranoid</quote> security options, it is - possible that the checksetup.pl script may fail with the error: -<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied -]]></programlisting> - </para> - - <para>This is because your <filename>/var/spool/mqueue</filename> - directory has a mode of <computeroutput>drwx------</computeroutput>. - Type <command>chmod 755 <filename>/var/spool/mqueue</filename></command> - as root to fix this problem. This will allow any process running on your - machine the ability to <emphasis>read</emphasis> the - <filename>/var/spool/mqueue</filename> directory. - </para> - </section> - - <section id="trbl-relogin-everyone"> - <title>Everybody is constantly being forced to relogin</title> - - <para>The most-likely cause is that the <quote>cookiepath</quote> parameter - is not set correctly in the Bugzilla configuration. You can change this (if - you're a Bugzilla administrator) from the editparams.cgi page via the web interface. - </para> - - <para>The value of the cookiepath parameter should be the actual directory - containing your Bugzilla installation, <emphasis>as seen by the end-user's - web browser</emphasis>. Leading and trailing slashes are mandatory. You can - also set the cookiepath to any directory which is a parent of the Bugzilla - directory (such as '/', the root directory). But you can't put something - that isn't at least a partial match or it won't work. What you're actually - doing is restricting the end-user's browser to sending the cookies back only - to that directory. - </para> - - <para>How do you know if you want your specific Bugzilla directory or the - whole site? - </para> - - <para>If you have only one Bugzilla running on the server, and you don't - mind having other applications on the same server with it being able to see - the cookies (you might be doing this on purpose if you have other things on - your site that share authentication with Bugzilla), then you'll want to have - the cookiepath set to "/", or to a sufficiently-high enough directory that - all of the involved apps can see the cookies. - </para> - - <example id="trbl-relogin-everyone-share"> - <title>Examples of urlbase/cookiepath pairs for sharing login cookies</title> - - <blockquote> - <literallayout> - urlbase is <ulink url="http://bugzilla.mozilla.org/"/> - cookiepath is / - - urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/> - but you have http://tools.mysite.tld/someotherapp/ which shares - authentication with your Bugzilla - cookiepath is / - </literallayout> - </blockquote> - </example> - - <para>On the other hand, if you have more than one Bugzilla running on the - server (some people do - we do on landfill) then you need to have the - cookiepath restricted enough so that the different Bugzillas don't - confuse their cookies with one another. - </para> - - - <example id="trbl-relogin-everyone-restrict"> - <title>Examples of urlbase/cookiepath pairs to restrict the login cookie</title> - <blockquote> - <literallayout> - urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/> - cookiepath is /bugzilla-tip/ - - urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/> - cookiepath is /bugzilla-2.16-branch/ - </literallayout> - </blockquote> - </example> - - <para>If you had cookiepath set to <quote>/</quote> at any point in the - past and need to set it to something more restrictive - (i.e. <quote>/bugzilla/</quote>), you can safely do this without - requiring users to delete their Bugzilla-related cookies in their - browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5). - </para> - </section> - - <section id="trbl-relogin-some"> - <title>Some users are constantly being forced to relogin</title> - - <para>First, make sure cookies are enabled in the user's browser. - </para> - - <para>If that doesn't fix the problem, it may be that the user's ISP - implements a rotating proxy server. This causes the user's effective IP - address (the address which the Bugzilla server perceives him coming from) - to change periodically. Since Bugzilla cookies are tied to a specific IP - address, each time the effective address changes, the user will have to - log in again. - </para> - - <para>If you are using 2.18 (or later), there is a - parameter called <quote>loginnetmask</quote>, which you can use to set - the number of bits of the user's IP address to require to be matched when - authenticating the cookies. If you set this to something less than 32, - then the user will be given a checkbox for <quote>Restrict this login to - my IP address</quote> on the login screen, which defaults to checked. If - they leave the box checked, Bugzilla will behave the same as it did - before, requiring an exact match on their IP address to remain logged in. - If they uncheck the box, then only the left side of their IP address (up - to the number of bits you specified in the parameter) has to match to - remain logged in. - </para> - - </section> - - <section id="trbl-index"> - <title><filename>index.cgi</filename> doesn't show up unless specified in the URL</title> - <para> - You probably need to set up your web server in such a way that it - will serve the index.cgi page as an index page. - </para> - <para> - If you are using Apache, you can do this by adding - <filename>index.cgi</filename> to the end of the - <computeroutput>DirectoryIndex</computeroutput> line - as mentioned in <xref linkend="http-apache"/>. - </para> - - </section> - - <section id="trbl-passwd-encryption"> - <title> - checksetup.pl reports "Client does not support authentication protocol - requested by server..." - </title> - - <para> - This error is occurring because you are using the new password - encryption that comes with MySQL 4.1, while your - <filename>DBD::mysql</filename> module was compiled against an - older version of MySQL. If you recompile <filename>DBD::mysql</filename> - against the current MySQL libraries (or just obtain a newer version - of this module) then the error may go away. - </para> - - <para> - If that does not fix the problem, or if you cannot recompile the - existing module (e.g. you're running Windows) and/or don't want to - replace it (e.g. you want to keep using a packaged version), then a - workaround is available from the MySQL docs: - <ulink url="http://dev.mysql.com/doc/mysql/en/Old_client.html"/> - </para> - - </section> - -</appendix> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: --> - - diff --git a/docs/xml/using.xml b/docs/xml/using.xml deleted file mode 100644 index 101a9d131..000000000 --- a/docs/xml/using.xml +++ /dev/null @@ -1,1957 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> - -<chapter id="using"> - <title>Using Bugzilla</title> - - <section id="using-intro"> - <title>Introduction</title> - <para>This section contains information for end-users of Bugzilla. There - is a Bugzilla test installation, called - <ulink url="http://landfill.bugzilla.org/">Landfill</ulink>, which you are - welcome to play with (if it's up). However, not all of the Bugzilla - installations there will necessarily have all Bugzilla features enabled, - and different installations run different versions, so some things may not - quite work as this document describes.</para> - - <para> - Frequently Asked Questions (FAQ) are available and answered on - <ulink url="http://wiki.mozilla.org/Bugzilla:FAQ">wiki.mozilla.org</ulink>. - They may cover some questions you have which are left unanswered. - </para> - </section> - - <section id="myaccount"> - <title>Create a Bugzilla Account</title> - - <para>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: - <ulink url="&landfillbase;"/>. - </para> - - <orderedlist> - <listitem> - <para> - On the home page <filename>index.cgi</filename>, click the - <quote>Open a new Bugzilla account</quote> link, or the - <quote>New Account</quote> link available in the footer of pages. - Now enter your email address, then click the <quote>Send</quote> - button. - </para> - - <note> - <para> - If none of these links is available, this means that the - administrator of the installation has disabled self-registration. - This means that only an administrator can create accounts - for other users. One reason could be that this installation is - private. - </para> - </note> - - <note> - <para> - Also, if only some users are allowed to create an account on - the installation, you may see these links but your registration - may fail if your email address doesn't match the ones accepted - by the installation. This is another way to restrict who can - access and edit bugs in this installation. - </para> - </note> - </listitem> - - <listitem> - <para> - Within moments, and if your registration is accepted, you should - receive an email to the address you provided, which contains your - login name (generally the same as the email address), and two URLs - with a token (a random string generated by the installation) to - confirm, respectively cancel, your registration. This is a way to - prevent users from abusing the generation of user accounts, for - instance by entering inexistent email addresses, or email addresses - which do not belong to them. - </para> - </listitem> - - <listitem> - <para> - By default, you have 3 days to confirm your registration. Past this - timeframe, the token is invalidated and the registration is - automatically canceled. You can also cancel this registration sooner - by using the appropriate URL in the email you got. - </para> - </listitem> - - <listitem> - <para> - If you confirm your registration, Bugzilla will ask you your real name - (optional, but recommended) and your password, which must be between - 3 and 16 characters long. - </para> - </listitem> - - <listitem> - <para> - Now all you need to do is to click the <quote>Log In</quote> - link in the footer at the bottom of the page in your browser, - enter your email address and password you just chose into the - login form, and click the <quote>Log in</quote> button. - </para> - </listitem> - </orderedlist> - - <para> - 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 during your session. - </para> - </section> - - <section id="bug_page"> - <title>Anatomy of a Bug</title> - - <para>The core of Bugzilla is the screen which displays a particular - bug. It's a good place to explain some Bugzilla concepts. - <ulink - url="&landfillbase;show_bug.cgi?id=1"> - Bug 1 on Landfill</ulink> - - 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.</para> - - <orderedlist> - <listitem> - <para> - <emphasis>Product and Component</emphasis>: - 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: - <simplelist> - <member> - <emphasis>Administration:</emphasis> - Administration of a Bugzilla installation.</member> - - <member> - <emphasis>Bugzilla-General:</emphasis> - Anything that doesn't fit in the other components, or spans - multiple components.</member> - - <member> - <emphasis>Creating/Changing Bugs:</emphasis> - Creating, changing, and viewing bugs.</member> - - <member> - <emphasis>Documentation:</emphasis> - The Bugzilla documentation, including The Bugzilla Guide.</member> - - <member> - <emphasis>Email:</emphasis> - Anything to do with email sent by Bugzilla.</member> - - <member> - <emphasis>Installation:</emphasis> - The installation process of Bugzilla.</member> - - <member> - <emphasis>Query/Buglist:</emphasis> - Anything to do with searching for bugs and viewing the - buglists.</member> - - <member> - <emphasis>Reporting/Charting:</emphasis> - Getting reports from Bugzilla.</member> - - <member> - <emphasis>User Accounts:</emphasis> - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc.</member> - - <member> - <emphasis>User Interface:</emphasis> - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc.</member> - </simplelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Status and Resolution:</emphasis> - - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>Assigned To:</emphasis> - The person responsible for fixing the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*QA Contact:</emphasis> - The person responsible for quality assurance on this bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*URL:</emphasis> - A URL associated with the bug, if any.</para> - </listitem> - - <listitem> - <para> - <emphasis>Summary:</emphasis> - A one-sentence summary of the problem.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Status Whiteboard:</emphasis> - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Keywords:</emphasis> - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>Platform and OS:</emphasis> - These indicate the computing environment where the bug was - found.</para> - </listitem> - - <listitem> - <para> - <emphasis>Version:</emphasis> - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>Priority:</emphasis> - The bug assignee uses this field to prioritize his or her bugs. - It's a good idea not to change this on other people's bugs.</para> - </listitem> - - <listitem> - <para> - <emphasis>Severity:</emphasis> - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Target:</emphasis> - (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.</para> - </listitem> - - <listitem> - <para> - <emphasis>Reporter:</emphasis> - The person who filed the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>CC list:</emphasis> - A list of people who get mail when the bug changes.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Time Tracking:</emphasis> - This form can be used for time tracking. - To use this feature, you have to be blessed group membership - specified by the <quote>timetrackinggroup</quote> parameter. - <simplelist> - <member> - <emphasis>Orig. Est.:</emphasis> - This field shows the original estimated time.</member> - - <member> - <emphasis>Current Est.:</emphasis> - This field shows the current estimated time. - This number is calculated from <quote>Hours Worked</quote> - and <quote>Hours Left</quote>.</member> - - <member> - <emphasis>Hours Worked:</emphasis> - This field shows the number of hours worked.</member> - - <member> - <emphasis>Hours Left:</emphasis> - This field shows the <quote>Current Est.</quote> - - <quote>Hours Worked</quote>. - This value + <quote>Hours Worked</quote> will become the - new Current Est.</member> - - <member> - <emphasis>%Complete:</emphasis> - This field shows what percentage of the task is complete.</member> - - <member> - <emphasis>Gain:</emphasis> - This field shows the number of hours that the bug is ahead of the - <quote>Orig. Est.</quote>.</member> - - <member> - <emphasis>Deadline:</emphasis> - This field shows the deadline for this bug.</member> - </simplelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Attachments:</emphasis> - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. Attachments are - normally stored in the Bugzilla database, unless they are marked as - Big Files, which are stored directly on disk. - </para> - </listitem> - - <listitem> - <para> - <emphasis>*Dependencies:</emphasis> - 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.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Votes:</emphasis> - Whether this bug has any votes.</para> - </listitem> - - <listitem> - <para> - <emphasis>Additional Comments:</emphasis> - You can add your two cents to the bug discussion here, if you have - something worthwhile to say.</para> - </listitem> - </orderedlist> - </section> - - <section id="lifecycle"> - <title>Life Cycle of a Bug</title> - - <para> - The life cycle, also known as work flow, of a bug is currently hardcoded - into Bugzilla. <xref linkend="lifecycle-image"/> contains a graphical - representation of this life cycle. If you wish to customize this image for - your site, the <ulink url="../images/bzLifecycle.xml">diagram file</ulink> - is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink> - native XML format. - </para> - - <figure id="lifecycle-image"> - <title>Lifecycle of a Bugzilla Bug</title> - <mediaobject> - <imageobject> - <imagedata fileref="../images/bzLifecycle.png" scale="66" /> - </imageobject> - </mediaobject> - </figure> - </section> - - <section id="query"> - <title>Searching for Bugs</title> - - <para>The Bugzilla Search page is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - <ulink url="&landfillbase;query.cgi"/>.</para> - - <para>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.</para> - - <para> - After a search is run, you can save it as a Saved Search, which - will appear in the page footer. If you are in the group defined - by the "querysharegroup" parameter, you may share your queries - with other users, see <xref linkend="savedsearches"/> for more details. - </para> - - <section id="boolean"> - <title>Boolean Charts</title> - <para> - Highly advanced querying is done using Boolean Charts. - </para> - <para> - The boolean charts further restrict the set of results - returned by a query. It is possible to search for bugs - based on elaborate combinations of criteria. - </para> - <para> - The simplest boolean searches have only one term. These searches - permit the selected left <emphasis>field</emphasis> - to be compared using a - selectable <emphasis>operator</emphasis> to a - specified <emphasis>value.</emphasis> - Using the "And," "Or," and "Add Another Boolean Chart" buttons, - additional terms can be included in the query, further - altering the list of bugs returned by the query. - </para> - <para> - There are three fields in each row of a boolean search. - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>Field:</emphasis> - the items being searched - </para> - </listitem> - <listitem> - <para> - <emphasis>Operator:</emphasis> - the comparison operator - </para> - </listitem> - <listitem> - <para> - <emphasis>Value:</emphasis> - the value to which the field is being compared - </para> - </listitem> - </itemizedlist> - <section id="pronouns"> - <title>Pronoun Substitution</title> - <para> - Sometimes, a query needs to compare a user-related field - (such as ReportedBy) with a role-specific user (such as the - user running the query or the user to whom each bug is assigned). - When the operator is either "equals" or "notequals", the value - can be "%reporter%", "%assignee%", "%qacontact%", or "%user%". - The user pronoun - refers to the user who is executing the query or, in the case - of whining reports, the user who will be the recipient - of the report. The reporter, assignee, and qacontact - pronouns refer to the corresponding fields in the bug. - </para> - <para> - Boolean charts also let you type a group name in any user-related - field if the operator is either "equals", "notequals" or "anyexact". - This will let you query for any member belonging (or not) to the - specified group. The group name must be entered following the - "%group.foo%" syntax, where "foo" is the group name. - So if you are looking for bugs reported by any user being in the - "editbugs" group, then you can type "%group.editbugs%". - </para> - </section> - <section id="negation"> - <title>Negation</title> - <para> - At first glance, negation seems redundant. Rather than - searching for - <blockquote> - <para> - NOT("summary" "contains the string" "foo"), - </para> - </blockquote> - one could search for - <blockquote> - <para> - ("summary" "does not contain the string" "foo"). - </para> - </blockquote> - However, the search - <blockquote> - <para> - ("CC" "does not contain the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where anyone on the CC list did not contain - "@mozilla.org" while - <blockquote> - <para> - NOT("CC" "contains the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where there was nobody on the CC list who - did contain the string. Similarly, the use of negation also permits - complex expressions to be built using terms OR'd together and then - negated. Negation permits queries such as - <blockquote> - <para> - NOT(("product" "equals" "update") OR - ("component" "equals" "Documentation")) - </para> - </blockquote> - to find bugs that are neither - in the update product or in the documentation component or - <blockquote> - <para> - NOT(("commenter" "equals" "%assignee%") OR - ("component" "equals" "Documentation")) - </para> - </blockquote> - to find non-documentation - bugs on which the assignee has never commented. - </para> - </section> - <section id="multiplecharts"> - <title>Multiple Charts</title> - <para> - The terms within a single row of a boolean chart are all - constraints on a single piece of data. If you are looking for - a bug that has two different people cc'd on it, then you need - to use two boolean charts. A search for - <blockquote> - <para> - ("cc" "contains the string" "foo@") AND - ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - would return only bugs with "foo@mozilla.org" on the cc list. - If you wanted bugs where there is someone on the cc list - containing "foo@" and someone else containing "@mozilla.org", - then you would need two boolean charts. - <blockquote> - <para> - First chart: ("cc" "contains the string" "foo@") - </para> - <para> - Second chart: ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - The bugs listed will be only the bugs where ALL the charts are true. - </para> - </section> - </section> - - <section id="quicksearch"> - <title>Quicksearch</title> - - <para> - Quicksearch is a single-text-box query tool which uses - metacharacters to indicate what is to be searched. For example, typing - "<literal>foo|bar</literal>" - into Quicksearch would search for "foo" or "bar" in the - summary and status whiteboard of a bug; adding - "<literal>:BazProduct</literal>" would - search only in that product. - You can use it to find a bug by its number or its alias, too. - </para> - - <para> - You'll find the Quicksearch box in Bugzilla's footer area. - On Bugzilla's front page, there is an additional - <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink> - link which details how to use it. - </para> - </section> - <section id="casesensitivity"> - <title>Case Sensitivity in Searches</title> - <para> - Bugzilla queries are case-insensitive and accent-insensitive, when - used with either MySQL or Oracle databases. When using Bugzilla with - PostgreSQL, however, some queries are case-sensitive. This is due to - the way PostgreSQL handles case and accent sensitivity. - </para> - </section> - <section id="list"> - <title>Bug Lists</title> - - <para>If you run a search, a list of matching bugs will be returned. - </para> - - <para>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: - <simplelist> - <member> - <emphasis>Long Format:</emphasis> - - this gives you a large page with a non-editable summary of the fields - of each bug.</member> - - <member> - <emphasis>XML:</emphasis> - - get the buglist in the XML format.</member> - - <member> - <emphasis>CSV:</emphasis> - - get the buglist as comma-separated values, for import into e.g. - a spreadsheet.</member> - - <member> - <emphasis>Feed:</emphasis> - - get the buglist as an Atom feed. Copy this link into your - favorite feed reader. If you are using Firefox, you can also - save the list as a live bookmark by clicking the live bookmark - icon in the status bar. To limit the number of bugs in the feed, - add a limit=n parameter to the URL.</member> - - <member> - <emphasis>iCalendar:</emphasis> - - Get the buglist as an iCalendar file. Each bug is represented as a - to-do item in the imported calendar.</member> - - <member> - <emphasis>Change Columns:</emphasis> - - change the bug attributes which appear in the list.</member> - - <member> - <emphasis>Change several bugs at once:</emphasis> - - If your account is sufficiently empowered, and more than one bug - appear in the bug list, this link is displayed which lets you make - the same change to all the bugs in the list - for example, changing - their assignee.</member> - - <member> - <emphasis>Send mail to bug assignees:</emphasis> - - If more than one bug appear in the bug list and there are at least - two distinct bug assignees, this links is displayed which lets you - easily send a mail to the assignees of all bugs on the list.</member> - - <member> - <emphasis>Edit Search:</emphasis> - - 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.</member> - - <member> - <emphasis>Remember Search As:</emphasis> - - 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. - </member> - </simplelist> - </para> - - <para> - If you would like to access the bug list from another program - it is often useful to have the list returned in something other - than HTML. By adding the ctype=type parameter into the bug list URL - you can specify several alternate formats. Besides the types described - above, the following formats are also supported: ECMAScript, also known - as JavaScript (ctype=js), and Resource Description Framework RDF/XML - (ctype=rdf). - </para> - </section> - - <section id="individual-buglists"> - <title>Adding/removing tags to/from bugs</title> - <para> - You can add and remove tags from individual bugs, which let you find and - manage them more easily. Creating a new tag automatically generates a saved - search - whose name is the name of the tag - which lists bugs with this tag. - This saved search will be displayed in the footer of pages by default, as - all other saved searches. The main difference between tags and normal saved - searches is that saved searches, as described in the previous section, are - stored in the form of a list of matching criteria, while the saved search - generated by tags is a list of bug numbers. Consequently, you can easily - edit this list by either adding or removing tags from bugs. To enable this - feature, you have to turn on the <quote>Enable tags for bugs</quote> user - preference, see <xref linkend="userpreferences" />. This feature is disabled - by default. - </para> - - <para> - This feature is useful when you want to keep track of several bugs, but - for different reasons. Instead of adding yourself to the CC list of all - these bugs and mixing all these reasons, you can now store these bugs in - separate lists, e.g. <quote>Keep in mind</quote>, <quote>Interesting bugs</quote>, - or <quote>Triage</quote>. One big advantage of this way to manage bugs - is that you can easily add or remove bugs one by one, which is not - possible to do with saved searches without having to edit the search - criteria again. - </para> - </section> - </section> - - <section id="bugreports"> - <title>Filing Bugs</title> - - <section id="fillingbugs"> - <title>Reporting a New Bug</title> - - <para>Years of bug writing experience has been distilled for your - reading pleasure into the - <ulink - url="&landfillbase;page.cgi?id=bug-writing.html"> - Bug Writing Guidelines</ulink>. - 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.</para> - - <para>The procedure for filing a bug is as follows:</para> - - <orderedlist> - <listitem> - <para> - Click the <quote>New</quote> link available in the footer - of pages, or the <quote>Enter a new bug report</quote> link - displayed on the home page of the Bugzilla installation. - </para> - - <note> - <para> - If you want to file a test bug to see how Bugzilla works, - you can do it on one of our test installations on - <ulink url="&landfillbase;">Landfill</ulink>. - </para> - </note> - </listitem> - - <listitem> - <para> - You first have to select the product in which you found a bug. - </para> - </listitem> - - <listitem> - <para> - You now see a form where you can specify the component (part of - the product which is affected by the bug you discovered; if you have - no idea, just select <quote>General</quote> if such a component exists), - the version of the program you were using, the Operating System and - platform your program is running on and the severity of the bug (if the - bug you found crashes the program, it's probably a major or a critical - bug; if it's a typo somewhere, that's something pretty minor; if it's - something you would like to see implemented, then that's an enhancement). - </para> - </listitem> - - <listitem> - <para> - You now have to give a short but descriptive summary of the bug you found. - <quote>My program is crashing all the time</quote> is a very poor summary - and doesn't help developers at all. Try something more meaningful or - your bug will probably be ignored due to a lack of precision. - The next step is to give a very detailed list of steps to reproduce - the problem you encountered. Try to limit these steps to a minimum set - required to reproduce the problem. This will make the life of - developers easier, and the probability that they consider your bug in - a reasonable timeframe will be much higher. - </para> - - <note> - <para> - Try to make sure that everything in the summary is also in the first - comment. Summaries are often updated and this will ensure your original - information is easily accessible. - </para> - </note> - </listitem> - - <listitem> - <para> - As you file the bug, you can also attach a document (testcase, patch, - or screenshot of the problem). - </para> - </listitem> - - <listitem> - <para> - Depending on the Bugzilla installation you are using and the product in - which you are filing the bug, you can also request developers to consider - your bug in different ways (such as requesting review for the patch you - just attached, requesting your bug to block the next release of the - product, and many other product specific requests). - </para> - </listitem> - - <listitem> - <para> - Now is a good time to read your bug report again. Remove all misspellings, - otherwise your bug may not be found by developers running queries for some - specific words, and so your bug would not get any attention. - Also make sure you didn't forget any important information developers - should know in order to reproduce the problem, and make sure your - description of the problem is explicit and clear enough. - When you think your bug report is ready to go, the last step is to - click the <quote>Commit</quote> button to add your report into the database. - </para> - </listitem> - </orderedlist> - - <para> - 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. - </para> - - <para>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. - </para> - </section> - - <section id="cloningbugs"> - <title>Clone an Existing Bug</title> - - <para> - Starting with version 2.20, Bugzilla has a feature that allows you - to clone an existing bug. The newly created bug will inherit - most settings from the old bug. This allows you to track more - easily similar concerns in a new bug. To use this, go to the bug - that you want to clone, then click the <quote>Clone This Bug</quote> - link on the bug page. This will take you to the <quote>Enter Bug</quote> - page that is filled with the values that the old bug has. - You can change those values and/or texts if needed. - </para> - </section> - - </section> - - <section id="attachments"> - <title>Attachments</title> - - <para> - You should 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. - </para> - - <para>You should make sure to trim screenshots. There's no need to show the - whole screen if you are pointing out a single-pixel problem. - </para> - - <para>Bugzilla stores and uses a Content-Type for each attachment - (e.g. text/html). To download an attachment as a different - Content-Type (e.g. application/xhtml+xml), you can override this - using a 'content_type' parameter on the URL, e.g. - <filename>&content_type=text/plain</filename>. - </para> - - <para> - If you have a really large attachment, something that does not need to - be recorded forever (as most attachments are), or something that is too - big for your database, you can mark your attachment as a - <quote>Big File</quote>, assuming the administrator of the installation - has enabled this feature. Big Files are stored directly on disk instead - of in the database. The maximum size of a <quote>Big File</quote> is - normally larger than the maximum size of a regular attachment. Independently - of the storage system used, an administrator can delete these attachments - at any time. Nevertheless, if these files are stored in the database, the - <quote>allow_attachment_deletion</quote> parameter (which is turned off - by default) must be enabled in order to delete them. - </para> - - <para> - Also, if the administrator turned on the <quote>allow_attach_url</quote> - parameter, you can enter the URL pointing to the attachment instead of - uploading the attachment itself. For example, this is useful if you want to - point to an external application, a website or a very large file. Note that - there is no guarantee that the source file will always be available, nor - that its content will remain unchanged. - </para> - - <section id="patchviewer"> - <title>Patch Viewer</title> - - <para>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.</para> - - <para>Patch viewer allows you to:</para> - - <simplelist> - <member>View patches in color, with side-by-side view rather than trying - to interpret the contents of the patch.</member> - <member>See the difference between two patches.</member> - <member>Get more context in a patch.</member> - <member>Collapse and expand sections of a patch for easy - reading.</member> - <member>Link to a particular section of a patch for discussion or - review</member> - <member>Go to Bonsai or LXR to see more context, blame, and - cross-references for the part of the patch you are looking at</member> - <member>Create a rawtext unified format diff out of any patch, no - matter what format it came from</member> - </simplelist> - - <section id="patchviewer_view"> - <title>Viewing Patches in Patch Viewer</title> - <para>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.</para> - </section> - - <section id="patchviewer_diff"> - <title>Seeing the Difference Between Two Patches</title> - <para>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.</para> - </section> - - <section id="patchviewer_context"> - <title>Getting More Context in a Patch</title> - <para>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".</para> - </section> - - <section id="patchviewer_collapse"> - <title>Collapsing and Expanding Sections of a Patch</title> - <para>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.</para> - </section> - - <section id="patchviewer_link"> - <title>Linking to a Section of a Patch</title> - <para>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.</para> - </section> - - <section id="patchviewer_bonsai_lxr"> - <title>Going to Bonsai and LXR</title> - <para>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.</para> - - <para>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).</para> - </section> - - <section id="patchviewer_unified_diff"> - <title>Creating a Unified Diff</title> - <para>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.</para> - </section> - </section> - </section> - - <section id="hintsandtips"> - <title>Hints and Tips</title> - - <para>This section distills some Bugzilla tips and best practices - that have been developed.</para> - - <section> - <title>Autolinkification</title> - <para>Bugzilla comments are plain text - so typing <U> 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: - <ulink url="http://www.bugzilla.org"/>. - Other strings which get linkified in the obvious manner are: - <simplelist> - <member>bug 12345</member> - <member>comment 7</member> - <member>bug 23456, comment 53</member> - <member>attachment 4321</member> - <member>mailto:george@example.com</member> - <member>george@example.com</member> - <member>ftp://ftp.mozilla.org</member> - <member>Most other sorts of URL</member> - </simplelist> - </para> - - <para>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. - </para> - </section> - - <section id="commenting"> - <title>Comments</title> - - <para>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. - </para> - - <para> - 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. - </para> - </section> - - <section id="comment-wrapping"> - <title>Server-Side Comment Wrapping</title> - <para> - Bugzilla stores comments unwrapped and wraps them at display time. This - ensures proper wrapping in all browsers. Lines beginning with the ">" - character are assumed to be quotes, and are not wrapped. - </para> - </section> - - <section id="dependencytree"> - <title>Dependency Tree</title> - - <para> - On the <quote>Dependency tree</quote> page linked from each bug - page, you can see the dependency relationship from the bug as a - tree structure. - </para> - - <para> - You can change how much depth to show, and you can hide resolved bugs - from this page. You can also collaps/expand dependencies for - each bug on the tree view, using the [-]/[+] buttons that appear - before its summary. This option is not available for terminal - bugs in the tree (that don't have further dependencies). - </para> - </section> - </section> - - <section id="timetracking"> - <title>Time Tracking Information</title> - - <para> - Users who belong to the group specified by the <quote>timetrackinggroup</quote> - parameter have access to time-related fields. Developers can see - deadlines and estimated times to fix bugs, and can provide time spent - on these bugs. - </para> - - <para> - At any time, a summary of the time spent by developers on bugs is - accessible either from bug lists when clicking the <quote>Time Summary</quote> - button or from individual bugs when clicking the <quote>Summarize time</quote> - link in the time tracking table. The <filename>summarize_time.cgi</filename> - page lets you view this information either per developer or per bug, - and can be split on a month basis to have greater details on how time - is spent by developers. - </para> - - <para> - As soon as a bug is marked as RESOLVED, the remaining time expected - to fix the bug is set to zero. This lets QA people set it again for - their own usage, and it will be set to zero again when the bug will - be marked as CLOSED. - </para> - </section> - - <section id="userpreferences"> - <title>User Preferences</title> - - <para> - Once logged in, you can customize various aspects of - Bugzilla via the "Preferences" link in the page footer. - The preferences are split into five tabs:</para> - - <section id="generalpreferences" xreflabel="General Preferences"> - <title>General Preferences</title> - - <para> - This tab allows you to change several default settings of Bugzilla. - </para> - - <itemizedlist spacing="compact"> - <listitem> - <para> - Bugzilla's general appearance (skin) - select which skin to use. - Bugzilla supports adding custom skins. - </para> - </listitem> - <listitem> - <para> - Quote the associated comment when you click on its reply link - sets - the behavior of the comment "Reply" link. Options include quoting the - full comment, just reference the comment number, or turn the link off. - </para> - </listitem> - <listitem> - <para> - Language used in email - select which language email will be sent in, - from the list of available languages. - </para> - </listitem> - <listitem> - <para> - After changing a bug - This controls what page is displayed after - changes to a bug are submitted. The options include to show the bug - just modified, to show the next bug in your list, or to do nothing. - </para> - </listitem> - <listitem> - <para> - Enable tags for bugs - turn bug tagging on or off. - </para> - </listitem> - <listitem> - <para> - Zoom textareas large when in use (requires JavaScript) - enable or - disable the automatic expanding of text areas when text is being - entered into them. - </para> - </listitem> - <listitem> - <para> - Field separator character for CSV files - - Select between a comma and semi-colon for exported CSV bug lists. - </para> - </listitem> - <listitem> - <para> - Automatically add me to the CC list of bugs I change - set default - behavior of CC list. Options include "Always", "Never", and "Only - if I have no role on them". - </para> - </listitem> - <listitem> - <para> - When viewing a bug, show comments in this order - - controls the order of comments. Options include "Oldest - to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the - bug description at the top". - </para> - </listitem> - <listitem> - <para> - Show a quip at the top of each bug list - controls - whether a quip will be shown on the Bug list page. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="emailpreferences"> - <title>Email Preferences</title> - - <para> - This tab allows you to enable or disable email notification on - specific events. - </para> - - <para> - In general, users have almost complete control over how much (or - how little) email Bugzilla sends them. If you want to receive the - maximum amount of email possible, click the <quote>Enable All - Mail</quote> button. If you don't want to receive any email from - Bugzilla at all, click the <quote>Disable All Mail</quote> button. - </para> - - <note> - <para> - A Bugzilla administrator can stop a user from receiving - bugmail by clicking the <quote>Bugmail Disabled</quote> checkbox - when editing the user account. This is a drastic step - best taken only for disabled accounts, as it overrides - the user's individual mail preferences. - </para> - </note> - - <para> - There are two global options -- <quote>Email me when someone - asks me to set a flag</quote> and <quote>Email me when someone - sets a flag I asked for</quote>. These define how you want to - receive bugmail with regards to flags. Their use is quite - straightforward; enable the checkboxes if you want Bugzilla to - send you mail under either of the above conditions. - </para> - - <para> - If you'd like to set your bugmail to something besides - 'Completely ON' and 'Completely OFF', the - <quote>Field/recipient specific options</quote> table - allows you to do just that. The rows of the table - define events that can happen to a bug -- things like - attachments being added, new comments being made, the - priority changing, etc. The columns in the table define - your relationship with the bug: - </para> - - <itemizedlist spacing="compact"> - <listitem> - <para> - Reporter - Where you are the person who initially - reported the bug. Your name/account appears in the - <quote>Reporter:</quote> field. - </para> - </listitem> - <listitem> - <para> - Assignee - Where you are the person who has been - designated as the one responsible for the bug. Your - name/account appears in the <quote>Assigned To:</quote> - field of the bug. - </para> - </listitem> - <listitem> - <para> - QA Contact - You are one of the designated - QA Contacts for the bug. Your account appears in the - <quote>QA Contact:</quote> text-box of the bug. - </para> - </listitem> - <listitem> - <para> - CC - You are on the list CC List for the bug. - Your account appears in the <quote>CC:</quote> text box - of the bug. - </para> - </listitem> - <listitem> - <para> - Voter - You have placed one or more votes for the bug. - Your account appears only if someone clicks on the - <quote>Show votes for this bug</quote> link on the bug. - </para> - </listitem> - </itemizedlist> - - <note> - <para> - Some columns may not be visible for your installation, depending - on your site's configuration. - </para> - </note> - - <para> - To fine-tune your bugmail, decide the events for which you want - to receive bugmail; then decide if you want to receive it all - the time (enable the checkbox for every column), or only when - you have a certain relationship with a bug (enable the checkbox - only for those columns). For example: if you didn't want to - receive mail when someone added themselves to the CC list, you - could uncheck all the boxes in the <quote>CC Field Changes</quote> - line. As another example, if you never wanted to receive email - on bugs you reported unless the bug was resolved, you would - un-check all boxes in the <quote>Reporter</quote> column - except for the one on the <quote>The bug is resolved or - verified</quote> row. - </para> - - <note> - <para> - Bugzilla adds the <quote>X-Bugzilla-Reason</quote> header to - all bugmail it sends, describing the recipient's relationship - (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug. - This header can be used to do further client-side filtering. - </para> - </note> - - <para> - Bugzilla has a feature called <quote>Users Watching</quote>. - When you enter one or more comma-delineated user accounts (usually email - addresses) into the text entry box, you will receive a copy of all the - bugmail those users are sent (security settings permitting). - This powerful functionality enables seamless transitions as developers - change projects or users go on holiday. - </para> - - <note> - <para> - The ability to watch other users may not be available in all - Bugzilla installations. If you don't see this feature, and feel - that you need it, speak to your administrator. - </para> - </note> - - <para> - Each user listed in the <quote>Users watching you</quote> field - has you listed in their <quote>Users to watch</quote> list - and can get bugmail according to your relationship to the bug and - their <quote>Field/recipient specific options</quote> setting. - </para> - - </section> - - <section id="savedsearches" xreflabel="Saved Searches"> - <title>Saved Searches</title> - <para> - On this tab you can view and run any Saved Searches that you have - created, and also any Saved Searches that other members of the group - defined in the "querysharegroup" parameter have shared. - Saved Searches can be added to the page footer from this screen. - If somebody is sharing a Search with a group she or he is allowed to - <link linkend="groups">assign users to</link>, the sharer may opt to have - the Search show up in the footer of the group's direct members by default. - </para> - </section> - - <section id="accountpreferences" xreflabel="Name and Password"> - <title>Name and Password</title> - - <para>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 - <emphasis>current</emphasis> password into the <quote>Password</quote> - 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.</para> - </section> - - <section id="permissionsettings"> - <title>Permissions</title> - - <para> - This is a purely informative page which outlines your current - permissions on this installation of Bugzilla. - </para> - - <para> - A complete list of permissions is below. Only users with - <emphasis>editusers</emphasis> privileges can change the permissions - of other users. - </para> - - <variablelist> - <varlistentry> - <term> - admin - </term> - <listitem> - <para> - Indicates user is an Administrator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhineatothers - </term> - <listitem> - <para> - Indicates user can configure whine reports for other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhines - </term> - <listitem> - <para> - Indicates user can configure whine reports for self. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudoers - </term> - <listitem> - <para> - Indicates user can perform actions as other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudo_protect - </term> - <listitem> - <para> - Indicates user can not be impersonated by other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - canconfirm - </term> - <listitem> - <para> - Indicates user can confirm a bug or mark it a duplicate. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - creategroups - </term> - <listitem> - <para> - Indicates user can create and destroy groups. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editbugs - </term> - <listitem> - <para> - Indicates user can edit all bug fields. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editclassifications - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit classifications. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editcomponents - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit components. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editkeywords - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit keywords. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editusers - </term> - <listitem> - <para> - Indicates user can edit or disable users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - tweakparams - </term> - <listitem> - <para> - Indicates user can change Parameters. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <note> - <para> - For more information on how permissions work in Bugzilla (i.e. who can - change what), see <xref linkend="cust-change-permissions"/>. - </para> - </note> - - </section> - </section> - - - <section id="reporting"> - <title>Reports and Charts</title> - - <para>As well as the standard buglist, Bugzilla has two more ways of - viewing sets of bugs. These are the reports (which give different - views of the current state of the database) and charts (which plot - the changes in particular sets of bugs over time.)</para> - - <section id="reports"> - <title>Reports</title> - - <para> - A report is a view of the current state of the bug database. - </para> - - <para> - You can run either an HTML-table-based report, or a graphical - line/pie/bar-chart-based one. The two have different pages to - define them, but are close cousins - once you've defined and - viewed a report, you can switch between any of the different - views of the data at will. - </para> - - <para> - Both report types are based on the idea of defining a set of bugs - using the standard search interface, and then choosing some - aspect of that set to plot on the horizontal and/or vertical axes. - You can also get a form of 3-dimensional report by choosing to have - multiple images or tables. - </para> - - <para> - So, for example, you could use the search form to choose "all - bugs in the WorldControl product", and then plot their severity - against their component to see which component had had the largest - number of bad bugs reported against it. - </para> - - <para> - Once you've defined your parameters and hit "Generate Report", - you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie - is only available if you didn't define a vertical axis, as pie - charts don't have one.) The other controls are fairly self-explanatory; - you can change the size of the image if you find text is overwriting - other text, or the bars are too thin to see. - </para> - - </section> - - <section id="charts"> - <title>Charts</title> - - <para> - A chart is a view of the state of the bug database over time. - </para> - - <para> - Bugzilla currently has two charting systems - Old Charts and New - Charts. Old Charts have been part of Bugzilla for a long time; they - chart each status and resolution for each product, and that's all. - They are deprecated, and going away soon - we won't say any more - about them. - New Charts are the future - they allow you to chart anything you - can define as a search. - </para> - - <note> - <para> - Both charting forms require the administrator to set up the - data-gathering script. If you can't see any charts, ask them whether - they have done so. - </para> - </note> - - <para> - An individual line on a chart is called a data set. - All data sets are organised into categories and subcategories. The - data sets that Bugzilla defines automatically use the Product name - as a Category and Component names as Subcategories, but there is no - need for you to follow that naming scheme with your own charts if - you don't want to. - </para> - - <para> - Data sets may be public or private. Everyone sees public data sets in - the list, but only their creator sees private data sets. Only - administrators can make data sets public. - No two data sets, even two private ones, can have the same set of - category, subcategory and name. So if you are creating private data - sets, one idea is to have the Category be your username. - </para> - - <section> - <title>Creating Charts</title> - - <para> - You create a chart by selecting a number of data sets from the - list, and pressing Add To List for each. In the List Of Data Sets - To Plot, you can define the label that data set will have in the - chart's legend, and also ask Bugzilla to Sum a number of data sets - (e.g. you could Sum data sets representing RESOLVED, VERIFIED and - CLOSED in a particular product to get a data set representing all - the resolved bugs in that product.) - </para> - - <para> - If you've erroneously added a data set to the list, select it - using the checkbox and click Remove. Once you add more than one - data set, a "Grand Total" line - automatically appears at the bottom of the list. If you don't want - this, simply remove it as you would remove any other line. - </para> - - <para> - You may also choose to plot only over a certain date range, and - to cumulate the results - that is, to plot each one using the - previous one as a baseline, so the top line gives a sum of all - the data sets. It's easier to try than to explain :-) - </para> - - <para> - Once a data set is in the list, one can also perform certain - actions on it. For example, one can edit the - data set's parameters (name, frequency etc.) if it's one you - created or if you are an administrator. - </para> - - <para> - Once you are happy, click Chart This List to see the chart. - </para> - - </section> - - <section id="charts-new-series"> - <title>Creating New Data Sets</title> - - <para> - You may also create new data sets of your own. To do this, - click the "create a new data set" link on the Create Chart page. - This takes you to a search-like interface where you can define - the search that Bugzilla will plot. At the bottom of the page, - you choose the category, sub-category and name of your new - data set. - </para> - - <para> - If you have sufficient permissions, you can make the data set public, - and reduce the frequency of data collection to less than the default - seven days. - </para> - </section> - - </section> - - </section> - - <section id="flags"> - <title>Flags</title> - - <para> - A flag is a kind of status that can be set on bugs or attachments - to indicate that the bugs/attachments are in a certain state. - Each installation can define its own set of flags that can be set - on bugs or attachments. - </para> - - <para> - If your installation has defined a flag, you can set or unset that flag, - and if your administrator has enabled requesting of flags, you can submit - a request for another user to set the flag. - </para> - - <para> - To set a flag, select either "+" or "-" from the drop-down menu next to - the name of the flag in the "Flags" list. The meaning of these values are - flag-specific and thus cannot be described in this documentation, - but by way of example, setting a flag named "review" to "+" may indicate - that the bug/attachment has passed review, while setting it to "-" - may indicate that the bug/attachment has failed review. - </para> - - <para> - To unset a flag, click its drop-down menu and select the blank value. - Note that marking an attachment as obsolete automatically cancels all - pending requests for the attachment. - </para> - - <para> - If your administrator has enabled requests for a flag, request a flag - by selecting "?" from the drop-down menu and then entering the username - of the user you want to set the flag in the text field next to the menu. - </para> - - <para> - A set flag appears in bug reports and on "edit attachment" pages with the - abbreviated username of the user who set the flag prepended to the - flag name. For example, if Jack sets a "review" flag to "+", it appears - as Jack: review [ + ] - </para> - - <para> - A requested flag appears with the user who requested the flag prepended - to the flag name and the user who has been requested to set the flag - appended to the flag name within parentheses. For example, if Jack - asks Jill for review, it appears as Jack: review [ ? ] (Jill). - </para> - - <para> - You can browse through open requests made of you and by you by selecting - 'My Requests' from the footer. You can also look at open requests limited - by other requesters, requestees, products, components, and flag names from - this page. Note that you can use '-' for requestee to specify flags with - 'no requestee' set. - </para> - </section> - - <section id="whining"> - <title>Whining</title> - - <para> - Whining is a feature in Bugzilla that can regularly annoy users at - specified times. Using this feature, users can execute saved searches - at specific times (i.e. the 15th of the month at midnight) or at - regular intervals (i.e. every 15 minutes on Sundays). The results of the - searches are sent to the user, either as a single email or as one email - per bug, along with some descriptive text. - </para> - - <warning> - <para> - Throughout this section it will be assumed that all users are members - of the bz_canusewhines group, membership in which is required in order - to use the Whining system. You can easily make all users members of - the bz_canusewhines group by setting the User RegExp to ".*" (without - the quotes). - </para> - - <para> - Also worth noting is the bz_canusewhineatothers group. Members of this - group can create whines for any user or group in Bugzilla using a - extended form of the whining interface. Features only available to - members of the bz_canusewhineatothers group will be noted in the - appropriate places. - </para> - </warning> - - <note> - <para> - For whining to work, a special Perl script must be executed at regular - intervals. More information on this is available in - <xref linkend="installation-whining"/>. - </para> - </note> - - <note> - <para> - This section does not cover the whineatnews.pl script. See - <xref linkend="installation-whining-cron"/> for more information on - The Whining Cron. - </para> - </note> - - <section id="whining-overview"> - <title>The Event</title> - - <para> - The whining system defines an "Event" as one or more queries being - executed at regular intervals, with the results of said queries (if - there are any) being emailed to the user. Events are created by - clicking on the "Add new event" button. - </para> - - <para> - Once a new event is created, the first thing to set is the "Email - subject line". The contents of this field will be used in the subject - line of every email generated by this event. In addition to setting a - subject, space is provided to enter some descriptive text that will be - included at the top of each message (to help you in understanding why - you received the email in the first place). - </para> - - <para> - The next step is to specify when the Event is to be run (the Schedule) - and what searches are to be performed (the Searches). - </para> - - </section> - - <section id="whining-schedule"> - <title>Whining Schedule</title> - - <para> - Each whining event is associated with zero or more schedules. A - schedule is used to specify when the query (specified below) is to be - run. A new event starts out with no schedules (which means it will - never run, as it is not scheduled to run). To add a schedule, press - the "Add a new schedule" button. - </para> - - <para> - Each schedule includes an interval, which you use to tell Bugzilla - when the event should be run. An event can be run on certain days of - the week, certain days of the month, during weekdays (defined as - Monday through Friday), or every day. - </para> - - <warning> - <para> - Be careful if you set your event to run on the 29th, 30th, or 31st of - the month, as your event may not run exactly when expected. If you - want your event to run on the last day of the month, select "Last day - of the month" as the interval. - </para> - </warning> - - <para> - Once you have specified the day(s) on which the event is to be run, you - should now specify the time at which the event is to be run. You can - have the event run at a certain hour on the specified day(s), or - every hour, half-hour, or quarter-hour on the specified day(s). - </para> - - <para> - If a single schedule does not execute an event as many times as you - would want, you can create another schedule for the same event. For - example, if you want to run an event on days whose numbers are - divisible by seven, you would need to add four schedules to the event, - setting the schedules to run on the 7th, 14th, 21st, and 28th (one day - per schedule) at whatever time (or times) you choose. - </para> - - <note> - <para> - If you are a member of the bz_canusewhineatothers group, then you - will be presented with another option: "Mail to". Using this you - can control who will receive the emails generated by this event. You - can choose to send the emails to a single user (identified by email - address) or a single group (identified by group name). To send to - multiple users or groups, create a new schedule for each additional - user/group. - </para> - </note> - </section> - - <section id="whining-query"> - <title>Whining Searches</title> - - <para> - Each whining event is associated with zero or more searches. A search - is any saved search to be run as part of the specified schedule (see - above). You start out without any searches associated with the event - (which means that the event will not run, as there will never be any - results to return). To add a search, press the "Include search" button. - </para> - - <para> - The first field to examine in your newly added search is the Sort field. - Searches are run, and results included, in the order specified by the - Sort field. Searches with smaller Sort values will run before searches - with bigger Sort values. - </para> - - <para> - The next field to examine is the Search field. This is where you - choose the actual search that is to be run. Instead of defining search - parameters here, you are asked to choose from the list of saved - searches (the same list that appears at the bottom of every Bugzilla - page). You are only allowed to choose from searches that you have - saved yourself (the default saved search, "My Bugs", is not a valid - choice). If you do not have any saved searches, you can take this - opportunity to create one (see <xref linkend="list"/>). - </para> - - <note> - <para> - When running queries, the whining system acts as if you are the user - executing the query. This means that the whining system will ignore - bugs that match your query, but that you can not access. - </para> - </note> - - <para> - Once you have chosen the saved search to be executed, give the query a - descriptive title. This title will appear in the email, above the - results of the query. If you choose "One message per bug", the query - title will appear at the top of each email that contains a bug matching - your query. - </para> - - <para> - Finally, decide if the results of the query should be sent in a single - email, or if each bug should appear in its own email. - </para> - - <warning> - <para> - Think carefully before checking the "One message per bug" box. If - you create a query that matches thousands of bugs, you will receive - thousands of emails! - </para> - </warning> - </section> - - <section> - <title>Saving Your Changes</title> - - <para> - Once you have defined at least one schedule, and created at least one - query, go ahead and "Update/Commit". This will save your Event and make - it available for immediate execution. - </para> - - <note> - <para> - If you ever feel like deleting your event, you may do so using the - "Remove Event" button in the upper-right corner of each Event. You - can also modify an existing event, so long as you "Update/Commit" - after completing your modifications. - </para> - </note> - </section> - - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - |