summaryrefslogtreecommitdiffstats
path: root/docs/en/xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/xml')
-rw-r--r--docs/en/xml/Bugzilla-Guide.xml272
-rw-r--r--docs/en/xml/about.xml461
-rw-r--r--docs/en/xml/administration.xml4532
-rw-r--r--docs/en/xml/installation.xml3320
-rw-r--r--docs/en/xml/integration.xml141
-rw-r--r--docs/en/xml/patches.xml290
-rw-r--r--docs/en/xml/using.xml2654
7 files changed, 3810 insertions, 7860 deletions
diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml
index e9650c7cb..9334472af 100644
--- a/docs/en/xml/Bugzilla-Guide.xml
+++ b/docs/en/xml/Bugzilla-Guide.xml
@@ -1,120 +1,128 @@
-<?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;
+<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- 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 about SYSTEM "about.sgml">
+<!ENTITY conventions SYSTEM "conventions.sgml">
+<!ENTITY doc-index SYSTEM "index.sgml">
+<!ENTITY faq SYSTEM "faq.sgml">
+<!ENTITY gfdl SYSTEM "gfdl.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
+<!ENTITY installation SYSTEM "installation.sgml">
+<!ENTITY administration SYSTEM "administration.sgml">
+<!ENTITY using SYSTEM "using.sgml">
+<!ENTITY integration SYSTEM "integration.sgml">
+<!ENTITY future SYSTEM "future.sgml">
+<!ENTITY index SYSTEM "index.sgml">
+<!ENTITY database SYSTEM "database.sgml">
+<!ENTITY patches SYSTEM "patches.sgml">
+<!ENTITY variants SYSTEM "variants.sgml">
+<!ENTITY requiredsoftware SYSTEM "requiredsoftware.sgml">
-<!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&amp;component=Documentation'>Bugzilla Documentation</ulink>">
-<!ENTITY mysql "http://www.mysql.com/">
+<!-- Coding standards for this document
-<!ENTITY min-perl-ver "5.8.1">
-]>
+1. Preface new or modified sections with a comment stating who
+ modified it and when; please also use the "authorinitials" tag.
+2. There is no "two".
-<!-- Coding standards for this document
+3. Other than the GFDL, please use the "section" tag instead of "sect1", "sect2", etc.
+
+4. Use Entities to include files for new chapters in Bugzilla-Guide.sgml.
+
+5. Ensure all documents compile cleanly to HTML after modification.
+ The errors "DTD Declaration not allowed here" and "DTDDECL catalog types not supported"
+ are normal errors to be expected when compiling the whole guide.
+
+6. Try to index important terms wherever possible.
+
+7. Follow coding standards at http://www.linuxdoc.org.
+
+8. All tags should be lowercase (needsfix)
-* 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.
+9. Code being submitted for review should use the
+"review" tag. Documentation on this is available at
+http://www.linuxdoc.org/LDP/LDP-Author-Guide/tools-hints.html
+ under section 4.9.4, "Making notes on the text while it's being written".
+
+10. Please use sensible spacing. The comments at the very end of each Guide
+ file define reasonable defaults for PSGML mode in EMACS.
+ Double-indent tags, use double spacing whenever possible,
+ try to avoid clutter and feel free to waste space in the code to make it more readable.
-->
-<book id="index">
+<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>
+ <BOOKINFO>
+ <TITLE>The Bugzilla Guide</TITLE>
+ <PUBDATE>v2.12.0, 24 April 2001</PUBDATE>
+ <AUTHOR>
+ <FIRSTNAME>Matthew</FIRSTNAME>
+ <OTHERNAME>P.</OTHERNAME>
+ <SURNAME>Barnson</SURNAME>
+ <affiliation>
+ <address><email>barnboy@trilobyte.net</email></address>
+ </affiliation>
+ </AUTHOR>
+
+ <ABSTRACT>
+ <PARA>This is the documentation for Bugzilla, the Mozilla bug-tracking system.</PARA>
+ </ABSTRACT>
+
+ <REVHISTORY>
+ <REVISION>
+ <REVNUMBER>v2.11</REVNUMBER>
+ <DATE>20 December 2000</DATE>
+ <AUTHORINITIALS>MPB</AUTHORINITIALS>
+ <REVREMARK>Converted the README, FAQ, and DATABASE information into SGML
+ docbook format.</REVREMARK>
+ </REVISION>
+
+ <revision>
+ <revnumber>2.11.1</revnumber>
+ <date>06 March 2001</date>
+ <authorinitials>MPB</authorinitials>
+ <revremark>
+ Took way too long to revise this for 2.12 release.
+ Updated FAQ to use qandaset tags instead of literallayout,
+ cleaned up administration section, added User Guide section,
+ miscellaneous FAQ updates and third-party integration information.
+ From this point on all new tags are lowercase in preparation for the
+ 2.13 release of the Guide in XML format instead of SGML.
+ </revremark>
+ </revision>
+
+ <revision>
+ <revnumber>2.12.0</revnumber>
+ <date>24 April 2001</date>
+ <authorinitials>MPB</authorinitials>
+ <revremark>
+ Things fixed this release: Elaborated on queryhelp interface, added FAQ regarding
+ moving bugs from one keyword to another, clarified possible problems with the Landfill
+ tutorial, fixed a boatload of typos and unclear sentence structures. Incorporated the
+ README into the UNIX installation section, and changed the README to indicate the deprecated
+ status. Things I know need work: Used "simplelist" a lot, where I should have used
+ "procedure" to tag things. Need to lowercase all tags to be XML compliant.
+ </revremark>
+ </revision>
+ </REVHISTORY>
+
+ <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;
@@ -125,25 +133,31 @@
<!-- Administering Bugzilla -->
&administration;
-<!-- Securing Bugzilla -->
-&security;
-
<!-- Using Bugzilla -->
&using;
-<!-- Customizing Bugzilla -->
-&customization;
+<!-- Integrating Bugzilla with Third-Party Tools -->
+&integration;
+
+<!-- The Future of Bugzilla -->
+&future;
+
+<!-- Appendix: The Frequently Asked Questions -->
+&faq;
+
+<!-- Appendix: Required Bugzilla Software Links -->
+&requiredsoftware
-<!-- Appendix: Troubleshooting -->
-&troubleshooting;
+<!-- Appendix: The Database Schema -->
+&database;
+
+<!-- Appendix: Major Bugzilla Variants -->
+&variants;
<!-- Appendix: Custom Patches -->
&patches;
-<!-- Appendix: Manually Installing Perl Modules -->
-&modules;
-
-<!-- Appendix: GNU Free Documentation License -->
+<!-- Appendix: The GNU Free Documentation License -->
&gfdl;
<!-- Glossary -->
@@ -152,27 +166,31 @@
<!-- Index -->
&index;
-
-</book>
+</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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
sgml-general-insert-case:lower
-sgml-indent-data:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
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/en/xml/about.xml b/docs/en/xml/about.xml
index 2594e873f..d1b56cfdb 100644
--- a/docs/en/xml/about.xml
+++ b/docs/en/xml/about.xml
@@ -1,243 +1,242 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-<!ENTITY conventions SYSTEM "conventions.xml"> ] > -->
-<!-- $Id: about.xml,v 1.1 2008/04/03 19:05:43 lpsolit%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-&current-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>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+<!ENTITY conventions SYSTEM "conventions.sgml"> ] >
+
+<CHAPTER ID="about">
+<TITLE>About This Guide</TITLE>
+
+ <SECTION ID="aboutthisguide">
+ <TITLE>Purpose and Scope of this Guide</TITLE>
+ <PARA>
+ This document was started on September 17, 2000
+ by Matthew P. Barnson after a great deal of procrastination updating the Bugzilla FAQ,
+ which I left untouched for nearly half a year.
+ After numerous complete rewrites and reformatting, it is the document you see today.
+ </PARA>
+ <PARA>
+ Despite the lack of updates, Bugzilla is simply the best piece of bug-tracking software
+ the world has ever seen. This document is intended to be the comprehensive guide to
+ the installation, administration, maintenance, and use of the Bugzilla bug-tracking system.
+ </PARA>
+ <PARA>
+ This release of the Bugzilla Guide is the <EMPHASIS>2.11</EMPHASIS> release.
+ It is so named that it may match the current version of Bugzilla.
+ The numbering tradition stems from that used for many free software projects,
+ in which <EMPHASIS>even-numbered</EMPHASIS> point releases (1.2, 1.14, etc.)
+ are considered "stable releases", intended for public consumption; on the other
+ hand, <EMPHASIS>odd-numbered</EMPHASIS> point releases (1.3, 2.09, etc.)
+ are considered unstable <EMPHASIS>development</EMPHASIS> releases intended
+ for advanced users, systems administrators, developers, and those who enjoy
+ a lot of pain.
+ </PARA>
+ <PARA>
+ Newer revisions of the Bugzilla Guide will follow the numbering conventions of
+ the main-tree Bugzilla releases, available at
+ <ULINK URL="http://www.mozilla.org/bugs/source.html">Mozilla.org</ULINK>, with
+ the exception that intermediate releases will have a minor revision number
+ following a period. For instance, if the current version of Bugzilla is 4.2,
+ the current "stable" version of the Bugzilla guide, in, say, it's fifth revision,
+ would be numbered "4.2.5". Got it? Good.
+ </PARA>
+ <PARA>
+ I wrote this in response to the enormous demand for decent Bugzilla documentation.
+ I have incorporated instructions from the Bugzilla README, Frequently Asked Questions,
+ Database Schema Document, and various mailing lists to create it.
+ Chances are, there are glaring errors in this documentation; please contact
+ <EMAIL>barnboy@trilobyte.net</EMAIL> to correct them.
+ </PARA>
+ </SECTION>
+
+ <SECTION ID="copyright">
+ <TITLE>Copyright Information</TITLE>
+ <BLOCKQUOTE>
+ <ATTRIBUTION>Copyright (c) 2000-2001 Matthew P. Barnson</ATTRIBUTION>
+ <PARA>
+ Permission is granted to copy, distribute and/or modify this document under thei
+ 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 the section entitled
+ "GNU Free Documentation LIcense".
+ </PARA>
+ </BLOCKQUOTE>
+ <PARA>
+ If you have any questions regarding this document, its' copyright, or publishing this
+ document in non-electronic form, please contact <EMAIL>barnboy@trilobyte.net</EMAIL>
+ </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>
+ Use the concepts, examples, and other content at your own risk.
+ As this is a new edition of this document, there may be errors
+ and inaccuracies that may damage your system. Use of this document
+ may cause your girlfriend to leave you, your cats to pee on your
+ furniture and clothing, your computer to cease functioning, your
+ boss to fire you, and global thermonuclear war. Proceed with caution.
+ </PARA>
+ <PARA>
+ All copyrights are held by their respective owners, unless specifically
+ noted otherwise. Use of a term in this document should not be regarded
+ as affecting the validity of any trademark or service mark.
+ In particular, I like to put down Microsoft(tm). Live with it.
+ </PARA>
+ <PARA>
+ Naming of particular products or brands should not be seen as endorsements,
+ with the exception of the term "GNU/Linux".
+ Use GNU/Linux. Love it. Bathe with it. It is life and happiness.
+ I endorse it wholeheartedly and encourage you to do the same.
+ </PARA>
+ <PARA>
+ You are strongly recommended to make a backup of your system before
+ installing Bugzilla and at regular intervals thereafter. Heaven knows
+ it's saved my bacon time after time; if you implement any suggestion in
+ this Guide, implement this one!
+ </PARA>
+ <PARA>
+ Bugzilla has not undergone a complete security review.
+ Security holes probably exist in the code.
+ Great care should be taken both in the installation and usage of this software.
+ Carefully consider the implications of installing other network services with Bugzilla.
+ </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>
+ <SECTION ID="newversions">
+ <TITLE>New Versions</TITLE>
+ <PARA>
+ This is the initial release of the Bugzilla Guide.
+ </PARA>
+ <PARA>
+ This document can be found in the following places:
+ </PARA>
+ <PARA>
+ <ITEMIZEDLIST>
+ <LISTITEM>
+ <PARA>
+ <ULINK URL="http://www.trilobyte.net/barnsons/">TriloBYTE</ULINK>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <ULINK URL="http://www.mozilla.org/projects/bugzilla/">Mozilla.org</ULINK>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <ULINK URL="http://www.linuxdoc.org/">The Linux Documentation Project</ULINK>
+ </PARA>
+ </LISTITEM>
+ </ITEMIZEDLIST>
+ </PARA>
+ <PARA>
+ The latest version of this document can be checked out via CVS.
+ Please follow the instructions available at
+ <ULINK URL="http://www.mozilla.org/cvs.html">the Mozilla CVS page</ULINK>,
+ and check out the mozilla/webtools/bugzilla/docs/ branch.
+ </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 dedicated hacking efforts,
+ numerous e-mail and IRC support sessions,
+ and overall excellent contribution to the Bugzilla community:
+ </PARA>
+ <PARA>
+ <ULINK URL="mailto://terry@mozilla.org">Terry Weissman</ULINK>
+ for initially converting Bugzilla from BugSplat!
+ and writing the README upon which this documentation is largely based.
+ </PARA>
+ <PARA>
+ <ULINK URL="mailto://tara@tequilarista.org">Tara Hernandez</ULINK>
+ for keeping Bugzilla development going strong after Terry left Mozilla.org
+ </PARA>
+ <PARA>
+ <ULINK URL="mailto://dkl@redhat.com">Dave Lawrence</ULINK>
+ for providing insight into the key differences between Red Hat's
+ customized Bugzilla, and being largely responsible for the
+ "Red Hat Bugzilla" appendix
+ </PARA>
+ <PARA>
+ <ULINK URL="mailto://endico@mozilla.org">Dawn Endico</ULINK>
+ for being a hacker extraordinaire and putting up with my incessant
+ questions and arguments on irc.mozilla.org in #mozwebtools
+ </PARA>
+ <PARA>
+ Last but not least, all the members of the
+ <ULINK URL="news://news.mozilla.org/netscape/public/mozilla/webtools">
+ netscape.public.mozilla.webtools</ULINK> newsgroup. Without your
+ discussions, insight, suggestions, and patches, this could never have happened.
+ </PARA>
+ </SECTION>
+ <SECTION id="contributors">
+<TITLE>Contributors</TITLE>
+ <PARA>
+ Thanks go to these people for significant contributions
+ to this documentation (in no particular order):
+ </PARA>
+ <PARA>
+ Zach Lipton (significant textual contributions),
+ Andrew Pearson,
+ Spencer Smith,
+ Eric Hanson,
+ Kevin Brannen,
+ </PARA>
+ </SECTION>
+ <SECTION ID="feedback">
+ <TITLE>Feedback</TITLE>
+ <PARA>
+ I welcome feedback on this document. Without your submissions and input,
+ this Guide cannot continue to exist. Please mail additions, comments, criticisms, etc.
+ to <EMAIL>barnboy@trilobyte.net</EMAIL>. Please send flames to
+ <EMAIL>devnull@localhost</EMAIL>
+ </PARA>
+ </SECTION>
+
+ <SECTION ID="translations">
+ <TITLE>Translations</TITLE>
+ <PARA>
+ The Bugzilla Guide needs translators!
+ Please volunteer your translation into the language of your choice.
+ If you will translate this Guide, please notify the members of the mozilla-webtools mailing list at
+ <email>mozilla-webtools@mozilla.org</email>. Since The Bugzilla Guide is also hosted on the
+ Linux Documentation Project, you would also do well to notify
+ </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
+</CHAPTER>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:upper
+sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
-sgml-auto-insert-required-elements:t
-sgml-balanced-tag-edit:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:Bugzilla-Guide\.sgml
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: -->
+sgml-local-ecat-files:nil
+sgml-doctype:"<!DOCTYPE chapter PUBLIC \"-//OASIS//DTD DocBook V4.1//EN\">"
+End:
+-->
+
+
+
+
+
+
+
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index 7a75604de..c52cacebf 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -1,3448 +1,1118 @@
-<!-- <!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>&lt;div&gt;</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>&lt;div&gt;</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>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<!-- TOC
+Chapter: Administration
+ Localconfig and Checksetup.pl customizations
+ The Email Gateway
+ Editing parameters
+ Deciding your site policies
+ The Shadow Database
+ Customizing password mail & layout
+ The Whining Cron
+ Why you shouldn't allow deletion
+ User administration
+ Creating Users
+ Disabling Users
+ User Permissions
+ Product Administration
+ Creating products
+ Creating components
+ Assigning default owners and Q/A contacts to components
+ Product Milestones
+ Product Versions
+ Voting
+-->
- <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>
+<CHAPTER id="administration">
+ <TITLE>Administering Bugzilla</TITLE>
+<SUBTITLE>Or, I just got this cool thing installed. Now what the heck do I do with it?</SUBTITLE>
+
+<PARA>
+So you followed the README isntructions to the letter, and
+just logged into bugzilla with your super-duper god account and you are sitting at the query
+screen. Yet, you have nothing to query. Your first act of business needs to be to setup the
+operating parameters for bugzilla.</PARA>
+
+ <SECTION id="postinstall-check">
+ <TITLE>Post-Installation Checklist</TITLE>
+ <PARA>
+ After installation, follow the checklist below to ensure that
+ you have a successful installation.
+ If you do not see a recommended setting for a parameter,
+ consider leaving it at the default
+ while you perform your initial tests on your Bugzilla setup.
+ </PARA>
+ <INDEXTERM>
+ <PRIMARY>checklist</PRIMARY>
+ </INDEXTERM>
+ <PROCEDURE>
+ <STEP>
+ <PARA>
+ Bring up "editparams.cgi" in your web browser. For instance, to edit parameters
+ at mozilla.org, the URL would be <ULINK URL="http://bugzilla.mozilla.org/editparams.cgi">
+ http://bugzilla.mozilla.org/editparams.cgi</ULINK>, also available under the "edit parameters"
+ link on your query page.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "maintainer" to <EMPHASIS>your</EMPHASIS> email address.
+ This allows Bugzilla's error messages
+ to display your email
+ address and allow people to contact you for help.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "urlbase" to the URL reference for your Bugzilla installation.
+ If your bugzilla query page is at http://www.foo.com/bugzilla/query.cgi,
+ your url base is http://www.foo.com/bugzilla/
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "usebuggroups" to "1" <EMPHASIS>only</EMPHASIS>
+ if you need to restrict access to products.
+ I suggest leaving this parameter <EMPHASIS>off</EMPHASIS>
+ while initially testing your Bugzilla.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "usebuggroupsentry" to "1" if you want to restrict access to products.
+ Once again, if you are simply testing your installation, I suggest against
+ turning this parameter on; the strict security checking may stop you from
+ being able to modify your new entries.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "shadowdb" to "bug_shadowdb" if you will be
+ running a *very* large installation of Bugzilla.
+ The shadow database enables many simultaneous users
+ to read and write to the database
+ without interfering with one another.
+ <NOTE>
+ <PARA>
+ Enabling "shadowdb" can adversely affect the stability
+ of your installation of Bugzilla.
+ You may frequently need to manually synchronize your databases,
+ or schedule nightly syncs
+ via "cron"
+ </PARA>
+ </NOTE>
+ Once again, in testing you should
+ avoid this option -- use it if or when you <EMPHASIS>need</EMPHASIS> to use it, and have
+ repeatedly run into the problem it was designed to solve -- very long wait times while
+ attempting to commit a change to the database.
+ </PARA>
+ <PARA>
+ If you use the "shadowdb" option,
+ it is only natural that you should turn the "queryagainstshadowdb"
+ option "On" as well. Otherwise you are replicating data into a shadow database for no reason!
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ If you have custom logos or HTML you must put in place to fit within your site design guidelines,
+ place the code in the "headerhtml", "footerhtml", "errorhtml",
+ "bannerhtml", or "blurbhtml" text boxes.
+ <NOTE>
+ <PARA>
+ The "headerhtml" text box is the HTML printed out
+ <EMPHASIS>before</EMPHASIS> any other code on the page.
+ If you have a special banner, put the code for it in "bannerhtml".
+ You may want to leave these
+ settings at the defaults initially.
+ </PARA>
+ </NOTE>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Add any text you wish to the "passwordmail" parameter box. For instance,
+ many people choose to use this box to give a quick training blurb about how to
+ use Bugzilla at your site.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Ensure "newemailtech" is "on".
+ Your users will thank you. This is the default in the post-2.12 world, and is
+ only an issue if you are upgrading.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Do you want to use the qa contact ("useqacontact")
+ and status whiteboard ("usestatuswhiteboard") fields?
+ These fields are useful because they allow for more flexibility,
+ particularly when you have an existing
+ Quality Assurance and/or Release Engineering team,
+ but they may not be needed for smaller installations.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "whinedays" to the amount 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 README, or set this value to "0".
+ </PARA>
+ </STEP>
+ <STEP>
+ <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.
+ <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>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Set "supportwatchers" to "On". This feature is helpful for team leads to monitor progress in their
+ respective areas, and can offer many other benefits, such as allowing a developer to pick up a
+ former engineer's bugs without requiring her to change all the information in the bug.
+ </PARA>
+ </STEP>
+ </PROCEDURE>
+ </SECTION>
+
+ <SECTION id="useradmin">
+ <TITLE>User Administration</TITLE>
+ <PARA>
+ User administration is one of the easiest parts of Bugzilla.
+ Keeping it from getting out of hand, however, can become a challenge.
+ </PARA>
+
+ <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 were to 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, you must use the MySQL interface.
+ Run "mysql" from the command line, and use these commands ("mysql>" denotes the
+ mysql prompt, not something you should type in):
+ <COMMAND><PROMPT>mysql></PROMPT> use bugs;</COMMAND>
+ <COMMAND><PROMPT>mysql></PROMPT> update profiles set groupset=0x7ffffffffffffff
+ where login_name = "(user's login name)"; </COMMAND>
+ </PARA>
+ </TIP>
+ </SECTION>
+
+ <SECTION id="manageusers">
+ <TITLE>Managing Other Users</TITLE>
+
+ <SECTION id="login">
+ <TITLE>Logging In</TITLE>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Open the index.html page for your Bugzilla installation in your browser window.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Click the "Query Existing Bug Reports" link.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Click the "Log In" link at the foot of the page.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Type your email address, and the password which was emailed to you when you
+ created your Bugzilla account, into the spaces provided.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ <PARA>Congratulations, you are logged in!</PARA>
+ </SECTION>
+
+ <SECTION id="createnewusers">
+ <TITLE>Creating new users</TITLE>
+ <PARA>
+ Your users can create their own user accounts by clicking the "New Account"
+ link at the bottom of each page.
+ However, should you desire to create user accounts ahead of time, here is how you do it.
+ </PARA>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ After logging in, click the "Users" link at the footer of the query page.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ To see a specific user, type a portion of their login name
+ in the box provided and click "submit".
+ To see all users, simply click the "submit" button.
+ You must click "submit" here to be able to add a new user.
+ </PARA>
+ <TIP>
+ <PARA>
+ More functionality is available via the list on the right-hand side
+ of the text entry box.
+ You can match what you type as a case-insensitive substring (the default)
+ of all users on your system, a case-sensitive regular expression
+ (please see the "man regexp" manual page for details on regular expression syntax),
+ or a <EMPHASIS>reverse</EMPHASIS> regular expression match,
+ where every user name which does NOT match the regular expression
+ is selected.
+ </PARA>
+ </TIP>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Click the "Add New User" link at the bottom of the user list
+ </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.
+ In general, it is preferable to log out and use the "New Account"
+ button to create users, as it will pre-populate all the required fields and also notify
+ the user of her account name and password.
+ </PARA>
+ </NOTE>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
+
+ <SECTION id="disableusers">
+ <TITLE>Disabling Users</TITLE>
+ <PARA>
+ I bet you noticed that big "Disabled Text" entry box available from the "Add New User" screen,
+ when you edit an account?
+ By entering any text in this box and selecting "submit",
+ you have prevented the user from using Bugzilla via the web interface.
+ Your explanation, written in this text box, will be presented to the user
+ the next time she attempts to use the system.
+ <WARNING>
+ <PARA>
+ Don't disable your own administrative account, or you will hate life!
+ </PARA>
+ </WARNING>
+ </PARA>
+ </SECTION>
+
+ <SECTION id="modifyusers">
+ <TITLE>Modifying Users</TITLE>
+ <PARA>
+ Here I will attempt to describe the function of each option on the user edit screen.
+ </PARA>
+ <ITEMIZEDLIST>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Login Name</EMPHASIS>: This is generally the user's email address.
+ However, if you have edited your system parameters,
+ this may just be the user's login name or some other identifier.
+ <TIP>
+ <PARA>
+ For compatability reasons, you should probably
+ stick with email addresses as user login names. It will make your life easier.
+ </PARA>
+ </TIP>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Real Name</EMPHASIS>: Duh!
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Password</EMPHASIS>: You will only see asterisks in versions
+ of Bugzilla newer than 2.10 or early 2.11. You can change the user password here.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Email Notification</EMPHASIS>: You may choose from one of three options:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ All qualifying bugs except those which I change:
+ The user will be notified of any change to any bug
+ for which she is the reporter, assignee, Q/A contact, CC recipient, or "watcher".
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Only those bugs which I am listed on the CC line:
+ The user will not be notified of changes to bugs where she is the assignee,
+ reporter, or Q/A contact, but will receive them if she is on the CC list.
+ <NOTE>
+ <PARA>
+ She will still receive whining cron emails if you set up the "whinemail" feature.
+ </PARA>
+ </NOTE>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>All Qualifying Bugs</EMPHASIS>: This user is a glutton for punishment.
+ If her name is in the reporter, Q/A contact, CC, assignee, or is a "watcher",
+ she will get email updates regarding the bug.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+</PARA>
+ <PARA>
+ <EMPHASIS>Disable Text</EMPHASIS>: If you type anything in this box,
+ including just a space, the user account is disabled from making any changes
+ to bugs via the web interface, and what you type in this box is presented as the reason.
+ <WARNING>
+ <PARA>Don't disable the administrator account!</PARA>
+ </WARNING>
+ <NOTE>
+ <PARA>
+ As of this writing, the user can still submit bugs via the e-mail gateway,
+ if you set it up, despite the disabled text field. The e-mail gateway should
+ <EMPHASIS>not</EMPHASIS> be enabled for secure installations of Bugzilla.
+ </PARA>
+ </NOTE>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>CanConfirm</EMPHASIS>: This field is only used if you have enabled
+ "unconfirmed" status in your parameters screen. If you enable this for a user,
+ that user can then move bugs from "Unconfirmed" to "Confirmed" status (ergo: "New" status).
+ Be judicious about allowing users to turn this bit on for other users.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Creategroups</EMPHASIS>: This option will allow a user to create and
+ destroy groups in Bugzilla. Unless you are using the Bugzilla GroupSentry security
+ option "usebuggroupsentry" in your parameters, this setting has no effect.
+ </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.
+ <NOTE>
+ <PARA>
+ Leaving this option unchecked does not prevent users from adding
+ comments to a bug! They simply cannot change a bug priority, severity,
+ etc. unless they are the assignee or reporter.
+ </PARA>
+ </NOTE>
+ </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. The name of a product or component can be
+ changed without affecting the associated bugs, but it tends to annoy
+ the hell out of your users when these change a lot.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Editkeywords</EMPHASIS>: If you use Bugzilla's keyword functionality,
+ enabling this feature allows a user can 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.
+ You must be very careful about creating too many new keywords
+ if you run a very large Bugzilla installation; keywords are global variables
+ across products, and you can often run into a phenomenon called "keyword bloat".
+ This confuses users, and then the feature goes unused.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>Editusers</EMPHASIS>: This flag allows a user do what you're doing
+ right now: edit other users.
+ This will allow those with the right to do so to remove administrator
+ priveleges from other users or grant them to themselves. Enable with care.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <EMPHASIS>PRODUCT</EMPHASIS>: PRODUCT bugs access. This allows an administrator,
+ with product-level granularity, to specify in which products a user can edit bugs.
+ The user must still have the "editbugs" privelege to edit bugs in this area;
+ this simply restricts them from even seeing bugs outside these boundaries if the administrator
+ has enabled the group sentry parameter "usebuggroupsentry". Unless you are using bug groups,
+ this option has no effect.
+ </PARA>
+ </LISTITEM>
+ </ITEMIZEDLIST>
+ </SECTION>
+ </SECTION>
+ </SECTION>
+
+ <SECTION id="programadmin">
+ <TITLE>Product, Component, Milestone, and Version Administration</TITLE>
+ <EPIGRAPH>
+ <PARA>
+ Dear Lord, we have to get our users to do WHAT?
+ </PARA>
+ </EPIGRAPH>
+
+ <SECTION id="products">
+ <TITLE>Products</TITLE>
+ <SUBTITLE>Formerly, and in some spots still, called "Programs"</SUBTITLE>
+ <PARA>
+ <GLOSSTERM baseform="product" linkend="gloss_product">Products</GLOSSTERM> are the
+ broadest category in Bugzilla, and you should have the least of these.
+ If your company makes computer games, you should have one product per game,
+ and possibly a few special products
+ (website, meetings...)
+ </PARA>
+ <PARA>
+ A Product (formerly called "Program", and still referred to that way
+ in some portions of the source code) controls some very important functions.
+ The number of "votes" available for users to vote for the most important bugs
+ is set per-product, as is the number of votes required to move a bug automatically
+ from the UNCONFIRMED status to the NEW status. One can close a Product for further
+ bug entry and define various Versions available from the Edit Product screen.
+ </PARA>
+ <PARA>To create a new product:</PARA>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Select "components" from the yellow footer
+ </PARA>
+ <TIP>
+ <PARA>
+ It may seem counterintuitive to click "components" when you want
+ to edit the properties associated with Products. This is one of a long
+ list of things we want in Bugzilla 3.0...
+ </PARA>
+ </TIP>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Select the "Add" link to the right of "Add a new product".
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Enter the name of the product and a description.
+ The Description field is free-form.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ <TIP>
+ <PARA>
+ Don't worry about the "Closed for bug entry", "Maximum Votes per person",
+ "Maximum votes a person can put on a single bug", "Number of votes a bug in
+ this Product needs to automatically get out of the UNCOMFIRMED state",
+ and "Version" options yet.
+ We'll cover those in a few moments.
+ </PARA>
+ </TIP>
+ </SECTION>
- <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>
+ <SECTION id="components">
+ <TITLE>Components</TITLE>
+ <PARA>
+ Components are subsections of a Product.
+
+ <EXAMPLE>
+ <TITLE>Creating some Components</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ The computer game you are designing may 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>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+
+ Each component has a owner and (if you turned it on in the parameters), a qa
+ contact. The owner should be the primary person who fixes bugs in that component. The QA
+ Contact should be the person who will ensure these bugs are completely fixed. The Owner,
+ QA Contact, and Reporter will get email when new bugs are created in this Component and
+ when these bugs change. Default Owner and Default QA Contact fields only dictate the
+ <EMPHASIS>default assignments</EMPHASIS>; the Owner and Q/A Contact fields in a bug
+ are otherwise unrelated to the Component.
+ </PARA>
+
+ <PARA>
+ To create a new Component:
+ </PARA>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Select the "Edit components" link from the "Edit Product" page
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Select the "Add" link to the right of the "Add a new component" text
+ on the "Select Component" page.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Fill out the "Component" field, a short "Description", and the "Initial Owner".
+ The "Component" field should not contain a space. The "Description" field is
+ free-form. The "Initial Owner" field must be that of a valid user already
+ existing in the database. If the initial owner does not exist, Bugzilla
+ will refuse to create the component.
+ <TIP>
+ <PARA>
+ Is your "Default Owner" a user who is not yet in the database?
+ No problem.
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Select the "Log out" link on the footer of the page.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Select the "New Account" link on the footer of the "Relogin" page
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Type in the email address of the default owner you want to create
+ in the "E-mail address" field, and her full name in the "Real name"
+ field, then select the "Submit Query" button.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Now select "Log in" again, type in your login information, and you
+ can modify the product to use the Default Owner information
+ you require.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ </TIP>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Either "edit" more components or return to the "query" page on the ensuing
+ "Addming new component" page. To return to the Product you were editing, you
+ must select the "components" link as before.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
- <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>
+ <SECTION id="versions">
+ <TITLE>Versions</TITLE>
+ <PARA>
+ Versions are the revisions of the product, such as "Flinders 3.1", "Flinders 95",
+ and "Flinders 2000". Using Versions helps you isolate code changes and are an aid
+ in reporting.
+
+ <EXAMPLE>
+ <TITLE>Common Use of Versions</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ A user reports a bug
+ against Version "Beta 2.0" of your product. The current Version of your software
+ is "Release Candidate 1", and no longer has the bug. This will
+ help you triage and classify bugs according to their relevance. It is also
+ possible people may report bugs against bleeding-edge beta versions that are
+ not evident in older versions of the software. This can help isolate code
+ changes that caused the bug
+ </PARA>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+ <EXAMPLE>
+ <TITLE>A Different Use of Versions</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ This field has been used to good effect by an online service provider in a slightly
+ different way. They had three versions of the product: "Production", "QA",
+ and "Dev". Although it may be the same product, a bug in the development
+ environment is not normally as critical as a Production bug, nor does it
+ need to be reported publicly. When used in conjunction with Target Milestones,
+ one can easily specify the environment where a bug can be reproduced, and
+ the Milestone by which it will be fixed.
+ </PARA>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+ </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".
+ If your product doesn't use version numbers, you may want to leave this as it is
+ or edit it so that it is "---". You can then go back to the edit versions page
+ and add new versions to your product.
+ </PARA>
+ <PARA>
+ Otherwise, click the "Add" button to the right of the "Add a new version" text.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Enter the name of the Version. This can be free-form characters up to the limit of the
+ text box. Then select the "Add" button.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ At this point you can select "Edit" to edit more Versions, or return to the "Query"
+ page, from which you can navigate back to the product through the "components" link
+ at the foot of the Query page.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
- <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>
+ <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. Or, you have a
+ bug that you plan to fix for 2.8, this would have a milestone of 2.8.
+ </PARA>
+ <NOTE>
+ <PARA>
+ Milestone options will only appear for a Product if you turned the "usetargetmilestone" field
+ in the "Edit Parameters" screen "On".
+ </PARA>
+ </NOTE>
+ <PARA>
+ To create new Milestones, set Default Milestones, and set Milestone URL:
+ </PARA>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Select "edit milestones"
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Select "Add" to the right of the "Add a new milestone" 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 (-255 to 255)
+ that defines where in the list this particular milestone appears.
+ Select "Add".
+ </PARA>
+ <EXAMPLE>
+ <TITLE>Using SortKey with Target Milestone</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ Let's say you create a target milestone called "Release 1.0", with Sortkey set to "0".
+ Later, you realize that you will have a public beta, called "Beta1".
+ You can create a Milestone called "Beta1", with a Sortkey of "-1" in order to ensure
+ people will see the Target Milestone of "Beta1" earlier on the list than "Release 1.0"
+ </PARA>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ If you want to add more milestones, select the "Edit" link.
+ If you don't, well shoot, you have to go back to the "query" page and select "components"
+ again, and make your way back to the Product you were editing.
+ <NOTE>
+ <PARA>
+ This is another in the list of unusual user interface decisions that
+ we'd like to get cleaned up. Shouldn't there be a link to the effect of
+ "edit the Product I was editing when I ended up here"? In any case,
+ clicking "components" in the footer takes you back to the "Select product"
+ screen, from which you can begin editing your product again.
+ </PARA>
+ </NOTE>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ From the Edit Product screen again (once you've made your way back), enter the URL
+ for a description of what your milestones are for this product in the "Milestone URL" field.
+ It should be of the format "http://www.foo.com/bugzilla/product_milestones.html"
+ </PARA>
+ <PARA>
+ Some common uses of this field include product descriptions, product roadmaps,
+ and of course a simple description of the meaning of each milestone.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ If you're using Target Milestones, the "Default Milestone" field must have some
+ kind of entry. If you really don't care if people set coherent Target Milestones,
+ simply leave this at the default, "---". However, controlling and regularly updating the Default
+ Milestone field is a powerful tool when reporting the status of projects.
+ </PARA>
+ <PARA>Select the "Update" button when you are done.</PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
- <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>&lt;groupname&gt;</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>&lt;productname&gt;</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>
+ <SECTION id="voting">
+ <TITLE>Voting</TITLE>
+ <PARA>
+ The concept of "voting" is a poorly understood, yet powerful feature for the management
+ of open-source projects. Each user is assigned so many Votes per product, which they can
+ freely reassign (or assign multiple votes to a single bug).
+ This allows developers to gauge user need for a particular enhancement
+ or bugfix. By allowing bugs with a certain number of votes to automatically move from
+ "UNCONFIRMED" to "NEW", users of the bug system can help high-priority bugs garner
+ attention so they don't sit for a long time awaiting triage.
+ </PARA>
+ <PARA>
+ The daunting challenge of Votes is deciding where you draw the line for a "vocal majority". If you
+ only have a user base of 100 users, setting a low threshold for bugs to move from UNCONFIRMED
+ to NEW makes sense. As the Bugzilla user base expands, however, these thresholds must be
+ re-evaluated. You should gauge whether this feature is worth the time and close monitoring involved,
+ and perhaps forego implementation until you have a critical mass of users who demand it.
+ </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>
+ Set "Maximum Votes per person" to your calculated value. Setting this field
+ to "0" disables voting.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Set "Maximum Votes a person can put on a single bug" to your calculated value. It
+ should probably be some number lower than the "Maximum votes per person".
+ Setting this field to "0" disables voting, but leaves the voting options open
+ to the user. This is confusing.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Set "Number of votes a bug in this product needs to automatically get out of the
+ UNCONFIRMED state" to your calculated number. Setting this field to "0"
+ disables the automatic move of bugs from UNCONFIRMED to NEW. Some people
+ advocate leaving this at "0", but of what use are Votes if your Bugzilla
+ user base is unable to affect which bugs appear on Development radar?
+ <TIP>
+ <PARA>
+ You should probably set this number to higher than a small coalition of
+ Bugzilla users can influence it. Most sites use this as a "referendum"
+ mechanism -- if users are able to vote a bug out of UNCONFIRMED, it
+ is a <EMPHASIS>really</EMPHASIS> bad bug!
+ </PARA>
+ </TIP>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Once you have adjusted the values to your preference, select the "Update" button.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
+
+ <SECTION id="groups">
+ <TITLE>Groups and Group Security</TITLE>
+ <PARA>
+ Groups can be very useful in bugzilla, because they allow users to isolate
+ bugs or products that should only be seen by certain people. Groups can also
+ be a complicated minefield of interdependencies and weirdness if mismanaged.
+
+ <EXAMPLE>
+ <TITLE>When to Use Group Security</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ Many Bugzilla sites isolate "Security-related" bugs from all other bugs.
+ This way, they can have a fix ready before the security vulnerability
+ is announced to the world. You can create a "Security" product which, by
+ default, has no members, and only add members to the group (in their individual
+ User page, as described under User Administration) who should have
+ priveleged access to "Security" bugs. Alternately, you may create a Group
+ independently of any Product, and change the Group mask on individual bugs
+ to restrict access to members only of certain Groups.
+ </PARA>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+
+ Groups only work if you enable the "usebuggroups" paramater.
+ In addition, if the "usebuggroupsentry" parameter is "On", one can restrict access
+ to products by groups, so that only members of a product group are able to view
+ bugs within that product.
+ Group security in Bugzilla can be divided into two categories:
+ Generic and Product-Based.
+ </PARA>
+ <NOTE>
+ <PARA>
+ Groups in Bugzilla are a complicated beast that evolved out of very simple user
+ permission bitmasks, apparently itself derived from common concepts in UNIX access
+ controls. A "bitmask" is a fixed-length number whose value can describe one, and
+ only one, set of states. For instance, UNIX file permissions are assigned bitmask
+ values: "execute" has a value of 1, "write" has a value of 2,
+ and "read" has a value of 4. Add them together,
+ and a file can be read, written to, and executed if it has a bitmask of "7". (This
+ is a simplified example -- anybody who knows UNIX security knows there is much
+ more to it than this. Please bear with me for the purpose of this note.) The only
+ way a bitmask scheme can work is by doubling the bit count for each value. Thus
+ if UNIX wanted to offer another file permission, the next would have to be a value of
+ 8, then the next 16, the next 32, etc.
+ </PARA>
+ <PARA>
+ Similarly, Bugzilla offers a bitmask to define group permissions, with an internal
+ limit of 64. Several are already occupied
+ by built-in permissions. The way around this limitation is
+ to avoid assigning groups to products if you have many products, avoid bloating
+ of group lists, and religiously prune irrelevant groups. In reality, most installations
+ of Bugzilla support far fewer than 64 groups, so this limitation has not hit
+ for most sites, but it is on the table to be revised for Bugzilla 3.0
+ because it interferes with the security schemes of some administrators.
+ </PARA>
+ </NOTE>
+ <PARA>
+ To enable Generic Group Security ("usebuggroups"):
+ </PARA>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Turn "On" "usebuggroups" in the "Edit Parameters" screen.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ You will generally have no groups set up. Select the "groups" link
+ in the footer.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Take a moment to understand the instructions on the "Edit Groups" screen.
+ Once you feel confident you understand what is expected of you, select the
+ "Add Group" link.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Fill out the "New Name" (remember, no spaces!), "New Description", and "New
+ User RegExp" fields. "New User RegExp" allows you to automatically place
+ all users who fulfill the Regular Expression into the new group.
+
+ <EXAMPLE>
+ <TITLE>Creating a New Group</TITLE>
+ <INFORMALEXAMPLE>
+ <PARA>
+ I created a group called "DefaultGroup" with a description of "This is simply
+ a group to play with", and a "New User RegExp" of "*@velio.com". This
+ new group automatically includes all Bugzilla users with "@velio.com" at the
+ end of their user id. When I finished, my new group was assigned bit #128.
+ </PARA>
+ </INFORMALEXAMPLE>
+ </EXAMPLE>
+
+ When you have finished, select the "Add" button.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+
+ <PARA>
+ To enable Product-Based Group Security ("usebuggroupsentry"):
+ </PARA>
+ <WARNING>
+ <PARA>
+ Don't forget that you only have 64 groups masks available, total, for
+ your installation of Bugzilla! If you plan on having more than 50
+ products in your individual Bugzilla installation, and require group
+ security for your products, you should
+ consider either running multiple Bugzillas or using Generic Group Security
+ instead of Product-Based ("usebuggroupsentry") Group Security.
+ </PARA>
+ </WARNING>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit Parameters" screen.
+ </PARA>
+ <WARNING>
+ <PARA>
+ "usebuggroupsentry" has the capacity to prevent the administrative user
+ from directly altering bugs because of conflicting group permissions.
+ If you plan on using "usebuggroupsentry", you should plan on restricting administrative
+ account usage to administrative duties only.
+ In other words, manage bugs with an unpriveleged user account, and
+ manage users, groups, Products, etc. with the administrative account.
+ </PARA>
+ </WARNING>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ You will generally have no Groups set up, unless you enabled "usebuggroupsentry"
+ prior to creating any Products. To create "Generic Group Security" groups,
+ follow the instructions given above. To create Product-Based Group security,
+ simply follow the instructions for creating a new Product. If you need to
+ add users to these new groups as you create them, you will find the option
+ to add them to the group available under the "Edit User" screens.
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </SECTION>
+ </SECTION>
- <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>
+ <SECTION id="security">
+ <TITLE>Bugzilla Security</TITLE>
+ <EPIGRAPH>
+ <PARA>
+ Putting your money in a wall safe is better protection than depending on the fact that
+ no one knows that you hide your money in a mayonnaise jar in your fridge.
+ </PARA>
+ </EPIGRAPH>
+ <NOTE>
+ <PARA>
+ Poorly-configured MySQL, Bugzilla, and FTP installations have given attackers full
+ access to systems in the past. Please take these guidelines seriously, even
+ for Bugzilla machines hidden away behind your firewall. 80% of all computer
+ trespassers are insiders, not anonymous crackers.
+ </PARA>
+ </NOTE>
+ <PARA>
+ First thing's first: Secure your installation.
+ <NOTE>
+ <PARA>
+ These instructions must, of necessity, be somewhat vague since Bugzilla runs on so many different
+ platforms. If you have refinements of these directions for specific platforms, please
+ submit them to <ULINK URL="mailto://mozilla-webtools@mozilla.org">mozilla-webtools@mozilla.org</ULINK>
+ </PARA>
+ </NOTE>
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Ensure you are running at least MysQL version 3.22.32 or newer. Earlier versions had
+ notable security holes and poorly secured default configuration choices.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA><EMPHASIS>There is no substitute for understanding the tools on your system!</EMPHASIS>
+ Read <ULINK URL="http://www.mysql.com/documentation/mysql/bychapter/manual_Privilege_system.html">
+ The MySQL Privelege System</ULINK> until you can recite it from memory!</PARA>
+ <PARA>
+ At the very least, ensure you password the "mysql -u root" account and the "bugs" account, establish grant
+ table rights (consult the Keystone guide in Appendix C: The Bugzilla Database for some easy-to-use details)
+ that do not allow CREATE, DROP, RELOAD, SHUTDOWN, and PROCESS for user "bugs". I wrote up the Keystone
+ advice back when I knew far less about security than I do now : )
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Lock down /etc/inetd.conf. Heck, disable inet entirely on this box. It should only listen to
+ port 25 for Sendmail
+ and port 80 for Apache.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>Do not run Apache as "nobody". This will require very lax permissions in your Bugzilla directories.
+ Run it, instead, as a user with a name, set via your httpd.conf file.</PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Ensure you have adequate access controls for $BUGZILLA_HOME/data/, $BUGZILLA_HOME/localconfig,
+ and $BUGZILLA_HOME/shadow directories.
+ The localconfig file stores your "bugs" user password,
+ which would be terrible to have in the hands
+ of a criminal. Also some files under $BUGZILLA_HOME/data store sensitive information.
+ </PARA>
+ <PARA>
+ On Apache, you can use .htaccess files to protect access to these directories, as outlined
+ in <ULINK URL="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">Bug 57161</ULINK> for the
+ localconfig file, and <ULINK URL="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">
+ Bug 65572</ULINK> for adequate protection in your data/ and shadow/ directories.
+ </PARA>
+ <PARA>
+ Note the instructions which follow are Apache-specific. If you use IIS, Netscape, or other
+ non-Apache web servers, please consult your system documentation for how to secure these
+ files from being transmitted to curious users.
+ </PARA>
+ <PARA>
+ Place the following text into a file named ".htaccess", readable by your web server,
+ in your $BUGZILLA_HOME/data directory.
+ <LITERALLAYOUT>
+ &lt;Files comments&gt;
+ allow from all
+ &lt;/Files&gt;
+ deny from all
+ </LITERALLAYOUT>
+ </PARA>
+ <PARA>
+ Place the following text into a file named ".htaccess", readable by your web server,
+ in your $BUGZILLA_HOME/ directory.
+ <LITERALLAYOUT>
+ &lt;Files localconfig&gt;
+ deny from all
+ &lt;/Files&gt;
+ allow from all
+ </LITERALLAYOUT>
+ </PARA>
+ <PARA>
+ Place the following text into a file named ".htaccess", readable by your web server,
+ in your $BUGZILLA_HOME/shadow directory.
+ <LITERALLAYOUT>
+ deny from all
+ </LITERALLAYOUT>
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ </SECTION>
+</CHAPTER>
- <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 &lt; 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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:upper
+sgml-minimize-attributes:nil
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-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
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/en/xml/installation.xml b/docs/en/xml/installation.xml
index 0373ab72c..03ff0bd8d 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,2040 +1,1322 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ -->
-<chapter id="installing-bugzilla">
- <title>Installing Bugzilla</title>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
- <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://&lt;your-machine&gt;/</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 "&lt;modulename&gt;"'</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>&lt;packagename&gt;-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>
+<CHAPTER id="installation">
+ <TITLE>Installing Bugzilla</TITLE>
- <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>
+ <SECTION id="README.unix">
+ <TITLE>UNIX Installation</TITLE>
+ <SECTION>
+ <TITLE>ERRATA</TITLE>
+ <NOTE>
+ <PARA>
+ If you are installing Bugzilla on S.u.S.e. Linux, or some other
+ distributions with "paranoid" security options, it is possible
+ that the checksetup.pl script may fail with the error:
+ <ERRORNAME>cannot chdir(/var/spool/mqueue): Permission denied</ERRORNAME>
+ This is because your
+ /var/spool/mqueue directory has a mode of "drwx------". Type
+ <COMMAND>chmod 755 /var/spool/mqueue</COMMAND> as root to fix this problem.
+ </PARA>
+ </NOTE>
- <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>
+ <NOTE>
+ <PARA>
+ Release Notes for Bugzilla 2.12 are available at docs/rel_notes.txt
+ </PARA>
+ </NOTE>
- <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>
+ <NOTE>
+ <PARA>
+ The preferred documentation for Bugzilla is available in docs/, with
+ a variety of document types available. Please refer to these documents when
+ installing, configuring, and maintaining your Bugzilla installation.
+ </PARA>
+ </NOTE>
- <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>
+ <WARNING>
+ <PARA>
+ Bugzilla is not a package where you can just plop it in a directory,
+ twiddle a few things, and you're off. Installing Bugzilla assumes you
+ know your variant of UNIX or Microsoft Windows well, are familiar with the
+ command line, and are comfortable compiling and installing a plethora
+ of third-party utilities. To install Bugzilla on Win32 requires
+ fair Perl proficiency, and if you use a webserver other than Apache you
+ should be intimately familiar with the security mechanisms and CGI
+ environment thereof.
+ </PARA>
+ </WARNING>
- <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&gt;</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&gt;</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&gt;</prompt> use <replaceable>$bugs_db</replaceable>
- <prompt>mysql&gt;</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>
+ <WARNING>
+ <PARA>
+ Bugzilla has not undergone a complete security review. Security holes
+ may exist in the code. Great care should be taken both in the installation
+ and usage of this software. Carefully consider the implications of
+ installing other network services with Bugzilla.
+ </PARA>
+ </WARNING>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Step-by-step Install</TITLE>
+ <SECTION>
+ <TITLE>Introduction</TITLE>
+ <PARA>
+ Installation of bugzilla is pretty straightforward, particularly if your
+ machine already has MySQL and the MySQL-related perl packages installed.
+ If those aren't installed yet, then that's the first order of business. The
+ other necessary ingredient is a web server set up to run cgi scripts.
+ While using Apache for your webserver is not required, it is recommended.
+ </PARA>
+
+ <PARA>
+ Bugzilla has been successfully installed under Solaris, Linux, and
+ Win32. The peculiarities of installing on Win32 (Win98+/NT/2K) are not
+ included in this section of the Guide; please check out the "Win32 Installation Instructions"
+ for further advice on getting Bugzilla to work on Microsoft Windows.
+ </PARA>
+
+ <PARA>
+ The Bugzilla Guide is contained in the "docs/" folder. It is available
+ in plain text (docs/txt), HTML (docs/html), or SGML source (docs/sgml).
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Installing the Prerequisites</TITLE>
+
+ <PARA>
+ The software packages necessary for the proper running of bugzilla are:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ MySQL database server and the mysql client (3.22.5 or greater)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Perl (5.004 or greater)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DBI Perl module
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Data::Dumper Perl module
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DBD::mySQL
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ TimeDate Perl module collection
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ GD perl module (1.8.3) (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Chart::Base Perl module (0.99c) (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DB_File Perl module (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ The web server of your choice. Apache is recommended.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ MIME::Parser Perl module (optional, for contrib/bug_email.pl interface)
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ <NOTE>
+ <PARA>
+ You must run Bugzilla on a filesystem that supports file locking via
+ flock(). This is necessary for Bugzilla to operate safely with multiple
+ instances.
+ </PARA>
+ </NOTE>
+ <WARNING>
+ <PARA>
+ It is a good idea, while installing Bugzilla, to ensure it is not
+ <EMPHASIS>accessible</EMPHASIS> by other machines on the Internet.
+ Your machine may be vulnerable to attacks
+ while you are installing. In other words, ensure there is some kind of firewall between you
+ and the rest of the Internet. Many installation steps require an active Internet connection
+ to complete, but you must take care to ensure that at no point is your machine vulnerable
+ to an attack.
+ </PARA>
+ </WARNING>
+
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Installing MySQL Database</TITLE>
+ <PARA>
+ Visit MySQL homepage at http://www.mysql.org/ and grab the latest stable
+ release of the server. Both binaries and source are available and which
+ you get shouldn't matter. Be aware that many of the binary versions
+ of MySQL store their data files in /var which on many installations
+ (particularly common with linux installations) is part of a smaller
+ root partition. If you decide to build from sources you can easily set
+ the dataDir as an option to configure.
+ </PARA>
+ <PARA>
+ If you've installed from source or non-package (RPM, deb, etc.) binaries
+ you'll want to make sure to add mysqld to your init scripts so the server
+ daemon will come back up whenever your machine reboots.
+ You also may want to edit those init scripts, to make sure that
+ mysqld will accept large packets. By default, mysqld is set up to only
+ accept packets up to 64K long. This limits the size of attachments you
+ may put on bugs. If you add something like "-O max_allowed_packet=1M"
+ to the command that starts mysqld (or safe_mysqld), then you will be
+ able to have attachments up to about 1 megabyte.
+ </PARA>
+ <NOTE>
+ <PARA>
+ If you plan on running Bugzilla and MySQL on the same machine,
+ consider using the "--skip-networking" option in the init script.
+ This enhances security by preventing network access to MySQL.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Perl (5.004 or greater)</TITLE>
+ <PARA>
+ Any machine that doesn't have perl on it is a sad machine indeed. Perl
+ for *nix systems can be gotten in source form from http://www.perl.com.
+ </PARA>
+ <PARA>
+ Perl is now a far cry from the the single compiler/interpreter binary it
+ once was. It now includes a great many required modules and quite a
+ few other support files. If you're not up to or not inclined to build
+ perl from source, you'll want to install it on your machine using some
+ sort of packaging system (be it RPM, deb, or what have you) to ensure
+ a sane install. In the subsequent sections you'll be installing quite
+ a few perl modules; this can be quite ornery if your perl installation
+ isn't up to snuff.
+ </PARA>
+ <TIP>
+ <PARA>
+ You can skip the following Perl module installation
+ steps by installing "Bundle::Bugzilla" from CPAN, which includes them.
+ All Perl module installation steps require you have an active Internet
+ connection.
+ </PARA>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl -MCPAN -e 'install "Bundle::Bugzilla"'</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ <PARA>
+ Bundle::Bugzilla doesn't include GD, Chart::Base, or MIME::Parser,
+ which are not essential to a basic Bugzilla install. If installing
+ this bundle fails, you should install each module individually to
+ isolate the problem.
+ </PARA>
+ </TIP>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>DBI Perl Module</TITLE>
+ <PARA>
+ The DBI module is a generic Perl module used by other database related
+ Perl modules. For our purposes it's required by the MySQL-related
+ modules. As long as your Perl installation was done correctly the
+ DBI module should be a breeze. It's a mixed Perl/C module, but Perl's
+ MakeMaker system simplifies the C compilation greatly.
+ </PARA>
+ <PARA>
+ Like almost all Perl modules DBI can be found on the Comprehensive Perl
+ Archive Network (CPAN) at http://www.cpan.org. The CPAN servers have a
+ real tendency to bog down, so please use mirrors. The current location
+ at the time of this writing (02/17/99) can be found in Appendix A.
+ </PARA>
+ <PARA>
+ Quality, general Perl module installation instructions can be found on
+ the CPAN website, but the easy thing to do is to just use the CPAN shell
+ which does all the hard work for you.
+ </PARA>
+ <PARA>
+ To use the CPAN shell to install DBI:
+ <INFORMALEXAMPLE>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl -MCPAN -e 'install "DBI"'</COMMAND>
+ </COMPUTEROUTPUT>
+ <NOTE>
+ <PARA>Replace "DBI" with the name of whichever module you wish
+ to install, such as Data::Dumper, TimeDate, GD, etc.</PARA>
+ </NOTE>
+ </PARA>
+ </INFORMALEXAMPLE>
+ To do it the hard way:
+ <INFORMALEXAMPLE>
+ <PARA>
+ Untar the module tarball -- it should create its own directory
+ </PARA>
+ <PARA>
+ CD to the directory just created, and enter the following commands:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl Makefile.PL</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make test</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make install</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ If everything went ok that should be all it takes. For the vast
+ majority of perl modules this is all that's required.
+ </PARA>
+ </INFORMALEXAMPLE>
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Data::Dumper Perl Module</TITLE>
+ <PARA>
+ The Data::Dumper module provides data structure persistence for Perl
+ (similar to Java's serialization). It comes with later sub-releases of
+ Perl 5.004, but a re-installation just to be sure it's available won't
+ hurt anything.
+ </PARA>
+ <PARA>
+ Data::Dumper is used by the MySQL related Perl modules. It can be
+ found on CPAN (link in Appendix A) and can be installed by following
+ the same four step make sequence used for the DBI module.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>MySQL related Perl Module Collection</TITLE>
+ <PARA>
+ The Perl/MySQL interface requires a few mutually-dependent perl
+ modules. These modules are grouped together into the the
+ Msql-Mysql-modules package. This package can be found at CPAN.
+ After the archive file has been downloaded it should
+ be untarred.
+ </PARA>
+ <PARA>
+ The MySQL modules are all built using one make file which is generated
+ by running:
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl Makefile.pl</COMMAND>
+ </PARA>
+ <PARA>
+ The MakeMaker process will ask you a few questions about the desired
+ compilation target and your MySQL installation. For many of the questions
+ the provided default will be adequate.
+ </PARA>
+ <PARA>
+ When asked if your desired target is the MySQL or mSQL packages
+ selected the MySQL related ones. Later you will be asked if you wish
+ to provide backwards compatibility with the older MySQL packages; you
+ must answer YES to this question. The default will be no, and if you
+ select it things won't work later.
+ </PARA>
+ <PARA>
+ A host of 'localhost' should be fine and a testing user of 'test' and
+ a null password should find itself with sufficient access to run tests
+ on the 'test' database which MySQL created upon installation. If 'make
+ test' and 'make install' go through without errors you should be ready
+ to go as far as database connectivity is concerned.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>TimeDate Perl Module Collection</TITLE>
+ <PARA>
+ Many of the more common date/time/calendar related Perl modules have
+ been grouped into a bundle similar to the MySQL modules bundle. This
+ bundle is stored on the CPAN under the name TimeDate. A (hopefully
+ current) link can be found in Appendix A. The component module we're
+ most interested in is the Date::Format module, but installing all of them
+ is probably a good idea anyway. The standard Perl module installation
+ instructions should work perfectly for this simple package.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>GD Perl Module (1.8.3)</TITLE>
+ <PARA>
+ The GD library was written by Thomas Boutell a long while ago to
+ programatically generate images in C. Since then it's become almost a
+ defacto standard for programatic image construction. The Perl bindings
+ to it found in the GD library are used on a million web pages to generate
+ graphs on the fly. That's what bugzilla will be using it for so you'd
+ better install it if you want any of the graphing to work.
+ </PARA>
+ <PARA>
+ Actually bugzilla uses the Graph module which relies on GD itself,
+ but isn't that always the way with OOP. At any rate, you can find the
+ GD library on CPAN (link in Appendix "Required Software").
+ </PARA>
+ <NOTE>
+ <PARA>
+ The Perl GD library requires some other libraries that may or may not be
+ installed on your system, including "libpng" and "libgd". The full requirements
+ are listed in the Perl GD library README. Just realize that if compiling GD fails,
+ it's probably because you're missing a required library.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Chart::Base Perl Module (0.99c)</TITLE>
+ <PARA>
+ The Chart module provides bugzilla with on-the-fly charting
+ abilities. It can be installed in the usual fashion after it has been
+ fetched from CPAN where it is found as the Chart-x.x... tarball in a
+ directory to be listed in Appendix "Required Software". Note that as with the GD perl
+ module, only the specific versions listed above (or newer) will work. Earlier
+ versions used GIF's, which are no longer supported by the latest
+ versions of GD.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>DB_File Perl Module</TITLE>
+ <PARA>
+ DB_File is a module which allows Perl programs to make use of the facilities provided by
+ Berkeley DB version 1.x. This module is required by collectstats.pl which is used for
+ bug charting. If you plan to make use of bug charting, you must install this module.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>HTTP Server</TITLE>
+ <PARA>
+ You have a freedom of choice here - Apache, Netscape or any other
+ server on UNIX would do. You can easily run the web server on a different
+ machine than MySQL, but need to adjust the MySQL "bugs" user permissions
+ accordingly.
+ </PARA>
+ <PARA>
+ You'll want to make sure that your web server will run any file
+ with the .cgi extension as a cgi and not just display it. If you're using
+ apache that means uncommenting the following line in the srm.conf file:
+ <COMPUTEROUTPUT>AddHandler cgi-script .cgi</COMPUTEROUTPUT>
+ </PARA>
+ <PARA>
+ With apache you'll also want to make sure that within the access.conf
+ file the line:
+ <COMPUTEROUTPUT>
+ Options ExecCGI
+ </COMPUTEROUTPUT>
+ is in the stanza that covers the directories you intend to put the bugzilla
+ .html and .cgi files into.
+ </PARA>
+ <PARA>
+ If you are using a newer version of Apache, both of the above lines will be
+ (or will need to be) in the httpd.conf file, rather than srm.conf or
+ access.conf.
+ </PARA>
+ <WARNING>
+ <PARA>
+ There are two critical directories and a file that should not be a served by
+ the HTTP server. These are the 'data' and 'shadow' directories and the
+ 'localconfig' file. You should configure your HTTP server to not serve
+ content from these files. Failure to do so will expose critical passwords
+ and other data. Please see your HTTP server configuration manual on how
+ to do this. If you use quips (at the top of the buglist pages) you will want
+ the 'data/comments' file to still be served. This file contains those quips.
+ </PARA>
+ </WARNING>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Installing the Bugzilla Files</TITLE>
+ <PARA>
+ You should untar the Bugzilla files into a directory that you're
+ willing to make writable by the default web server user (probably
+ 'nobody'). You may decide to put the files off of the main web space
+ for your web server or perhaps off of /usr/local with a symbolic link
+ in the web space that points to the bugzilla directory. At any rate,
+ just dump all the files in the same place (optionally omitting the CVS
+ directories if they were accidentally tarred up with the rest of Bugzilla)
+ and make sure you can access the files in that directory through your
+ web server.
+ </PARA>
+ <TIP>
+ <PARA>
+ HINT: If you symlink the bugzilla directory into your Apache's
+ HTML heirarchy, you may receive "Forbidden" errors unless you
+ add the "FollowSymLinks" directive to the &lt;Directory&gt; entry
+ for the HTML root.
+ </PARA>
+ </TIP>
+ <PARA>
+ Once all the files are in a web accessible directory, make that
+ directory writable by your webserver's user (which may require just
+ making it world writable). This is a temporary step until you run
+ the post-install "checksetup.pl" script, which locks down your
+ installation.
+ </PARA>
+ <PARA>
+ Lastly, you'll need to set up a symbolic link from /usr/bonsaitools/bin
+ to the correct location of your perl executable (probably /usr/bin/perl).
+ Otherwise you must hack all the .cgi files to change where they look
+ for perl. To make future upgrades easier, you should use the symlink
+ approach.
+ <TIP>
+ <PARA>
+ If you don't have root access to set this symlink up, check out the
+ "setperl.csh" utility, listed in the Patches section of this
+ Guide. It will change the path to perl in all your Bugzilla files for
+ you.
+ </PARA>
+ </TIP>
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Setting Up the MySQL Database</TITLE>
+ <PARA>
+ After you've gotten all the software installed and working you're ready
+ to start preparing the database for its life as a the back end to a high
+ quality bug tracker.
+ </PARA>
+ <PARA>
+ First, you'll want to fix MySQL permissions to allow access from
+ Bugzilla. For the purpose of this Installation section, the Bugzilla username
+ will be "bugs", and will have minimal permissions. Bugzilla has
+ not undergone a thorough security audit. It may be possible for
+ a system cracker to somehow trick Bugzilla into executing a command
+ such as "; DROP DATABASE mysql".
+ </PARA>
+ <PARA>
+ That would be bad.
+ </PARA>
+ <PARA>
+ Give the MySQL root user a password. MySQL passwords are
+ limited to 16 characters.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>mysql -u root mysql</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>
+ UPDATE user SET Password=PASSWORD ('new_password')
+ WHERE user='root';
+ </COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>FLUSH PRIVILEGES;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ From this point on, if you need to access MySQL as the
+ MySQL root user, you will need to use "mysql -u root -p" and
+ enter your new_password. Remember that MySQL user names have
+ nothing to do with Unix user names (login names).
+ </PARA>
+ <PARA>
+ Next, we create the "bugs" user, and grant sufficient
+ permissions for checksetup.pl, which we'll use later, to work
+ its magic. This also restricts the "bugs" user to operations
+ within a database called "bugs", and only allows the account
+ to connect from "localhost". Modify it to reflect your setup
+ if you will be connecting from another machine or as a different
+ user.
+ </PARA>
+ <PARA>
+ Remember to set bugs_password to some unique password.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
+ ALTER,CREATE,DROP,REFERENCES
+ ON bugs.* TO bugs@localhost
+ IDENTIFIED BY 'bugs_password';</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>
+ mysql>
+ </PROMPT>
+ <COMMAND>
+ FLUSH PRIVILEGES;
+ </COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ Next, run the magic checksetup.pl script. (Many thanks to Holger
+ Schurig &lt;holgerschurig@nikocity.de&gt; for writing this script!)
+ It will make sure Bugzilla files and directories have reasonable
+ permissions, set up the "data" directory, and create all the MySQL
+ tables.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>./checksetup.pl</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ The first time you run it, it will create a file called "localconfig".
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Tweaking "localconfig"</TITLE>
+ <PARA>
+ This file contains a variety of settings you may need to tweak including
+ how Bugzilla should connect to the MySQL database.
+ </PARA>
+ <PARA>
+ The connection settings include:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ server's host: just use "localhost" if the MySQL server is
+ local
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ database name: "bugs" if you're following these directions
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ MySQL username: "bugs" if you're following these directions
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Password for the "bugs" MySQL account above
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ <PARA>
+ Once you are happy with the settings, re-run checksetup.pl. On this
+ second run, it will create the database and an administrator account
+ for which you will be prompted to provide information.
+ </PARA>
+ <PARA>
+ When logged into an administrator account once Bugzilla is running,
+ if you go to the query page (off of the bugzilla main menu), you'll
+ find an 'edit parameters' option that is filled with editable treats.
+ </PARA>
+ <PARA>
+ Should everything work, you should have a nearly empty copy of the bug
+ tracking setup.
+ </PARA>
+ <PARA>
+ The second time around, checksetup.pl will stall if it is on a
+ filesystem that does not fully support file locking via flock(), such as
+ NFS mounts. This support is required for Bugzilla to operate safely with
+ multiple instances. If flock() is not fully supported, it will stall at:
+ <ERRORCODE>Now regenerating the shadow database for all bugs.</ERRORCODE>
+ <NOTE>
+ <PARA>
+ The second time you run checksetup.pl, it is recommended you be the same
+ user as your web server runs under, and that you be sure you have set the
+ "webservergroup" parameter in localconfig to match the web server's group
+ name, if any. Under some systems, otherwise, checksetup.pl will goof up
+ your file permissions and make them unreadable to your web server.
+ </PARA>
+ </NOTE>
+ </PARA>
+ <NOTE>
+ <PARA>
+ The checksetup.pl script is designed so that you can run it at any time
+ without causing harm. You should run it after any upgrade to Bugzilla.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Setting Up Maintainers Manuall (Optional)</TITLE>
+ <PARA>
+ If you want to add someone else to every group by hand, you can do it
+ by typing the appropriate MySQL commands. Run '<COMPUTEROUTPUT>
+ mysql -u root -p bugs</COMPUTEROUTPUT>'
+ (you may need different parameters, depending on your security settings
+ according to section 3, above). Then:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>update profiles set groupset=0x7fffffffffffffff
+ where login_name = 'XXX';</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ replacing XXX with the Bugzilla email address.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>The Whining Cron (Optional)</TITLE>
+ <PARA>
+ By now you've got a fully functional bugzilla, but what good are bugs
+ if they're not annoying? To help make those bugs more annoying you can
+ set up bugzilla's automatic whining system. This can be done by adding
+ the following command as a daily crontab entry (for help on that see that
+ crontab man page):
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <COMMAND>cd &lt;your-bugzilla-directory&gt; ; ./whineatnews.pl</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Bug Graphs (Optional)</TITLE>
+ <PARA>
+ As long as you installed the GD and Graph::Base Perl modules you might
+ as well turn on the nifty bugzilla bug reporting graphs.
+ </PARA>
+ <PARA>
+ Add a cron entry like this to run collectstats daily at 5 after midnight:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>crontab -e</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ 5 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./collectstats.pl
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ After two days have passed you'll be able to view bug graphs from the
+ Bug Reports page.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Securing MySQL</TITLE>
+ <PARA>
+ If you followed the README for setting up your "bugs" and "root" user in
+ MySQL, much of this should not apply to you. If you are upgrading
+ an existing installation of Bugzilla, you should pay close attention
+ to this section.
+ </PARA>
+ <PARA>
+ Most MySQL installs have "interesting" default security parameters:
+ <SIMPLELIST>
+ <MEMBER>mysqld defaults to running as root</MEMBER>
+ <MEMBER>it defaults to allowing external network connections</MEMBER>
+ <MEMBER>it has a known port number, and is easy to detect</MEMBER>
+ <MEMBER>it defaults to no passwords whatsoever</MEMBER>
+ <MEMBER>it defaults to allowing "File_Priv"</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ This means anyone from anywhere on the internet can not only drop the
+ database with one SQL command, and they can write as root to the system.
+ </PARA>
+ <PARA>
+ To see your permissions do:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>mysql -u root -p</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>use mysql;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>show tables;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>select * from user;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>select * from db;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ To fix the gaping holes:
+ <SIMPLELIST>
+ <MEMBER>DELETE FROM user WHERE User='';</MEMBER>
+ <MEMBER>UPDATE user SET Password=PASSWORD('new_password') WHERE user='root';</MEMBER>
+ <MEMBER> FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ If you're not running "mit-pthreads" you can use:
+ <SIMPLELIST>
+ <MEMBER>GRANT USAGE ON *.* TO bugs@localhost;</MEMBER>
+ <MEMBER>GRANT ALL ON bugs.* TO bugs@localhost;</MEMBER>
+ <MEMBER>REVOKE DROP ON bugs.* FROM bugs@localhost;</MEMBER>
+ <MEMBER>FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ With "mit-pthreads" you'll need to modify the "globals.pl" Mysql->Connect
+ line to specify a specific host name instead of "localhost", and accept
+ external connections:
+ <SIMPLELIST>
+ <MEMBER>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ Consider also:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ Turning off external networking with "--skip-networking",
+ unless you have "mit-pthreads", in which case you can't.
+ Without networking, MySQL connects with a Unix domain socket.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ using the --user= option to mysqld to run it as an unprivileged
+ user.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ starting MySQL in a chroot jail
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ running the httpd in a "chrooted" jail
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ making sure the MySQL passwords are different from the OS
+ passwords (MySQL "root" has nothing to do with system "root").
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ running MySQL on a separate untrusted machine
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ making backups ;-)
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ </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>
+ <SECTION>
+ <TITLE>Installation General Notes</TITLE>
+ <SECTION>
+ <TITLE>Modifying Your Running System</TITLE>
+ <PARA>
+ Bugzilla optimizes database lookups by storing all relatively static
+ information in the versioncache file, located in the data/ subdirectory
+ under your installation directory (we said before it needs to be writable,
+ right?!)
+ </PARA>
+ <PARA>
+ If you make a change to the structural data in your database (the
+ versions table for example), or to the "constants" encoded in
+ defparams.pl, you will need to remove the cached content from the data
+ directory (by doing a "rm data/versioncache"), or your changes won't show
+ up!
+ </PARA>
+ <PARA>
+ That file gets automatically regenerated whenever it's more than an
+ hour old, so Bugzilla will eventually notice your changes by itself, but
+ generally you want it to notice right away, so that you can test things.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Upgrading From Previous Versions</TITLE>
+ <PARA>
+ The developers of Bugzilla are constantly adding new tables, columns and
+ fields. You'll get SQL errors if you just update the code. The strategy
+ to update is to simply always run the checksetup.pl script whenever
+ you upgrade your installation of Bugzilla. If you want to see what has
+ changed, you can read the comments in that file, starting from the end.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>UNIX Installation Instructions History</TITLE>
+ <PARA>
+ This document was originally adapted from the Bonsai installation
+ instructions by Terry Weissman &lt;terry@mozilla.org&gt;.
+ </PARA>
+ <PARA>
+ The February 25, 1999 re-write of this page was done by Ry4an Brase
+ &lt;ry4an@ry4an.org&gt;, with some edits by Terry Weissman, Bryce Nesbitt,
+ Martin Pool, & Dan Mosedale (But don't send bug reports to them!
+ Report them using bugzilla, at http://bugzilla.mozilla.org/enter_bug.cgi ,
+ project Webtools, component Bugzilla).
+ </PARA>
+ <PARA>
+ This document was heavily modified again Wednesday, March 07 2001 to
+ reflect changes for Bugzilla 2.12 release by Matthew P. Barnson. The
+ securing MySQL section should be changed to become standard procedure
+ for Bugzilla installations.
+ </PARA>
+ <PARA>
+ Finally, the README in its entirety was marked up in SGML and included into
+ the Guide on April 24, 2001.
+ </PARA>
+ <PARA>
+ Comments from people using this Guide for the first time are particularly welcome.
+ </PARA>
+ </SECTION>
+ </SECTION>
+
+ </SECTION>
+ </SECTION>
+
+ <SECTION id="README.windows">
+ <TITLE>Win32 (Win98+/NT/2K) Installation</TITLE>
+ <PARA>
+ These directions have <EMPHASIS>not</EMPHASIS> been extensively tested.
+ We need testers! Please try these out and post any changes to the
+ newsgroup.
+ </PARA>
+ <SECTION id="ntverified">
+ <TITLE>Win32 Installation: Step-by-step</TITLE>
+ <NOTE>
+ <PARA>
+ You should be familiar with, and cross-reference, the UNIX README
+ while performing your Win32 installation. Unfortunately, Win32
+ directions are not yet as detailed as those for UNIX.
+ </PARA>
+ <PARA>
+ The <EMPHASIS>most critical</EMPHASIS> difference for Win32 users is
+ the lack of support for a crypt() function in MySQL for Windows. It does not
+ have it! All ENCRYPT statements must be modified.
+ </PARA>
+ </NOTE>
+
+ <PROCEDURE>
+ <STEP>
+ <PARA>
+ Install <ULINK URL="http://www.apache.org/">Apache Web Server</ULINK>
+ for Windows.
+ </PARA>
+ <NOTE>
+ <PARA>
+ You may also use Internet Information Server or Personal Web
+ Server for this purpose. However, setup is slightly more
+ difficult. If ActivePerl doesn't seem to handle your file
+ associations correctly (for .cgi and .pl files), please
+ consult the FAQ, in the "Win32" section.
+ </PARA>
+ <PARA>
+ If you are going to use IIS, if on Windows NT you must be updated
+ to at least Service Pack 4.
+ </PARA>
+ </NOTE>
+ </STEP>
+ <STEP>
+ <PARA>
+ Install <ULINK URL="http://www.activestate.com/">ActivePerl</ULINK>
+ </PARA>
+ <PARA>
+ Please also check the following links to fully understand the status
+ of ActivePerl on Win32:
+ <ULINK URL="http://language.perl.com/newdocs/pod/perlport.html">
+ Perl Porting</ULINK>, and
+ <ULINK URL="http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html">
+ Hixie Click Here</ULINK>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Use ppm from your perl\bin directory to install the following packs: DBI,
+ DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, and GD. You may need
+ to extract them from .zip format using Winzip or other unzip program first.
+ These additional ppm modules can be downloaded from ActiveState.
+ </PARA>
+ <PARA>
+ The syntax for ppm is:
+ <COMPUTEROUTPUT>
+ <PROMPT>C:> </PROMPT><COMMAND>ppm install &lt;module&gt;.ppd</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ <PARA>
+ You can find ActiveState ppm modules at
+ <ULINK URL="http://www.activestate.com/PPMPackages/5.6plus/">
+ http://www.activestate.com/PPMPackages/5.6plus</ULINK>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Download and install the Windows GNU tools from
+ <ULINK URL="http://www.cygwin.com/">www.cygwin.com</ULINK>.
+ Make sure the GNU utilities are in your $PATH.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Install MySQL for NT.
+ <NOTE>
+ <PARA>
+ Your configuration file for MySQL <EMPHASIS>must</EMPHASIS> be named C:\MY.CNF.
+ </PARA>
+ </NOTE>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ Setup MySQL
+ </PARA>
+ <SUBSTEPS>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>C:> </PROMPT>
+ <COMMAND>C:\mysql\bin\mysql -u root mysql</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>DELETE FROM user WHERE Host='localhost' AND User='';</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>UPDATE user SET Password=PASSWORD ('new_password')
+ WHERE user='root';</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>GRANT SELECT, INSERT, UPDATE, DELETE,
+ INDEX, ALTER, CREATE, DROP, REFERENCES
+ ON bugs.* to bugs@localhost
+ IDENTIFIED BY 'bugs_password';</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>FLUSH PRIVILEGES;</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>create database bugs;</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>exit</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>C:></PROMPT>
+ <COMMAND>C:\mysql\bin\mysqladmin -u root -p reload</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </STEP>
+ </SUBSTEPS>
+ </STEP>
+
+ <STEP>
+ <PARA>
+ Configure Bugzilla. For Win32, this involves editing "defparams.pl"
+ and "localconfig" to taste. Running "checksetup.pl" should create
+ localconfig for you. Note that getgrnam() doesn't work, and should be
+ deleted. Change this line:
+ "my $webservergid = getgrnam($my_webservergroup); "
+ to
+ "my $webservergid = $my_webservergroup; "
+ </PARA>
+ </STEP>
+
+ <STEP>
+ <NOTE>
+ <PARA>
+ There are several alternatives to Sendmail that will work on Win32.
+ The one mentioned here is a <EMPHASIS>suggestion</EMPHASIS>, not
+ a requirement. Some other mail packages that can work include
+ <ULINK URL="http://www.blat.net/">BLAT</ULINK>,
+ <ULINK URL="http://www.geocel.com/windmail/">Windmail</ULINK>,
+ <ULINK URL="http://www.dynamicstate.com/">Mercury Sendmail</ULINK>,
+ and the CPAN Net::SMTP Perl module (available in .ppm).
+ Every option requires some hacking of the Perl scripts for Bugzilla
+ to make it work. The option here simply requires the least.
+ </PARA>
+ </NOTE>
+ <PARA>
+ Download NTsendmail, available from<ULINK URL="http://www.ntsendmail.com/">
+ www.ntsendmail.com</ULINK>. In order for it to work, you must set up some
+ new environment variables (detailed on the ntsendmail home page). Figuring
+ out where to put those variables is left as an exercise for the reader.
+ You must have a "real" mail server which allows you to relay off it
+ in your $ENV{"NTsendmail"} (which you should probably place in globals.pl)
+ </PARA>
+ <PARA>
+ Once downloaded and installed, modify all open(SENDMAIL) calls to open
+ "| c:\ntsendmail\ntsendmail -t" instead of "|/usr/lib/sendmail -t".
+ </PARA>
+ <NOTE>
+ <PARA>
+ We need someone to test this and make sure this works as advertised.
+ </PARA>
+ </NOTE>
+ </STEP>
+ <STEP>
+ <PARA>
+ Modify globals.pl and CGI.pl to remove the word "encrypt".
+ </PARA>
+ <NOTE>
+ <PARA>
+ I'm not sure this is all that is involved to remove crypt. Any
+ NT Bugzilla hackers want to pipe up?
+ </PARA>
+ </NOTE>
+ </STEP>
+ <STEP>
+ <PARA>
+ Change all references to "processmail" to "processmail.pl" in
+ all files, and rename "processmail" to "processmail.pl"
+ </PARA>
+ <NOTE>
+ <PARA>
+ I really think this may be a change we want to make for
+ main-tree Bugzilla. It's painless for the UNIX folks,
+ and will make the Win32 people happier.
+ </PARA>
+ </NOTE>
+ </STEP>
+ <STEP>
+ <PARA>
+ Modify the path to perl on the first line (#!) of all files
+ to point to your Perl installation, and
+ add "perl" to the beginning of all Perl system calls that
+ use a perl script as an argument. This may take you a while.
+ There is a "setperl.pl" utility to speed part of this procedure,
+ available in the "Patches and Utilities" section of The Bugzilla Guide.
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ In processmail.pl, add "binmode(HANDLE)" before all read() calls.
+ This may not be necessary, but in some cases the read() under
+ Win32 doesn't count the EOL's without using a binary read().
+ </PARA>
+ </STEP>
+ </PROCEDURE>
+
+ </SECTION>
+
+ <SECTION id="addlwintips">
+ <TITLE>Additional Windows Tips</TITLE>
+ <TIP>
+ <PARA>
+ From Andrew Pearson:
+ <BLOCKQUOTE>
+ <PARA>
+ "You can make Bugzilla work with Personal Web Server for
+ Windows 98 and higher, as well as for IIS 4.0. Microsoft has
+ information available at
+ <ULINK URL=" http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP">
+ http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP</ULINK>
+ </PARA>
+ <PARA>
+ Basically you need to add two String Keys in the
+ registry at the following location:
+ </PARA>
+ <PARA>
+ HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
+ </PARA>
+ <PARA>
+ The keys should be called ".pl" and ".cgi", and both
+ should have a value something like:
+ <COMMAND>c:/perl/bin/perl.exe "%s" "%s"</COMMAND>
+ </PARA>
+ <PARA>
+ The KB article only talks about .pl, but it goes into
+ more detail and provides a perl test script.
+ </PARA>
+ </BLOCKQUOTE>
+ </PARA>
+ </TIP>
+ <TIP>
+ <PARA>"Brian" had this to add, about upgrading to Bugzilla 2.12 from previous versions:</PARA>
+ <BLOCKQUOTE>
+ <PARA>
+ Hi - I am updating bugzilla to 2.12 so I can tell you what I did (after I
+ deleted the current dir and copied the files in).
+ </PARA>
+ <PARA>
+ In checksetup.pl, I did the following...
+ </PARA>
+ <PROCEDURE>
+ <STEP>
+ <PROGRAMLISTING>
+my $webservergid = getgrnam($my_webservergroup);
+ </PROGRAMLISTING>
+ <PARA>to</PARA>
+ <PROGRAMLISTING>
+my $webservergid = 'Administrators'
+ </PROGRAMLISTING>
+ </STEP>
+ <STEP>
+ <PARA>
+ I then ran checksetup.pl
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I removed all the encrypt()
+ <EXAMPLE>
+ <TITLE>Removing encrypt() for Windows NT installations</TITLE>
+ <PARA>
+ Replace this:
+ <PROGRAMLISTING>
+SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . ", " .
+ SqlQuote(substr($realcryptpwd, 0, 2)) . ")");
+my $enteredcryptpwd = FetchOneColumn();
+ </PROGRAMLISTING>
+ with this:
+ <PROGRAMLISTING>
+my $enteredcryptpwd = $enteredpwd
+ </PROGRAMLISTING>
+ in cgi.pl.
+ </PARA>
+ </EXAMPLE>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I renamed processmail to processmail.pl
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I altered the sendmail statements to windmail:
+ <PROGRAMLISTING>
+open SENDMAIL, "|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t > mail.log";
+ </PROGRAMLISTING>
+ </PARA>
+ <PARA>
+ The quotes around the dir is for the spaces. mail.log is for the output
+ </PARA>
+ </STEP>
+ </PROCEDURE>
+ </BLOCKQUOTE>
+ </TIP>
+ </SECTION>
+ </SECTION>
+</CHAPTER>
- <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>&lt;Directory&gt;</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>
- &lt;Directory /var/www/html/bugzilla&gt;
- AddHandler cgi-script .cgi
- Options +Indexes +ExecCGI
- DirectoryIndex index.cgi
- AllowOverride Limit
- &lt;/Directory&gt;
- </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>&lt;Directory /var/www/html/&gt;</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>&lt;Directory&gt;</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 &lt;Directory&gt; 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://&lt;yourdomainname&gt;/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>
-&lt;full path to perl.exe &gt;\perl.exe -x&lt;full path to Bugzilla&gt; -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://&lt;your-bugzilla-server&gt;/</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 &lt;your-bugzilla-directory&gt; ; ./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 &lt;your-bugzilla-directory&gt;</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 &lt;your-bugzilla-directory&gt; ; ./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 &lt;your-bugzilla-directory&gt; ; ./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>&lt;VirtualHost&gt;</computeroutput> section for your
- Bugzilla, or in the <computeroutput>&lt;Directory&gt;</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.&lt;PROJECT&gt;</filename> in the same location as
- the default one (<filename>localconfig</filename>). It also checks for
- customized templates in a directory named
- <filename>&lt;PROJECT&gt;</filename> in the same location as the
- default one (<filename>template/&lt;langcode&gt;</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>
-&lt;VirtualHost 212.85.153.228:80&gt;
- ServerName foo.bar.baz
- SetEnv PROJECT foo
- Alias /bugzilla /var/www/bugzilla
-&lt;/VirtualHost&gt;
-</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&gt; <command>ppm install &lt;module name&gt;</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 &amp; 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 &amp;</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 &amp;&amp; make test &amp;&amp; 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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:upper
+sgml-minimize-attributes:nil
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-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
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/en/xml/integration.xml b/docs/en/xml/integration.xml
index 485a03dcd..74ec817f5 100644
--- a/docs/en/xml/integration.xml
+++ b/docs/en/xml/integration.xml
@@ -1,120 +1,75 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" >
+
<!-- Keep these tools listings in alphabetical order please. -MPB -->
-<section id="integration">
+
+<chapter id="integration">
<title>Integrating Bugzilla with Third-Party Tools</title>
- <section id="bonsai"
- xreflabel="Bonsai, the Mozilla automated CVS management system">
+ <section id="bonsai">
<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>
+ <para>We need Bonsai integration information.</para>
</section>
- <section id="cvs" xreflabel="CVS, the Concurrent Versioning System">
+ <section id="cvs">
<title>CVS</title>
+ <para>We need CVS integration information</para>
+ </section>
- <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.
+ <section id="scm">
+ <title>Perforce SCM</title>
+ <para>
+ Richard Brooksby created a Perforce integration tool for Bugzilla and TeamTrack.
+ You can find the main project page at
+ <ulink url="http://www.ravenbrook.com/project/p4dti/">
+ http://www.ravenbrook.com/project/p4dti</ulink>. "p4dti" 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">
+ http://public.perforce.com/public/perforce/p4dti/index.html</ulink>.
</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>
+ Integration of Perforce with Bugzilla, once patches are applied, is fairly seamless. However,
+ p4dti is a patch against the Bugzilla 2.10 release, not the current 2.12 release. I anticipate
+ patches for 2.12 will be out shortly. Check the project page regularly for updates, or
+ take the given patches and patch it manually. 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>
-
- <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>
+ Right now, there is no way to synchronize the Bug ID and the Perforce Transaction Number, or
+ to change the Bug ID to read (PRODUCT).bugID unless you hack it in. Additionally, if you
+ have synchronization problems, the easiest way to avoid them is to only put the bug
+ information, comments, etc. into Bugzilla, and not into the Perforce change records.
+ They will link anyway; merely reference the bug ID fixed in your change description,
+ and put a comment into Bugzilla
+ giving the change ID that fixed the Bugzilla bug. It's a process issue, not a technology
+ question.
</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 id="tinderbox">
+ <title>Tinderbox</title>
+ <para>We need Tinderbox integration information</para>
</section>
- <section id="tinderbox"
- xreflabel="Tinderbox, the Mozilla automated build management system">
- <title>Tinderbox/Tinderbox2</title>
+</chapter>
- <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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
sgml-general-insert-case:lower
-sgml-indent-data:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
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/en/xml/patches.xml b/docs/en/xml/patches.xml
index 12efb0ca4..8d7a72682 100644
--- a/docs/en/xml/patches.xml
+++ b/docs/en/xml/patches.xml
@@ -1,131 +1,237 @@
-<!-- <!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>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<appendix id="patches">
+ <title>Useful Patches and Utilities for Bugzilla</title>
+
+<section id="setperl">
+ <title>The setperl.csh Utility</title>
+ <para>
+ You can use the "setperl.csh" utility to quickly and easily
+ change the path to perl on all your Bugzilla files.
+ This is a C-shell script; if you do not have "csh" or "tcsh" in the search
+ path on your system, it will not work!
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Download the "setperl.csh" utility to your Bugzilla
+ directory and make it executable.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>cd /your/path/to/bugzilla</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>wget -O setperl.csh 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>chmod u+x setperl.csh</command>
+ </computeroutput>
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>
+ Prepare (and fix) Bugzilla file permissions.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>chmod u+w *</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>chmod u+x duplicates.cgi</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>chmod a-x bug_status.html</command>
+ </computeroutput>
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>
+ Run the script:
+ </para>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>./setperl.csh /your/path/to/perl</command>
+ </computeroutput>
+<example>
+ <title>Using Setperl to set your perl path</title>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>./setperl.csh /usr/bin/perl</command>
+ </computeroutput>
+ </para>
+ </example>
+ </para>
+ </step>
+ </procedure>
+ </section>
<section id="cmdline">
- <title>Command-line Search Interface</title>
-
+ <title>Command-line Bugzilla Queries</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>.
+ Users can query Bugzilla from the command line using
+ this suite of utilities.
</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>.
+ The query.conf file contains the mapping from options to field
+ names and comparison types. Quoted option names are "grepped" for, so
+ it should be easy to edit this file. Comments (#) have no effect; you
+ must make sure these lines do not contain any quoted "option"
</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>.
+ buglist is a shell script which submits a Bugzilla query and writes the
+ resulting HTML page to stdout. It supports both short options,
+ (such as "-Afoo" or "-Rbar") and long options (such as
+ "--assignedto=foo" or "--reporter=bar"). If the first character
+ of an option is not "-", it is treated as if it were prefixed
+ with "--default=".
</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.
+ The columlist is taken from the COLUMNLIST environment variable.
+ This is equivalent to the "Change Columns" option when you list
+ bugs in buglist.cgi. If you have already used Bugzilla, use
+ <command>grep COLUMLIST ~/.netscape/cookies</command> 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>
+ bugs is a simple shell script which calls buglist and extracts
+ the bug numbers from the output. Adding the prefix
+ "http://bugzilla.mozilla.org/buglist.cgi?bug_id="
turns the bug list into a working link if any bugs are found.
- Counting bugs is easy. Pipe the results through
+ 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
+ Akkana says she has good results piping buglist output through
<command>w3m -T text/html -dump</command>
</para>
-
+ <procedure>
+ <step>
+ <para>
+ Download three files:
+ </para>
+ <substeps>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash$</prompt>
+ <command>wget -O query.conf 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash$</prompt>
+ <command>wget -O buglist 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'</command>
+ </computeroutput>
+ </para>
+ </step>
+ <step>
+ <para>
+ <computeroutput>
+ <prompt>bash#</prompt>
+ <command>wget -O bugs 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command>
+ </computeroutput>
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>
+ Make your utilities executable:
+ <computeroutput>
+ <prompt>bash$</prompt>
+ <command>chmod u+x buglist bugs</command>
+ </computeroutput>
+ </para>
+ </step>
+ </procedure>
</section>
- <section id="cmdline-bugmail">
- <title>Command-line 'Send Unsent Bug-mail' tool</title>
-
+ <section id="quicksearch">
+ <title>The Quicksearch Utility</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.
+ Quicksearch is a new, experimental feature of the 2.12 release.
+ It consist of two Javascript files, "quicksearch.js" and "localconfig.js",
+ and two documentation files, "quicksearch.html" and "quicksearchhack.html"
</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.
+ The index.html page has been updated to include the QuickSearch text box.
</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.
+ To take full advantage of the query power, the Bugzilla maintainer must
+ edit "localconfig.js" according to the value sets used in the local installation.
+ </para>
+ <para>
+ Currently, keywords must be hard-coded in localconfig.js. If they are not,
+ keywords are not automatically recognized. This means, if localconfig.js
+ is left unconfigured, that searching for a bug with the "foo" keyword
+ will only find bugs with "foo" in the summary, status whiteboard, product or
+ component name, but not those with the keyword "foo".
+ </para>
+ <para>
+ Workarounds for Bugzilla users:
+ <simplelist>
+ <member>search for '!foo' (this will find only bugs with the keyword "foo"</member>
+ <member>search 'foo,!foo' (equivalent to 'foo OR keyword:foo')</member>
+ </simplelist>
</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.
+ When this tool is ported from client-side JavaScript to server-side Perl,
+ the requirement for hard-coding keywords can be fixed.
+ <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=70907">This bug</ulink>
+ has details.
</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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
sgml-general-insert-case:lower
-sgml-indent-data:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
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/en/xml/using.xml b/docs/en/xml/using.xml
index 101a9d131..bc8159835 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -1,1957 +1,877 @@
-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<!-- TOC
+Chapter: Using Bugzilla
+ Create an account
+ Logging in
+ Setting up preferences
+ Account Settings
+ Email Settings
+ Page Footer
+ Permissions
+ Life cycle of a bug
+ Creating a bug
+ Checking for duplicates
+ Overview of all bug fields
+ Setting bug permissions
+ The Query Interface
+ Standard Queries
+ Email Queries
+ Boolean Queries
+ Regexp Queries
+ The Query Results
+ Changing Columns
+ Changing sorting order
+ Mass changes
+ Miscellaneous usage hints
-<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>
+-->
+<chapter id="using">
+<title>Using Bugzilla</title>
+ <epigraph>
<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.
+ What, Why, How, & What's in it for me?
</para>
- </section>
-
- <section id="myaccount">
- <title>Create a Bugzilla Account</title>
+ </epigraph>
- <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;"/>.
+ <section id="whatis">
+ <title>What is Bugzilla?</title>
+ <para>
+ Bugzilla is one example of a class of programs called "Defect Tracking Systems",
+ or, more commonly, "Bug-Tracking Systems". Defect Tracking Systems allow individual or
+ groups of developers to keep track of outstanding bugs in their product effectively.
+ Bugzilla was originally written by Terry Weissman in a programming language called
+ "TCL", to replace a crappy
+ bug-tracking database used internally for Netscape Communications. Terry later ported
+ Bugzilla to
+ Perl from TCL, and in Perl it remains to this day.
+ Most commercial defect-tracking software vendors at the
+ time charged enormous licensing fees, and Bugzilla quickly became a favorite of the
+ open-source crowd (with its genesis in the open-source browser project, Mozilla). It
+ is now the de-facto standard defect-tracking system against which all others are
+ measured.
</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.
+ Bugzilla has matured immensely, and now boasts many advanced features. These include:
+ <itemizedlist>
+ <listitem>
+ <para>
+ integrated, product-based granular security schema
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ inter-bug dependencies and dependency graphing
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ advanced reporting capabilities
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a robust, stable RDBMS back-end
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ extensive configurability
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a very well-understood and well-thought-out natural bug resolution protocol
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ email, XML, and HTTP APIs
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ available integration with automated software configuration management systems, including
+ Perforce and CVS.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ too many more features to list
+ </para>
+ </listitem>
+ </itemizedlist>
</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.
+ Despite its current robustness and popularity, however, Bugzilla
+ faces some near-term challenges, such as reliance on a single database, a lack of
+ abstraction of the user interface and program logic, verbose email bug
+ notifications, a powerful but daunting query interface, little reporting configurability,
+ problems with extremely large queries, some unsupportable bug resolution options,
+ no internationalization, and dependence on some nonstandard libraries.
</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.
+ Some recent headway has been made on the query front, however. If you are using the latest
+ version of Bugzilla, you should see a "simple search" form on the default front page of
+ your Bugzilla install. Type in two or three search terms and you should pull up some
+ relevant information. This is also available as "queryhelp.cgi".
+ </para>
+ <para>
+ Despite these small problems, Bugzilla is very hard to beat. It is under <emphasis>very</emphasis>
+ active development to address the current issues, and a long-awaited overhaul in the form
+ of Bugzilla 3.0 is expected sometime later this year.
</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>
-
+
+ <section id="why">
+ <title>Why Should We Use Bugzilla?</title>
+ <epigraph>
<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.
+ No, Who's on first...
</para>
- </section>
-
- </section>
-
- <section id="attachments">
- <title>Attachments</title>
-
+ </epigraph>
<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.
+ For many years, defect-tracking software has remained principally the domain
+ of large software development houses. Even then, most shops never bothered
+ with bug-tracking software, and instead simply relied on shared lists and
+ email to monitor the status of defects. This procedure is error-prone and
+ tends to cause those bugs judged least significant by developers to be
+ dropped or ignored
</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>&amp;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.
+ These days, many companies are finding that integrated defect-tracking
+ systems reduce downtime, increase productivity, and raise customer
+ satisfaction with their systems. Along with full disclosure, an open
+ bug-tracker allows manufacturers to keep in touch with their clients
+ and resellers, to communicate about problems effectively throughout
+ the data management chain. Many corporations have also discovered that
+ defect-tracking helps reduce costs by providing IT support accountability,
+ telephone support knowledge bases, and a common, well-understood system
+ for accounting for unusual system or software issues.
</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.
+ But why should <emphasis>you</emphasis> use Bugzilla?
</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 &lt;U&gt; 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.
+ 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, Loki software,
+ Linux-Mandrake, and VA Systems. Combined with systems such as CVS, Bonsai,
+ or Perforce SCM, Bugzilla provides a powerful, easy-to-use solution to
+ configuration management and replication problems
</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.
+ Bugzilla can dramatically increase the productivity and accountability
+ of individual employees by providing a documented workflow and positive
+ feedback for good performance. How many times do you wake up in the
+ morning, remembering that you were supposed to do *something* today,
+ but you just can't quite remember? Put it in Bugzilla, and you have a record
+ of it from which you can extrapolate milestones, predict product versions
+ for integration, and by using Bugzilla's e-mail integration features
+ be able to follow the discussion trail that led to critical decisions.
</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.
+ Ultimately, Bugzilla puts the power in your hands to improve your value
+ to your employer or business while providing a usable framework for your natural
+ attention to detail and knowledge store to flourish.
</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>
+ <section id="how">
+ <title>How do I use Bugzilla?</title>
+ <epigraph>
<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.
+ Hey! I'm Woody! Howdy, Howdy, Howdy!
</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>
-
+ </epigraph>
+
+ <para>
+ Bugzilla is a large, complex system. Describing how to use it
+ requires some time. If you are only interested in installing or administering
+ a Bugzilla installation, please consult the Installing and Administering
+ Bugzilla portions of this Guide. This section is principally aimed towards
+ developing end-user mastery of Bugzilla, so you may fully enjoy the benefits
+ afforded by using this reliable open-source bug-tracking software.
+ </para>
+ <para>
+ Throughout this portion of the Guide, we will refer to user account
+ options available at the Bugzilla test installation,
+ <ulink url="http://landfill.tequilarista.org/">
+ landfill.tequilarista.org</ulink>.
<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>
+ <para>
+ Some people have run into difficulties completing this tutorial. If
+ you run into problems, please check the updated, online documentation available
+ at <ulink url="http://www.trilobyte.net/barnsons/">http://www.trilobyte.net/barnsons</ulink>.
+ If you're still stumped, please subscribe to the newsgroup and provide details of exactly
+ what's stumping you! If enough people complain, I'll have to fix it in the next
+ version of this Guide. You can subscribe to the newsgroup at
+ <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">
+ news://news.mozilla.org/netscape.public.mozilla.webtools</ulink>
+ </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>
-
+ Although Landfill serves as a great introduction to Bugzilla, it does not offer
+ all the options you would have as a user on your own installation of Bugzilla,
+ nor can it do more than serve as a general introduction to Bugzilla. Additionally,
+ Landfill often runs cutting-edge versions of Bugzilla for testing, so some things
+ may work slightly differently than mentioned here.
+ </para>
+
+ <section id="myaccount">
+ <title>Create a Bugzilla Account</title>
<para>
- This is a purely informative page which outlines your current
- permissions on this installation of Bugzilla.
+ First thing's first! 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 the end-user Bugzilla experience, use this URL:
+ <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/">
+ http://landfill.tequilarista.org/mozilla/bugzilla/</ulink>
</para>
-
+ <orderedlist>
+ <listitem>
+ <para>
+ Click the "Open a new Bugzilla account" link.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enter your "E-mail address" and "Real Name" (or whatever name you want to call yourself)
+ in the spaces provided, then select the "Create Account" button.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Within 5-10 minutes, you should receive an email to the address you provided above,
+ which contains your login name (generally the same as the email address), and
+ a password you can use to access your account. This password is randomly generated,
+ and should be changed at your nearest opportunity (we'll go into how to do it later).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Click the "Log In" link in the yellow area at the bottom of the page in your browser,
+ then enter your "E-mail address" and "Password" you just received into the spaces provided,
+ and select "Login".
+ <note>
+ <para>
+ If you ever forget your password, you can come back to this page, enter your
+ "E-mail address", then select the "E-mail me a password" button to have your password
+ mailed to you again so that you can login.
+ </para>
+ </note>
+ <caution>
+ <para>
+ Many modern browsers include an "Auto-Complete" or "Form Fill" feature to
+ remember the user names and passwords you type in at many sites. Unfortunately,
+ sometimes they attempt to "guess" what you will put in as your password, and guess
+ wrong. If you notice a text box is already filled out, please overwrite the contents
+ of the text box so you can be sure to input the correct information.
+ </para>
+ </caution>
+ </para>
+ </listitem>
+ </orderedlist>
<para>
- A complete list of permissions is below. Only users with
- <emphasis>editusers</emphasis> privileges can change the permissions
- of other users.
+ Congratulations! If you followed these directions, you now are the
+ proud owner of a user account on landfill.tequilarista.org (Landfill) or
+ your local Bugzilla install. You should now see in your browser a
+ page called the "Bugzilla Query Page". It may look daunting, but
+ with this Guide to walk you through it, you will master it in no time.
</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>
-
+ <section id="query">
+ <title>The Bugzilla Query Page</title>
<para>
- A report is a view of the current state of the bug database.
+ The Bugzilla Query Page is the heart and soul of Bugzilla. It is the master
+ interface where you can find any bug report, comment, or patch currently in the Bugzilla
+ system. We'll go into how to create your own bug report later on.
</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.
+ There are efforts underway to simplify query usage. If you have a local installation
+ of Bugzilla 2.12 or higher, you should have "quicksearch.html" available
+ to use and simplify your searches. There is also, or shortly will be, a helper
+ for the query interface, called "queryhelp.cgi". Landfill tends to run the latest code,
+ so these two utilities should be available there for your perusal.
</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.
+ At this point, please visit the main Bugzilla site,
+ <ulink url="http://bugzilla.mozilla.org/query.cgi">
+ bugzilla.mozilla.org</ulink>, to see a more fleshed-out query page.
</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.
+ The first thing you need to notice about the Bugzilla Query Page is that
+ nearly every box you see on your screen has a hyperlink nearby, explaining what
+ it is or what it does. Near the upper-left-hand corner of your browser window
+ you should see the word "Status" underlined. Select 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.
+ Notice the page that popped up? Every underlined word you see on your screen
+ is a hyperlink that will take you to context-sensitive help.
+ Click around for a while, and learn what everything here does. To return
+ to the query interface after pulling up a help page, use the "Back" button in
+ your browser.
</para>
-
- </section>
-
- <section id="charts">
- <title>Charts</title>
-
<para>
- A chart is a view of the state of the bug database over time.
+ I'm sure that after checking out the online help, you are now an Expert
+ on the Bugzilla Query Page. If, however, you feel you haven't mastered it yet,
+ let me walk you through making a few successful queries to find out what there
+ are in the Bugzilla bug-tracking system itself.
</para>
-
+ <orderedlist>
+ <listitem>
+ <para>
+ Ensure you are back on the "Bugzilla Query Page"
+ Do nothing in the boxes marked "Status", "Resolution", "Platform", "OpSys",
+ "Priority", or "Severity". The default query for "Status" is to find all bugs that
+ are NEW, ASSIGNED, or REOPENED, which is what we want. If you don't select anything
+ in the other 5 scrollboxes there, then you are saying that "any of these are OK";
+ we're not locking ourselves into only finding bugs on the "DEC" Platform, or "Windows 95"
+ OpSys (Operating System). You're smart, I think you have it figured out.
+ </para>
+ <para>
+ Basically, selecting <emphasis>anything</emphasis> on the query page narrows your search
+ down. Leaving stuff unselected, or text boxes unfilled, broadens your search!
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You see the box immediately below the top six boxes that contains an "Email" text box,
+ with the words "matching as", a drop-down selection box, then some checkboxes with
+ "Assigned To" checked by default? This allows you to filter your search down based upon
+ email address. Let's put my email address in there, and see what happens.
+ </para>
+ <para>
+ Type "barnboy@trilobyte.net" in the top Email text box.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Let's narrow the search some more. Scroll down until you find the box with the word
+ "Program" over the top of it. This is where we can narrow our search down to only
+ specific products (software programs or product lines) in our Bugzilla database.
+ Please notice the box is a <emphasis>scrollbox</emphasis>. Using the down arrow on the
+ scrollbox, scroll down until you can see an entry called "Webtools". Select this entry.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Did you notice that some of the boxes to the right changed when you selected "Webtools"?
+ Every Program (or Product) has different Versions, Components, and Target Milestones associated
+ with it. A "Version" is the number of a software program.
+ <example>
+ <title>Some Famous Software Versions</title>
+ <informalexample>
+ <para>
+ Do you remember the hype in 1995 when Microsoft Windows 95(r) was released?
+ It may have been several years
+ ago, but Microsoft(tm) spent over $300 Million advertising this new Version of their
+ software. Three years later, they released Microsoft Windows 98(r),
+ another new version, to great fanfare, and then in 2000 quietly
+ released Microsoft Windows ME(Millenium Edition)(r).
+ </para>
+ <para>
+ Software "Versions" help a manufacturer differentiate
+ their current product from their
+ previous products. Most do not identify their products
+ by the year they were released.
+ Instead, the "original" version of their software will
+ often be numbered "1.0", with
+ small bug-fix releases on subsequent tenths of a digit. In most cases, it's not
+ a decimal number; for instance, often 1.9 is an <emphasis>older</emphasis> version
+ of the software than 1.11,
+ but is a <emphasis>newer</emphasis> version than 1.1.1.
+ </para>
+ <para>
+ In general, a "Version" in Bugzilla should refer to
+ <emphasis>released</emphasis>
+ products, not products that have not yet been released
+ to the public. Forthcoming products
+ are what the Target Milestone field is for.
+ </para>
+ </informalexample>
+ </example>
+ </para>
+ <para>
+ A "Component" is a piece of a Product.
+ It may be a standalone program, or some other logical
+ division of a Product or Program.
+ Normally, a Component has a single Owner, who is responsible
+ for overseeing efforts to improve that Component.
+ <example>
+ <title>Mozilla Webtools Components</title>
+ <informalexample>
+ <para>
+ Mozilla's "Webtools" Product is composed of several pieces (Components):
+ <simplelist>
+ <member><emphasis>Bonsai</emphasis>,
+ a tool to show recent changes to Mozilla</member>
+ <member><emphasis>Bugzilla</emphasis>,
+ a defect-tracking tool</member>
+ <member><emphasis>Build</emphasis>,
+ a tool to automatically compile source code
+ into machine-readable form</member>
+ <member><emphasis>Despot</emphasis>,
+ a program that controls access to the other Webtools</member>
+ <member><emphasis>LXR</emphasis>,
+ a utility that automatically marks up text files
+ to make them more readable</member>
+ <member><emphasis>MozBot</emphasis>,
+ a "robot" that announces changes to Mozilla in Chat</member>
+ <member><emphasis>TestManager</emphasis>,
+ a tool to help find bugs in Mozilla</member>
+ <member><emphasis>Tinderbox</emphasis>,
+ which displays reports from Build</member>
+ </simplelist>
+ </para>
+ <para>
+ A different person is responsible for each of these Components.
+ Tara Hernandez keeps
+ the "Bugzilla" component up-to-date.
+ </para>
+ </informalexample>
+ </example>
+ </para>
+ <para>
+ A "Milestone", or "Target Milestone" is a often a planned future "Version" of a
+ product. In many cases, though, Milestones simply represent significant dates for
+ a developer. Having certain features in your Product is frequently
+ tied to revenue (money)
+ the developer will receive if the features work by the time she
+ reaches the Target Milestone.
+ Target Milestones are a great tool to organize your time.
+ If someone will pay you $100,000 for
+ incorporating certain features by a certain date,
+ those features by that Milestone date become
+ a very high priority. Milestones tend to be highly malleable creatures,
+ though, that appear
+ to be in reach but are out of reach by the time the important day arrives.
+ </para>
+ <para>
+ The Bugzilla Project has set up Milestones for future
+ Bugzilla versions 2.14, 2.16, 2.18, 3.0, etc. However,
+ a Target Milestone can just as easily be a specific date,
+ code name, or weird alphanumeric
+ combination, like "M19".
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OK, now let's select the "Bugzilla" component from its scrollbox.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Skip down the page a bit -- do you see the "submit query" button?
+ Select it, and let's run
+ this query!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Congratulations! You've completed your first Query, and have before you the Bug List
+ of the author of this Guide, Matthew P. Barnson (barnboy@trilobyte.net). If I'm
+ doing well,
+ you'll have a cryptic "Zarro Boogs Found" message on your screen. It is just
+ a happy hacker's way of saying "Zero Bugs Found". However, I am fairly certain I will
+ always have some bugs assigned to me that aren't done yet,
+ so you won't often see that message!
+ </para>
+ </listitem>
+ </orderedlist>
<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.
+ I encourage you to click the bug numbers in the left-hand column and examine
+ my bugs. Also notice that if you click the underlined
+ links near the top of this page, they do
+ not take you to context-sensitive help here,
+ but instead sort the columns of bugs on the screen!
+ When you need to sort your bugs by priority, severity,
+ or the people they are assigned to, this
+ is a tremendous timesaver.
+ </para>
+ <para>
+ A couple more interesting things about the Bug List page:
+ <simplelist>
+ <member><emphasis>Change Columns</emphasis>:
+ by selecting this link, you can show all kinds
+ of information in the Bug List</member>
+ <member><emphasis>Change several bugs at once</emphasis>:
+ If you have sufficient rights to change all
+ the bugs shown in the Bug List, you can mass-modify them.
+ This is a big time-saver.</member>
+ <member><emphasis>Send mail to bug owners</emphasis>:
+ If you have many related bugs, you can request
+ an update from every person who owns the bugs in
+ the Bug List asking them the status.</member>
+ <member><emphasis>Edit this query</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>
+ </simplelist>
</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>
+ <para>
+ There are many more options to the Bugzilla Query Page
+ and the Bug List than I have shown you.
+ But this should be enough for you to learn to get around.
+ I encourage you to check out the
+ <ulink url="http://www.mozilla.org/bugs/">Bugzilla Home Page</ulink>
+ to learn about the Anatomy
+ and Life Cycle of a Bug before continuing.
+ </para>
</note>
+ </section>
+
+
+ <section id="bugreports">
+ <title>Creating and Managing Bug Reports</title>
+ <epigraph>
+ <para>And all this time, I thought we were taking bugs <emphasis>out</emphasis>...</para>
+ </epigraph>
- <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 id="bug_writing">
+ <title>Writing a Great Bug Report</title>
+ <para>
+ Before we plunge into writing your first bug report, I encourage you to read
+ <ulink url="http://www.mozilla.org/quality/bug-writing-guidelines.html">Mozilla.org's 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>
+ While you are at it, why not learn how to find previously reported bugs? Mozilla.org
+ has published a great tutorial on finding duplicate bugs, available at
+ <ulink url="http://www.mozilla.org/quality/help/beginning-duplicate-finding.html">
+ http://www.mozilla.org/quality/help/beginning-duplicate-finding.html</ulink>.
+ </para>
+ <para>
+ I realize this was a lot to read. However, understanding the mentality of writing
+ great bug reports will help us on the next part!
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Go back to <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/">
+ http://landfill.tequilarista.org/mozilla/bugzilla/</ulink>
+ in your browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Select the
+ <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/enter_bug.cgi">
+ Enter a new bug report</ulink> link.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Select a product.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now you should be at the "Enter Bug" form.
+ The "reporter" should have been automatically filled out
+ for you (or else Bugzilla prompted you to Log In again
+ -- you did keep the email with your username
+ and password, didn't you?).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Select a Component in the scrollbox.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Bugzilla should have made reasonable guesses, based upon your browser,
+ for the "Platform" and "OS" drop-down
+ boxes. If those are wrong, change them -- if you're on an SGI box
+ running IRIX, we want to know!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fill in the "Assigned To" box with the email address you provided earlier.
+ This way you don't end up sending copies of your bug to lots of other people,
+ since it's just a test bug.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Leave the "CC" text box blank.
+ Fill in the "URL" box with "http://www.mozilla.org".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enter "The Bugzilla Guide" in the Summary text box,
+ and place any comments you have on this
+ tutorial, or the Guide in general, into the Description box.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ Voila! Select "Commit" and send in your bug report!
+ Next we'll look at resolving bugs.
+ </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 id="bug_manage">
+ <title>Managing your Bug Reports</title>
+ <para>
+ OK, you should have a link to the bug you just created near the top of your page.
+ It should say
+ "Bug XXXX posted", with a link to the right saying "Back to BUG# XXXX".
+ Select this link.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Scroll down a bit on the subsequent page,
+ until you see the "Resolve bug, changing resolution to (dropdown box).
+ Normally, you would
+ "Accept bug (change status to ASSIGNED)", fix it, and then resolve.
+ But in this case, we're
+ going to short-circuit the process because this wasn't a real bug.
+ Change the dropdown next to
+ "Resolve Bug" to "INVALID", make sure the radio button is
+ marked next to "Resolve Bug", then
+ click "Commit".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Hey! It said it couldn't take the change in a big red box!
+ That's right, you must specify
+ a Comment in order to make this change. Select the "Back"
+ button in your browser, add a
+ Comment, then try Resolving the bug with INVALID status again.
+ This time it should work.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ You have now learned the basics of Bugzilla navigation,
+ entering a bug, and bug maintenance.
+ I encourage you to explore these features, and see what you can do with them!
+ We'll spend no more time on individual Bugs or Queries from this point on, so you are
+ on your own there.
+ </para>
+ <para>
+ But I'll give a few last hints!
+ </para>
+ <para>
+ There is a <ulink url="http://bugzilla.mozilla.org/help.html">CLUE</ulink>
+ on the Query page
+ that will teach you more how to use the form.
+ </para>
+ <para>
+ If you click the hyperlink on the
+ <ulink url="http://bugzilla.mozilla.org/describecomponents.cgi">Component</ulink>
+ box of the Query page, you will be presented a form that will describe what all
+ the components are.
+ </para>
+ <para>
+ Possibly the most powerful feature of the Query page is the
+ <ulink url="http://bugzilla.mozilla.org/booleanchart.html">Boolean Chart</ulink> section.
+ It's a bit confusing to use the first time, but can provide unparalleled
+ flexibility in your queries,
+ allowing you to build extremely powerful requests.
+ </para>
+ <para>
+ Finally, you can build some nifty
+ <ulink url="http://bugzilla.mozilla.org/reports.cgi">Reports</ulink>
+ using the "Bug Reports" link near the bottom of the query page, and also
+ available via the "Reports" link
+ at the footer of each page.
+ </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>
+ <section id="init4me">
+ <title>What's in it for me?</title>
+ <epigraph>
<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).
+ Indiana, it feels like we walking on fortune cookies!
</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.
+ These ain't fortune cookies, kid...
</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).
+ </epigraph>
+ <para>
+ Customized User Preferences offer tremendous versatility to
+ your individual Bugzilla experience.
+ Let's plunge into what you can do! The first step is to click
+ the "Edit prefs" link at the footer of each page once you
+ have logged in to
+ <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/query.cgi?GoAheadAndLogIn=1">
+ Landfill</ulink>.
+ </para>
+ <section id="accountsettings">
+ <title>Account Settings</title>
+ <para>
+ On this page, you can change your basic Account Settings,
+ including your password and full name.
+ For security reasons, in order to change anything on this page you
+ must type your <emphasis>current</emphasis>
+ password into the "Old Password" field.
+ If you wish to change your password, type the new password you
+ want into the "New Password" field and again into the "Re-enter
+ new password" field to ensure
+ you typed your new password correctly. Select the "Submit" button and you're done!
</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 id="emailsettings">
+ <title>Email Settings</title>
+ <section id="notification">
+ <title>Email Notification</title>
+ <note>
+ <para>
+ The email notification settings described below have been obsoleted in Bugzilla 2.12, and
+ this section will be replaced with a comprehensive description of the amazing array of
+ new options at your disposal. However, in the meantime, throw this chunk out the window
+ and go crazy with goofing around with different notification options.
+ </para>
+ </note>
+ <para>
+ Ahh, here you can reduce or increase the amount of email sent you from Bugzilla!
+ In the drop-down "Notify me of changes to", select one of
+ <simplelist>
+ <member><emphasis>All qualifying bugs</emphasis>: sends you every change to every bug
+ where your name is somewhere on it, regardless of who changed it.</member>
+ <member><emphasis>Only those bugs which I am listed in the CC line</emphasis>: prevents
+ you from receiving mail for which you are the reporter,'
+ owner, or QA contact. If you are on the CC
+ list, presumably someone had a <emphasis>good</emphasis>
+ reason for you to get the email.</member>
+ <member><emphasis>All qulifying bugs except those which I change</emphasis>:
+ This is the default, and
+ a sensible setting. If someone else changes your bugs, you will get emailed,
+ but if you change bugs
+ yourself you will receive no notification of the change.</member>
+ </simplelist>
+ </para>
+ </section>
+ <section id="newemailtech">
+ <title>New Email Technology</title>
+ <note>
+ <para>
+ This option may not be available in all Bugzilla installations, depending upon
+ the preferences of the systems administrator responsible for the setup of your Bugzilla.
+ However, if you really want this functionality, ask her to "enable newemailtech
+ in Params"
+ and "make it the default for all new users", referring her to the Administration section
+ of this Guide.
+ </para>
+ </note>
+ <para>
+ Disregard the warnings about "experimental and bleeding edge"; the code to handle email
+ in a cleaner manner than that historically used for Bugzilla is
+ quite robust and well-tested now.
+ </para>
+ <para>
+ I recommend you enable the option, "Click here to sign up (and risk any bugs)".
+ Your email-box
+ will thank you for it. The fundamental shift in "newemailtech" is away from standard UNIX
+ "diff" output, which is quite ugly, to a prettier, better laid-out email.
+ </para>
+ </section>
+ <section id="watchsettings">
+ <title>"Watching" Users</title>
+ <note>
+ <para>
+ This option may not be available in all Bugzilla installations, depending upon
+ the preferences of the systems administrator responsible for the setup of your Bugzilla.
+ However, if you really want this functionality, ask her to "enable watchers in Params".
+ </para>
+ </note>
+ <para>
+ By entering user email names into the "Users to watch" text entry box, delineated by commas,
+ you can watch bugs of other users. This powerful functionality enables seamless transitions
+ as developers change projects, managers wish to get in touch with the issues faced by their
+ direct reports, or users go on vacation. If any of these three situations apply
+ to you, you will undoubtedly find this feature quite convenient.
+ </para>
+ </section>
</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>
-
+ <section id="footersettings">
+ <title>Page Footer</title>
<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>
+ <para>
+ By default, this page is quite barren. However, go explore the Query Page some more; you will
+ find that you can store numerous queries on the server, so if you regularly run a particular query
+ it is just a drop-down menu away. On this page of Preferences, if you have many stored
+ queries you can elect to have them always one-click away!
+ </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>
+ If you have many stored queries on the server, here you will find individual drop-downs for each
+ stored query. Each drop-down gives you the option of that query appearing on the footer of every
+ page in Bugzilla! This gives you powerful one-click access to any complex searches you may set up,
+ and is an excellent way to impress your boss...
+ </para>
+ <tip>
+ <para>By default, the "My Bugs" link appears at the bottom of each page. However, this query
+ gives you both the bugs you have reported, as well as those you are assigned. One of the most
+ common uses for this page is to remove the "My Bugs" link, replacing it with two other queries,
+ commonly called "My Bug Reports" and "My Bugs" (but only referencing bugs assigned to you). This
+ allows you to distinguish those bugs you have reported from those you are assigned. I commonly
+ set up complex Boolean queries in the Query page and link them to my footer in this page. When
+ they are significantly complex, a one-click reference can save hours of work.</para>
+ </tip>
</section>
-
- <section>
- <title>Saving Your Changes</title>
-
+ <section id="permissionsettings">
+ <title>Permissions</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.
+ This is a purely informative page which outlines your current permissions on
+ this installation of Bugzilla. If you have permissions to grant certain permissions to
+ other users, the "other users" link appears on this page as well as the footer.
+ For more information regarding user administration, please consult the Administration
+ section of this Guide.
</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>
+ <section id="usingbz-conc">
+ <title>Using Bugzilla-Conclusion</title>
+ <para>
+ Thank you for reading through this portion of the Bugzilla Guide. I anticipate
+ it may not yet meet the needs of all readers. If you have additional comments or
+ corrections to make, please submit your contributions to the
+ <ulink url="mailto://mozilla-webtools@mozilla.org">mozilla-webtools</ulink>
+ mailing list/newsgroup. The mailing list is mirrored to the netscape.public.mozilla.webtools
+ newsgroup, and the newsgroup is mirrored to mozilla-webtools@mozilla.org
+ </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-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
sgml-general-insert-case:lower
-sgml-indent-data:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:Bugzilla-Guide\.sgml
+sgml-exposed-tags:nil
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:
-->
-