{
name => 'docs_urlbase',
type => 't',
- default => 'docs/html/',
+ default => 'docs/%lang%/html/',
checker => \&check_url
},
'install-module.pl' => { perms => $owner_executable },
'docs/makedocs.pl' => { perms => $owner_executable },
- 'docs/rel_notes.txt' => { perms => $ws_readable },
- 'docs/README.docs' => { perms => $owner_readable },
+ 'docs/style.css' => { perms => $ws_readable },
+ 'docs/*/rel_notes.txt' => { perms => $ws_readable },
+ 'docs/*/README.docs' => { perms => $owner_readable },
"$datadir/bugzilla-update.xml" => { perms => $ws_writeable },
"$datadir/params" => { perms => $ws_writeable },
"$datadir/mailer.testfile" => { perms => $ws_writeable },
dirs => $ws_dir_readable },
t => { files => $owner_readable,
dirs => $owner_dir_readable },
- 'docs/html' => { files => $ws_readable,
+ 'docs/*/html' => { files => $ws_readable,
dirs => $ws_dir_readable },
- 'docs/pdf' => { files => $ws_readable,
+ 'docs/*/pdf' => { files => $ws_readable,
dirs => $ws_dir_readable },
- 'docs/txt' => { files => $ws_readable,
+ 'docs/*/txt' => { files => $ws_readable,
dirs => $ws_dir_readable },
- 'docs/images' => { files => $ws_readable,
+ 'docs/*/images' => { files => $ws_readable,
dirs => $ws_dir_readable },
'docs/lib' => { files => $owner_readable,
dirs => $owner_dir_readable },
- 'docs/xml' => { files => $owner_readable,
+ 'docs/*/xml' => { files => $owner_readable,
dirs => $owner_dir_readable },
);
get_version_and_os
indicate_progress
install_string
+ include_languages
template_include_path
vers_cmp
get_console_locale
return $string_template;
}
-sub template_include_path {
+sub include_languages {
my ($params) = @_;
$params ||= {};
if (!grep($_ eq 'en', @usedlanguages)) {
push(@usedlanguages, 'en');
}
+
+ return @usedlanguages;
+}
+sub template_include_path {
+ my @usedlanguages = include_languages(@_);
# Now, we add template directories in the order they will be searched:
# First, we add extension template directories, because extension templates
Note that languages are sorted by the user's preference (as specified
in their browser, usually), and extensions are sorted alphabetically.
+=item C<include_languages>
+
+Used by L<Bugzilla::Template> to determine the languages' list which
+are compiled with the browser's I<Accept-Language> and the languages
+of installed templates.
+
=item C<vers_cmp>
=over
use Bugzilla::Constants;
use Bugzilla::Install::Requirements;
-use Bugzilla::Install::Util qw(install_string template_include_path);
+use Bugzilla::Install::Util qw(install_string template_include_path include_languages);
use Bugzilla::Util;
use Bugzilla::User;
use Bugzilla::Error;
# Allow templates to access the "corect" URLBase value
'urlbase' => sub { return Bugzilla::Util::correct_urlbase(); },
+ # Allow templates to access docs url with users' preferred language
+ 'docs_urlbase' => sub {
+ my ($language) = include_languages();
+ my $docs_urlbase = Bugzilla->params->{'docs_urlbase'};
+ $docs_urlbase =~ s/\%lang\%/$language/;
+ return $docs_urlbase;
+ },
+
# These don't work as normal constants.
DB_MODULE => \&Bugzilla::Constants::DB_MODULE,
REQUIRED_MODULES =>
--- /dev/null
+txt
+pdf
+html
--- /dev/null
+Welcome to the Bugzilla documentation project!
+You'll find these directories and files here:
+
+README.docs # This README file
+html/ # The compiled HTML docs from XML sources (do not edit)
+txt/ # The compiled text docs from XML sources (do not edit)
+xml/ # The original XML doc sources (edit these)
+
+A note about the XML:
+ The documentation is written in DocBook 4.1.2, and attempts to adhere
+to the LinuxDoc standards where applicable (http://www.tldp.org).
+Please consult "The LDP Author Guide" at tldp.org for details on how
+to set up your personal environment for compiling XML files.
+ If you need to make corrections to typographical errors, or other minor
+editing duties, feel free to use any text editor to make the changes. XML
+is not rocket science -- simply make sure your text appears between
+appropriate tags (like <para>This is a paragraph</para>) and we'll be fine.
+If you are making more extensive changes, please ensure you at least validate
+your XML before checking it in with something like:
+ nsgmls -s $JADE_PUB/xml.dcl Bugzilla-Guide.xml
+
+ When you validate, please validate the master document (Bugzilla-Guide.xml)
+as well as the document you edited to ensure there are no critical errors.
+The following errors are considered "normal" when validating with nsgmls:
+
+ DTDDECL catalog entries are not supported
+ "DOCTYPE" declaration not allowed in instance
+
+ The reason these occur is that free sgml/xml validators do not yet support
+the DTDDECL catalog entries, and I've included DOCTYPE declarations in
+entities referenced from Bugzilla-Guide.xml so these entities can compile
+individually, if necessary. I suppose I ought to comment them out at some
+point, but for now they are convenient and don't hurt anything.
+
+ Thanks for taking the time to read these notes and consulting the
+documentation. Please address comments and questions to the newsgroup:
+news://news.mozilla.org/netscape/public/mozilla/webtools .
+
+==========
+HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT:
+==========
+
+Trying to set up an XML Docbook editing environment the
+first time can be a daunting task.
+I use Linux-Mandrake, in part, because it has a fully-functional
+XML Docbook editing environment included as part of the
+distribution CD's. If you have easier instructions for how to
+do this for a particular Linux distribution or platform, please
+let the team know at the mailing list: mozilla-webtools@mozilla.org.
+
+The following text is taken nearly verbatim from
+http://bugzilla.mozilla.org/show_bug.cgi?id=95970, where I gave
+these instructions to someone who wanted the greater manageability
+maintaining a document in Docbook brings:
+
+This is just off the top of my head, but here goes. Note some of these may
+NOT be necessary, but I don't think they hurt anything by being installed.
+
+rpms:
+
+openjade
+jadetex
+docbook-dtds
+docbook-style-dsssl
+docbook-style-dsssl-doc
+docbook-utils
+xemacs
+psgml
+sgml-tools
+sgml-common
+
+
+If you're getting these from RedHat, make sure you get the ones in the
+rawhide area. The ones in the 7.2 distribution are too old and don't
+include the XML stuff. The packages distrubuted with RedHat 8.0 and 9
+and known to work.
+
+Download "ldp.dsl" from the Resources page on tldp.org. This is the
+stylesheet I use to get the HTML and text output. It works well, and has a
+nice, consistent look with the rest of the linuxdoc documents. You'll have to
+adjust the paths in ldp.dsl at the top of the file to reflect the actual
+locations of your docbook catalog files. I created a directory,
+/usr/share/sgml/docbook/ldp, and put the ldp.dsl file there. I then edited
+ldp.dsl and changed two lines near the top:
+<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/html/docbook.dsl" CDATA
+dsssl>
+...and...
+<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/print/docbook.dsl" CDATA
+dsssl>
+
+Note the difference is the top one points to the HTML docbook stylesheet,
+and the next one points to the PRINT docbook stylesheet.
+
+Also note that modifying ldp.dsl doesn't seem to be needed on RedHat 9.
+
+ You know, this sure looks awful involved. Anyway, once you have this in
+place, add to your .bashrc:
+export SGML_CATALOG_FILES=/etc/sgml/catalog
+export LDP_HOME=/usr/share/sgml/docbook/ldp
+export JADE_PUB=/usr/share/doc/openjade-1.3.1/pubtext
+
+or in .tcshrc:
+setenv SGML_CATALOG_FILES /etc/sgml/catalog
+setenv LDP_HOME /usr/share/sgml/docbook/ldp
+setenv JADE_PUB /usr/share/doc/openjade-1.3.1/pubtext
+
+ If you have root access and want to set this up for anyone on your box,
+you can add those lines to /etc/profile for bash users and /etc/csh.login
+for tcsh users.
+
+ Make sure you edit the paths in the above environment variables if those
+folders are anywhere else on your system (for example, the openjade version
+might change if you get a new version at some point).
+
+ I suggest xemacs for editing your XML Docbook documents. The darn
+thing just works, and generally includes PSGML mode by default. Not to
+mention you can validate the SGML from right within it without having to
+remember the command-line syntax for nsgml (not that it's that hard
+anyway). If not, you can download psgml at
+http://www.sourceforge.net/projects/psgml.
+
+ Another good editor is the latest releases of vim and gvim. Vim will
+recognize DocBook tags and give them a different color than unreconized tags.
+
+==========
+NOTES:
+==========
+
+ Here are the commands I use to maintain this documentation.
+ You MUST have DocBook 4.1.2 set up correctly in order for this to work.
+
+ These commands can be run all at once using the ./makedocs.pl script.
+
+To create HTML documentation:
+bash$ cd html
+bash$ jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
+$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml
+
+To create HTML documentation as a single big HTML file:
+bash$ cd html
+bash$ jade -V nochunks -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
+$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml >Bugzilla-Guide.html
+
+To create TXT documentation as a single big TXT file:
+bash$ cd txt
+bash$ lynx -dump -nolist ../html/Bugzilla-Guide.html >Bugzilla-Guide.txt
+
+
+Sincerely,
+ Matthew P. Barnson
+ The Bugzilla "Doc Knight"
+ mbarnson@sisna.com
+
+ with major edits by Dave Miller <justdave@syndicomm.com> based on
+ experience setting this up on the Landfill test server.
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+ <dia:diagramdata>
+ <dia:attribute name="background">
+ <dia:color val="#ffffff"/>
+ </dia:attribute>
+ <dia:attribute name="pagebreak">
+ <dia:color val="#000099"/>
+ </dia:attribute>
+ <dia:attribute name="paper">
+ <dia:composite type="paper">
+ <dia:attribute name="name">
+ <dia:string>#A4#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="tmargin">
+ <dia:real val="2.8222000598907471"/>
+ </dia:attribute>
+ <dia:attribute name="bmargin">
+ <dia:real val="2.8222000598907471"/>
+ </dia:attribute>
+ <dia:attribute name="lmargin">
+ <dia:real val="2.8222000598907471"/>
+ </dia:attribute>
+ <dia:attribute name="rmargin">
+ <dia:real val="2.8222000598907471"/>
+ </dia:attribute>
+ <dia:attribute name="is_portrait">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="scaling">
+ <dia:real val="1"/>
+ </dia:attribute>
+ <dia:attribute name="fitto">
+ <dia:boolean val="false"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ <dia:attribute name="grid">
+ <dia:composite type="grid">
+ <dia:attribute name="width_x">
+ <dia:real val="1"/>
+ </dia:attribute>
+ <dia:attribute name="width_y">
+ <dia:real val="1"/>
+ </dia:attribute>
+ <dia:attribute name="visible_x">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:attribute name="visible_y">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:composite type="color"/>
+ </dia:composite>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#d8e5e5"/>
+ </dia:attribute>
+ <dia:attribute name="guides">
+ <dia:composite type="guides">
+ <dia:attribute name="hguides"/>
+ <dia:attribute name="vguides"/>
+ </dia:composite>
+ </dia:attribute>
+ </dia:diagramdata>
+ <dia:layer name="Background" visible="true">
+ <dia:object type="Standard - Line" version="0" id="O0">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21,0"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="20.5,-0.05;21.5,2.05"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="21,0"/>
+ <dia:point val="21,2"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="2"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="1" to="O10" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O1">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21,4"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="15.5,3.95;21.05,7.05"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="21,4"/>
+ <dia:point val="21,6.95"/>
+ <dia:point val="16,4"/>
+ <dia:point val="16,7"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O10" connection="13"/>
+ <dia:connection handle="3" to="O11" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O2">
+ <dia:attribute name="obj_pos">
+ <dia:point val="10,4"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="9.95,3.95;16.5,7.05"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="10,4"/>
+ <dia:point val="10,7"/>
+ <dia:point val="16,4"/>
+ <dia:point val="16,7"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="3" to="O11" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Line" version="0" id="O3">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16,8.9"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="15.5,8.85;16.5,12.05"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="16,8.9"/>
+ <dia:point val="16,12"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O11" connection="13"/>
+ <dia:connection handle="1" to="O12" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O4">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13,13"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="10.95,7.9;13.5,13.05"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="13,13"/>
+ <dia:point val="13,7.95"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-1.9999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O12" connection="7"/>
+ <dia:connection handle="1" to="O11" connection="7"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Line" version="0" id="O5">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16,14"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="15.5,13.95;16.5,17.05"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="16,14"/>
+ <dia:point val="16,17"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O12" connection="13"/>
+ <dia:connection handle="1" to="O13" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Line" version="0" id="O6">
+ <dia:attribute name="obj_pos">
+ <dia:point val="10,3"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="9.95,2.95;10.05,4.05"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="10,3"/>
+ <dia:point val="10,4"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="2"/>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O7">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16,18.9"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="15.95,18.85;21.5,22.05"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="16,18.9"/>
+ <dia:point val="16,22"/>
+ <dia:point val="21,19"/>
+ <dia:point val="21,22"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O13" connection="13"/>
+ <dia:connection handle="3" to="O14" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O8">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16,18.9"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="9.5,18.85;16.05,22.05"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="16,18.9"/>
+ <dia:point val="16,22"/>
+ <dia:point val="10,19"/>
+ <dia:point val="10,22"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O13" connection="13"/>
+ <dia:connection handle="3" to="O15" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O9">
+ <dia:attribute name="obj_pos">
+ <dia:point val="8.5,22"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="8.4318,13.5624;13.6055,22.0682"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="8.5,22"/>
+ <dia:point val="13.1464,13.8536"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-0.71725063066182693"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O15" connection="1"/>
+ <dia:connection handle="1" to="O12" connection="11"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O10">
+ <dia:attribute name="obj_pos">
+ <dia:point val="17.9,2"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="17.85,1.95;24.15,4.05"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="17.9,2"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6.1999999999999993"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="2"/>
+ </dia:attribute>
+ <dia:attribute name="inner_color">
+ <dia:color val="#e5e5e5"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#UNCONFIRMED#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="21,3.3"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O11">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13,7"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="12.95,6.95;19.05,8.95"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="13,7"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="1.9000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#NEW#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16,8.25"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O12">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13,12"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="12.95,11.95;19.05,14.05"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="13,12"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="2"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#ASSIGNED#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16,13.3"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O13">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13,17"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="12.95,16.95;19.05,18.95"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="13,17"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="1.9000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="inner_color">
+ <dia:color val="#bfbfbf"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#RESOLVED#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16,18.25"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O14">
+ <dia:attribute name="obj_pos">
+ <dia:point val="18,22"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="17.95,21.95;24.05,23.95"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="18,22"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="1.9000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="inner_color">
+ <dia:color val="#bfbfbf"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#VERIFIED#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="21,23.25"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O15">
+ <dia:attribute name="obj_pos">
+ <dia:point val="7,22"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="6.95,21.95;13.05,23.95"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="7,22"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="1.9000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#REOPEN#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="10,23.25"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O16">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13,27"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="12.95,26.95;19.05,28.95"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="13,27"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="6"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="1.9000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="inner_color">
+ <dia:color val="#bfbfbf"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#CLOSED#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="80" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.80000000000000004"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16,28.25"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O17">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21,23.9"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="15.5,23.85;21.05,27.05"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="21,23.9"/>
+ <dia:point val="21,27"/>
+ <dia:point val="16,24"/>
+ <dia:point val="16,27"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O14" connection="13"/>
+ <dia:connection handle="3" to="O16" connection="2"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O18">
+ <dia:attribute name="obj_pos">
+ <dia:point val="19,17.95"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.945,17.8995;25.05,28.4505"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="19,17.95"/>
+ <dia:point val="24,18"/>
+ <dia:point val="25,21"/>
+ <dia:point val="25,23"/>
+ <dia:point val="25,25"/>
+ <dia:point val="24,28"/>
+ <dia:point val="19,27.95"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O13" connection="8"/>
+ <dia:connection handle="6" to="O16" connection="8"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Line" version="0" id="O19">
+ <dia:attribute name="obj_pos">
+ <dia:point val="18,22.95"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="12.95,22.45;18.05,23.45"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="18,22.95"/>
+ <dia:point val="13,22.95"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O14" connection="7"/>
+ <dia:connection handle="1" to="O15" connection="8"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O20">
+ <dia:attribute name="obj_pos">
+ <dia:point val="14.5,27"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="9.5,23.85;14.5851,27.0575"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="14.5,27"/>
+ <dia:point val="15,24"/>
+ <dia:point val="10,27"/>
+ <dia:point val="10,23.9"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O16" connection="1"/>
+ <dia:connection handle="3" to="O15" connection="13"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O21">
+ <dia:attribute name="obj_pos">
+ <dia:point val="8.5,22"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="8.42939,17.5449;13.3716,22.0706"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="8.5,22"/>
+ <dia:point val="13,17.95"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-0.74169570721594136"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O15" connection="1"/>
+ <dia:connection handle="1" to="O13" connection="7"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O22">
+ <dia:attribute name="obj_pos">
+ <dia:point val="19,7.95"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.5,7.9;22.05,17.525"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="19,7.95"/>
+ <dia:point val="19,17.475"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-3"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O11" connection="8"/>
+ <dia:connection handle="1" to="O13" connection="6"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O23">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21,4"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.4981,3.9432;23.6948,17.5979"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="21,4"/>
+ <dia:point val="19,17.475"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-3.5943353432190368"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O10" connection="13"/>
+ <dia:connection handle="1" to="O13" connection="6"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Arc" version="0" id="O24">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21,4"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.5011,3.94034;21.8578,13.1573"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="21,4"/>
+ <dia:point val="19,13"/>
+ </dia:attribute>
+ <dia:attribute name="curve_distance">
+ <dia:real val="-1.6769027424613245"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O10" connection="13"/>
+ <dia:connection handle="1" to="O12" connection="8"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O25">
+ <dia:attribute name="obj_pos">
+ <dia:point val="10.025,0.825"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="7.2,0.225;12.85,3.225"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#New bug from a
+user with canconfirm
+or a product without
+UNCONFIRMED state#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.69999999999999996"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="10.025,0.825"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="1"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O26">
+ <dia:attribute name="obj_pos">
+ <dia:point val="20.325,4.48321"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="14.675,3.93321;20.325,5.28321"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug confirmed or
+receives enough votes#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="20.325,4.48321"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="2"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O27">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16.2865,10.1"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="16.2865,9.55;20.3865,10.9"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Developer takes
+possession#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16.2865,10.1"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O28">
+ <dia:attribute name="obj_pos">
+ <dia:point val="10.7629,9.45"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="8.0629,8.8825;10.7804,10.285"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Ownership
+is changed#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="10.7629,9.45"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="2"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O29">
+ <dia:attribute name="obj_pos">
+ <dia:point val="21.4576,6.43623"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="17.3576,5.88623;21.4576,7.23623"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Developer takes
+possession#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="21.4576,6.43623"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="2"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Flowchart - Box" version="0" id="O30">
+ <dia:attribute name="obj_pos">
+ <dia:point val="4.81289,11.0073"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="4.76289,10.9573;10.5629,16.2573"/>
+ </dia:attribute>
+ <dia:attribute name="elem_corner">
+ <dia:point val="4.81289,11.0073"/>
+ </dia:attribute>
+ <dia:attribute name="elem_width">
+ <dia:real val="5.6999999999999993"/>
+ </dia:attribute>
+ <dia:attribute name="elem_height">
+ <dia:real val="5.1999999999999993"/>
+ </dia:attribute>
+ <dia:attribute name="inner_color">
+ <dia:color val="#bfbfbf"/>
+ </dia:attribute>
+ <dia:attribute name="show_background">
+ <dia:boolean val="true"/>
+ </dia:attribute>
+ <dia:attribute name="corner_radius">
+ <dia:real val="0.10000000000000001"/>
+ </dia:attribute>
+ <dia:attribute name="padding">
+ <dia:real val="0.14999999999999999"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Possible resolutions:
+ FIXED
+ DUPLICATE
+ WONTFIX
+ WORKSFORME
+ INVALID#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="4.91289,11.7573"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Line" version="0" id="O31">
+ <dia:attribute name="obj_pos">
+ <dia:point val="10.3629,14.9073"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="10.3278,14.8722;13.1815,17.1815"/>
+ </dia:attribute>
+ <dia:attribute name="conn_endpoints">
+ <dia:point val="10.3629,14.9073"/>
+ <dia:point val="13.1464,17.1464"/>
+ </dia:attribute>
+ <dia:attribute name="numcp">
+ <dia:int val="1"/>
+ </dia:attribute>
+ <dia:attribute name="line_width">
+ <dia:real val="0.050000000000000003"/>
+ </dia:attribute>
+ <dia:attribute name="line_style">
+ <dia:enum val="4"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O30" connection="10"/>
+ <dia:connection handle="1" to="O13" connection="0"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O32">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16.299,15.3073"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="16.299,14.7573;20.449,16.1073"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Development is
+finished with bug#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16.299,15.3073"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O33">
+ <dia:attribute name="obj_pos">
+ <dia:point val="11.4365,21"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="11.4365,20.45;15.5365,21.8"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#QA not satisfied
+with solution#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="11.4365,21"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O34">
+ <dia:attribute name="obj_pos">
+ <dia:point val="16.8365,21.05"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="16.8365,20.5;20.7365,21.85"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#QA verifies
+solution worked#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="16.8365,21.05"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O35">
+ <dia:attribute name="obj_pos">
+ <dia:point val="17.224,25.875"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="17.224,25.325;20.574,26.075"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug is closed#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="17.224,25.875"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O36">
+ <dia:attribute name="obj_pos">
+ <dia:point val="22.5365,18.5"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="22.5365,17.95;25.8865,18.7"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug is closed#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="22.5365,18.5"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O37">
+ <dia:attribute name="obj_pos">
+ <dia:point val="9.62401,17.8111"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="5.52401,17.2611;9.62401,18.6111"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Developer takes
+possession#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="9.62401,17.8111"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="2"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O38">
+ <dia:attribute name="obj_pos">
+ <dia:point val="11.1865,19.15"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="11.1865,18.6;13.3365,19.95"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Issue is
+resolved#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="11.1865,19.15"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O39">
+ <dia:attribute name="obj_pos">
+ <dia:point val="11.049,25.325"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="11.049,24.775;15.049,25.525"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug is reopened#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="11.049,25.325"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O40">
+ <dia:attribute name="obj_pos">
+ <dia:point val="13.9365,22.75"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="13.9365,22.2;17.9365,22.95"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug is reopened#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="13.9365,22.75"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O41">
+ <dia:attribute name="obj_pos">
+ <dia:point val="19,17.95"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.9494,3.46851;29.05,18.0006"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="19,17.95"/>
+ <dia:point val="23,18"/>
+ <dia:point val="29,14"/>
+ <dia:point val="29,11"/>
+ <dia:point val="29,8"/>
+ <dia:point val="27,7"/>
+ <dia:point val="23.9286,3.85355"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O13" connection="8"/>
+ <dia:connection handle="6" to="O10" connection="15"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O42">
+ <dia:attribute name="obj_pos">
+ <dia:point val="24,10"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="24,9.45;28.15,10.8"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Development is
+finished with bug#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="24,10"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O43">
+ <dia:attribute name="obj_pos">
+ <dia:point val="23.8536,22.1464"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="23.5359,3.46851;29.0712,22.2033"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="23.8536,22.1464"/>
+ <dia:point val="29.6426,21.2696"/>
+ <dia:point val="29,14"/>
+ <dia:point val="29,11"/>
+ <dia:point val="29,8"/>
+ <dia:point val="27,7"/>
+ <dia:point val="23.9286,3.85355"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O14" connection="4"/>
+ <dia:connection handle="6" to="O10" connection="15"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - BezierLine" version="0" id="O44">
+ <dia:attribute name="obj_pos">
+ <dia:point val="18.8536,28.7536"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="18.8032,3.46851;29.05,28.8043"/>
+ </dia:attribute>
+ <dia:attribute name="bez_points">
+ <dia:point val="18.8536,28.7536"/>
+ <dia:point val="28.0326,28.8213"/>
+ <dia:point val="29,24"/>
+ <dia:point val="29,21"/>
+ <dia:point val="29,18"/>
+ <dia:point val="29,14"/>
+ <dia:point val="29,11"/>
+ <dia:point val="29,8"/>
+ <dia:point val="27,7"/>
+ <dia:point val="23.9286,3.85355"/>
+ </dia:attribute>
+ <dia:attribute name="corner_types">
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ <dia:enum val="0"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow">
+ <dia:enum val="22"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_length">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:attribute name="end_arrow_width">
+ <dia:real val="0.5"/>
+ </dia:attribute>
+ <dia:connections>
+ <dia:connection handle="0" to="O16" connection="15"/>
+ <dia:connection handle="9" to="O10" connection="15"/>
+ </dia:connections>
+ </dia:object>
+ <dia:object type="Standard - Text" version="0" id="O45">
+ <dia:attribute name="obj_pos">
+ <dia:point val="25,4"/>
+ </dia:attribute>
+ <dia:attribute name="obj_bb">
+ <dia:rectangle val="25,3.45;30.1,4.8"/>
+ </dia:attribute>
+ <dia:attribute name="text">
+ <dia:composite type="text">
+ <dia:attribute name="string">
+ <dia:string>#Bug is reopened,
+was never confirmed#</dia:string>
+ </dia:attribute>
+ <dia:attribute name="font">
+ <dia:font family="sans" style="0" name="Helvetica"/>
+ </dia:attribute>
+ <dia:attribute name="height">
+ <dia:real val="0.59999999999999998"/>
+ </dia:attribute>
+ <dia:attribute name="pos">
+ <dia:point val="25,4"/>
+ </dia:attribute>
+ <dia:attribute name="color">
+ <dia:color val="#000000"/>
+ </dia:attribute>
+ <dia:attribute name="alignment">
+ <dia:enum val="0"/>
+ </dia:attribute>
+ </dia:composite>
+ </dia:attribute>
+ </dia:object>
+ </dia:layer>
+</dia:diagram>
--- /dev/null
+Release Notes for Bugzilla version 3.0 and higher are available in HTML
+format, either on the bugzilla.org website, or in your current installation,
+linked from the index page.
+
+bugzilla.org links for release notes
+------------------------------------
+3.0.2: http://www.bugzilla.org/releases/3.0.2/release-notes.html
+
+***************************************
+*** The Bugzilla 2.22 Release Notes ***
+***************************************
+
+Table of Contents
+*****************
+
+- Introduction
+- Important Updates In This Point Release
+- Minimum Requirements
+ * Perl
+ * For MySQL Users
+ * For PostgreSQL Users
+ * Required Perl Modules
+ * Optional Perl Modules
+- What's New?
+ * Complete PostgreSQL Support
+ * Parameters In Sections
+ * One Codebase, Multiple Databases
+ * UTF-8 for New Installations
+ * Admins Can Impersonate Users
+ * Bug Import and Moving Improvements
+ * Adding Individual Bugs to Saved Searches
+ * Attach URLs
+ * Optional "Strict Isolation" for Groups
+ * "editcomponents" Change
+ * "shutdownhtml" Change
+ * Miscellaneous Improvements
+ * All Changes
+- Deprecated Features
+- Outstanding Issues (<======================== IMPORTANT, PLEASE READ)
+- How to Upgrade From An Older Bugzilla
+ * Steps for Upgrading
+- Code Changes Which May Affect Customizations
+ * CGI.pl is Gone
+ * Other Changes
+- Security Fixes In 2.22 Releases
+- Release Notes for Previous Versions
+
+Introduction
+************
+Bugzilla 2.22 is one of our most polished releases. We did a lot of
+small cleanups to make Bugzilla easier to use and more useful in
+many, many small ways, in addition to adding some major new features.
+
+This document contains the release notes for Bugzilla 2.22.
+In this document, recently added, changed, and removed features
+of Bugzilla are described. If you are upgrading from an older version,
+you will definitely want to read these release notes in detail, so that
+you have an idea of what has changed.
+
+If you are upgrading from a version before 2.20, also read the 2.20
+release notes (lower in this file) and any previous release notes.
+
+If you are installing a new Bugzilla, you will still want to look over
+the release notes to see if there is any particularly important
+information that affects your installation.
+
+If you would like to contribute code to Bugzilla, read our
+Contributor's Guide at:
+
+http://www.bugzilla.org/docs/contributor.html
+
+
+Important Updates In This Point Release
+***************************************
+
+This section describes bugs fixed in releases after the original 2.22
+release.
+
+Version 2.22.2
+--------------
+
++ Make Bugzilla compatible with Template Toolkit 2.15 (bug 357374)
+
++ Make Bugzilla compatible with versions of MySQL higher than 5.0.25
+ (bug 321645)
+
++ Sanity Check can now only be run by people with the "admin" privilege.
+ (bug 91761)
+
+Version 2.22.1
+--------------
+
++ When sending mail, Bugzilla could throw the error "Insecure dependency in
+ exec while running with -T switch" (bug 340538).
+
++ Using the public webdot server (for dependency graphs) should work
+ again (bug 351243).
+
++ The "I'm added to or removed from this capacity" email preference
+ wasn't working for new bugs (bug 349852).
+
++ The original release of 2.22 incorrectly said it required Template-Toolkit
+ version 2.08. In actual fact, Bugzilla requires version 2.10 (bug 351478).
+
++ votes.cgi would crash if your bug was the one confirming a bug (bug 351300).
+
++ checksetup.pl now correctly reports if your Template::Plugin::GD module
+ is missing. If missing, it could lead to charts and graphs not working
+ (bug 345389).
+
++ The "Keyword" field on buglist.cgi was not sorted alphabetically, so
+ it wasn't very useful for sorting (bug 342828).
+
++ Sendmail will no longer complain about there being a newline in the
+ email address, when Bugzilla sends mail (bug 331365).
+
++ contrib/bzdbcopy.pl would try to insert an invalid value into the
+ database, unnecessarily (bug 335572).
+
++ Deleting a bug now correctly deletes its attachments from the database
+ (bug 339667).
+
+
+Minimum Requirements
+********************
+
+Perl
+----
+
+ Perl v5.6.1 (Non-Windows platforms)
+ ActiveState Perl v5.8.1 (Windows only)
+
+ Note that this is the last release of Bugzilla to support perl 5.6.x--
+ future versions will require perl 5.8.
+
+For MySQL Users
+---------------
+
+ MySQL v4.0.14 (changed from 2.20)
+ perl module: DBD::mysql v2.9003 (changed from 2.18)
+
+For PostgreSQL Users
+--------------------
+
+ PostgreSQL 7.3.x
+ perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+)
+
+ WARNING: DBD::Pg 1.43 has a bug which causes checksetup.pl to fail
+ and corrupt the database. If you are using DBD::Pg 1.43, either downgrade
+ to 1.41 or upgrade to 1.45 (1.42 and 1.44 seem broken somehow too).
+
+ Note that this is the last release of Bugzilla to support PostgreSQL 7.x.
+ Future versions will require PostgreSQL 8.0 and DBD::Pg 1.45.
+
+Required Perl Modules
+---------------------
+
+ AppConfig v1.52
+ CGI v2.93
+ Data::Dumper (any)
+ Date::Format v2.21
+ DBI v1.38
+ File::Spec v0.84
+ File::Temp (any)
+ Template Toolkit v2.10 (changed from 2.20)
+ Text::Wrap v2001.0131
+ Mail::Mailer v1.67 (changed from 2.20)
+ MIME::Base64 v3.01 (new in 2.22)
+ MIME::Parser v5.406 (new in 2.22)
+ Storable (any)
+
+ Note: The SMTP support in Mail::Mailer 1.73 (the most recent version)
+ is broken. The last known working version is 1.67.
+
+Optional Perl Modules
+---------------------
+
+ Chart::Base v1.0
+ GD v1.20
+ GD::Graph (any)
+ GD::Text::Align (any)
+ Net::LDAP (any)
+ PatchReader v0.9.4
+ XML::Twig (any) (new in 2.22)
+ Image::Magick (new in 2.22)
+
+
+What's New?
+***********
+
+Complete PostgreSQL Support
+---------------------------
+Bugzilla 2.20 contained experimental support for PostgreSQL.
+In Bugzilla 2.22, PostgreSQL support is fully complete and stable. Using
+PostgreSQL with Bugzilla should be as stable as using MySQL, and if
+you experience any problems they will be taken as seriously as if you
+were running MySQL.
+
+There are no known remaining major problems with Bugzilla on PostgreSQL.
+All features of Bugzilla have been tested and work.
+
+
+Parameters In Sections
+----------------------
+Long-time users of Bugzilla know that over time the parameter list has
+grown quite large. It has now been split into sections to make it easier
+to use.
+
+
+One Codebase, Multiple Databases
+--------------------------------
+There is now limited support for having multiple projects use the
+same Bugzilla codebase, but all have separate databases.
+
+The different projects can have their own templates and their own
+bug database, but all use the same set of Bugzilla code in the same
+directory.
+
+To enable this, set an environment variable called PROJECT when
+calling the Bugzilla CGIs. Then for each project, you can have
+a localconfig.PROJECT (where "PROJECT" is the value of the PROJECT
+environment variable) file for the database parameters, and a
+template/en/PROJECT directory (where "PROJECT" is the value of the
+PROJECT environment variable)
+
+This feature isn't documented yet, but we hope to have documentation for
+it soon.
+
+
+UTF-8 For New Installations
+---------------------------
+If this is the first time you're installing Bugzilla, it will now use
+UTF-8 encoding for all pages, automatically. It will also send emails
+in UTF-8. This eliminates most of the internationalization problems
+users have experienced, as one Bugzilla page may now contain any number
+of languages simultaneously.
+
+If you are upgrading and you want to use UTF-8, just turn on the "utf8"
+Parameter. However, realize that if you have non-UTF-8 data in your
+Bugzilla, it will appear unreadable. (If you just have ASCII in your
+database, you're safe to turn on the "utf8" parameter, definitely.)
+
+
+Admins Can Impersonate Users
+----------------------------
+User impersonation (think of the su/sudo command on Unix) allows you
+to view pages and perform actions as if you are logged in as someone else,
+without having to know their password.
+
+A user in the new "bz_sudoers" group has the option of "becoming"
+any user in Bugzilla. Once they "become" that user, they *are* that user
+for the rest of the session, until they decide to switch back to being
+themselves.
+
+However, they cannot "become" any user in the "bz_sudo_protect" group.
+This group includes everybody in the "admin" and "bz_sudoers" groups by
+default.
+
+Any time a user is impersonated, they will get an email notifying them
+who has impersonated them.
+
+
+Bug Import and Moving Improvements
+----------------------------------
+The XML Import script, importxml.pl, has been completely re-written.
+
+It now:
+
+ * Correctly imports the "priority" field
+ * Understands when the "Reporter" or "CC List" security boxes
+ are unchecked on the bug.
+ * Places bugs in the appropriate groups
+ * Allows attachments to be imported
+ * Is much more forgiving about small problems in the XML
+
+
+Adding Individual Bugs to Saved Searches (Tagging)
+--------------------------------------------------
+Users now have the option of adding an individual bug to any
+particular Saved Search. Individual users that disagree with the site
+default can add or remove this feature (which appears as an entry box
+visible in the footer) by changing the General Preferences setting
+called "Enable tags for bugs".
+
+
+Attach URLs
+-----------
+Instead of attaching a file, you can now also attach a URL to a bug.
+This will show up just like an attachment on show_bug.cgi, but when
+you click on it, it will take you to the URL.
+
+To enable this, turn on the "allow_attach_url" parameter.
+
+
+Optional "Strict Isolation" for Groups
+--------------------------------------
+If you turn on the "strict_isolation" parameter in Bugzilla, you
+will *not* be able to add any user to the CC field (or set them
+as an Assignee or QA Contact) unless that user could normally see
+the bug. That is, you will no longer be able to "accidentally"
+(or intentionally) give somebody access to a bug that they
+otherwise couldn't see.
+
+
+"editcomponents" Change
+-----------------------
+Previously, all users who had "editcomponents" could see every Product,
+using the editcomponents.cgi script. Now, users with "editcomponents"
+can only see Products that they normally have access to.
+
+This restriction also affects editversions.cgi, editmilestones.cgi and
+editproducts.cgi.
+
+
+"shutdownhtml" Change
+---------------------
+All of Bugzilla is now affected by the "shutdownhtml" parameter,
+including command-line scripts. checksetup.pl is exempt. Many scripts
+(such as collectstats.pl and whine.pl) will just exit silently when
+"shutdownhtml" is turned on.
+
+
+Miscellaneous Improvements
+--------------------------
+
+- Added a frequently-requested user preference for whether or not to go
+ to the next bug in your list after submitting changes to a bug.
+
+- The ability to do relative date searches (like "1d" for "1 day" or "1w"
+ for "1 week") by hour now, in addition to days and other units of time.
+
+- "Alias" added to the New Bug form, for users with editbugs.
+
+- Users can now actually see the descriptions of flags that you enter
+ in editflagtypes.cgi. The description will appear as a tooltip
+ when a user places their mouse over the flag name on show_bug.cgi.
+
+- Bugzilla will optionally convert BMP attachments into PNGs for you.
+ See the "convert_uncompressed_images" in the "Attachments" section
+ of the Parameters.
+
+- You can now edit the Status Whiteboard when you are changing multiple
+ bugs at once.
+
+- The way that groups work in the database has changed, and large-scale
+ Bugzilla use with many concurrent users should be much faster, as a
+ result. (Technical Details: The need for Bugzilla to "derive groups"
+ has gone away pretty much entirely.)
+
+- Performance improvements on searching attachment information that's not
+ the actual content of the attachment (such as searching the Attachment
+ Description or the Attachment MIME Type)
+
+- You can now specify multiple email addresses, comma-separated, when
+ setting the requestee of a flag, and it will set the flag once for each
+ of those email addresses
+
+- "Bug Creation Time" is now searchable in the Boolean Charts.
+
+- When you mark a comment on a bug as private, the background color
+ of the comment will change immediately. However, in order for
+ Bugzilla to register that the comment is now private, you still
+ have to "submit" the changes.
+
+- Emails sent from Bugzilla now have "X-Bugzilla-Keywords" and
+ "X-Bugzilla-Severity" by default, containing the information
+ from the related Bugzilla fields.
+
+- You can now change the assignee and QA contact on multiple bugs at
+ once even when those bugs are in different products.
+
+- contrib/merge-users.pl allows you to merge two user accounts. This is
+ particulary useful when a user opened several accounts and only one should
+ be kept. It also lets you merge a deleted account with an existing one.
+
+All Changes
+-----------
+
+If you'd like to see all the changes between Bugzilla 2.20 and Bugzilla
+2.22, see:
+
+http://tinyurl.com/9p2tm
+
+
+Deprecated Features
+*******************
+
+- This is the last release of Bugzilla to support perl 5.6.x. All future
+ versions of Bugzilla will require at least perl 5.8.
+
+ This is the last release of Bugzilla to support PostgreSQL 7.x. Future
+ releases using PostgreSQL will require PostgreSQL 8.0 and DBD::Pg 1.45.
+
+Outstanding Issues
+******************
+
+- bug 305836: PostgreSQL users: do not use DBD::Pg version 1.43 with
+ Bugzilla. It has a bug which can corrupt the database. Version 1.41
+ is fine. Version 1.45 or higher is fine too.
+
+- (No Bug Number) VERY IMPORTANT: If you have customized the values in
+ your Status/Resolution field, you must edit checksetup.pl BEFORE YOU
+ RUN IT. Find the line that starts like this:
+
+ bug_status => ["UNCONFIRMED",
+
+ That's where you set the values for the Status field.
+
+ resolution => ["","FIXED",
+
+ And that's where you set values for the Resolution field.
+
+ Those are both near line 1826 in checksetup.pl.
+
+ If you forget to do this, you will have to manually edit the "bug_status"
+ and "resolution" tables in the database to contain the correct values.
+
+- bug 276230: The support for restricting access to particular Categories of
+ New Charts is not complete. You should treat the 'chartgroup' Param as the
+ only access mechanism available. However, additionally, charts migrated from
+ Old Charts will be restricted to the groups that are marked MANDATORY for
+ the corresponding Product. There is currently no way to change this
+ restriction, and the groupings will not be updated if the group configuration
+ for the Product changes.
+
+- bug 37765: If you use the "sendmail" support of Bugzilla,
+ and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.)
+ make sure the "sendmailnow" parameter is ON or Bugzilla will not send
+ e-mail correctly.
+
+- bug 69621: If you rename or remove a keyword that is in use on bugs, you will
+ need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing
+ the option to rebuild the cache when it asks. Otherwise keywords may not show
+ up properly in search results.
+
+- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for
+ example, if you use a translation of Bugzilla), don't enable the XS::Stash
+ option when you install the Template Toolkit, or your Bugzilla installation
+ may become slow. This problem is fixed in a not-yet-released version of the
+ Template Toolkit (after 2.14).
+
+- Bug 99215: Flags are not protected by "mid-air collision" detection.
+ Nor are any attachment changes.
+
+- Bug 89822: When changing multiple bugs at the same time, there is no
+ "mid-air collision" protection.
+
+- bug 322955: The email interface (bug_mail.pl) in the contrib/ directory
+ has not been maintained (as it has no maintainer), and does not work
+ properly. We hope to have this fixed in our next major release of
+ Bugzilla; however, any help or contributions in this area are very
+ welcome.
+
+
+How to Upgrade From An Older Bugzilla
+*************************************
+
+NOTE: Upgrading from a large installation (over 10,000 bugs) running 2.18
+ or before may take a significant amount of time. checksetup will
+ try to let you know how long it will take, but expect downtime
+ of an hour or more if you have many bugs, many attachments,
+ or many users.
+
+Steps for Upgrading
+-------------------
+
+1) Read these entire Release Notes, particularly the "Outstanding Issues"
+ and "Security Fixes" sections.
+
+2) View the Sanity Check (sanitycheck.cgi) page on your installation before
+ upgrading. Attempt to fix all warnings that the page produces before
+ you go any further, or you may experience problems during your upgrade.
+
+3) Make a backup of the Bugzilla database before you upgrade, perhaps
+ by using mysqldump. THIS IS VERY IMPORTANT. If anything goes wrong
+ during the upgrade, your installation can be corrupted beyond
+ recovery. Having a backup keeps you safe.
+
+ Example:
+
+ mysqldump -u root -p bugs > bugs-db.sql
+
+4) Replace the files in your installation with the new version of Bugzilla,
+ or you can try to use CVS to upgrade. The bugzilla.org website has
+ instructions on how to do the actual installation.
+
+ You can also use a brand-new Bugzilla directory, as long as you
+ copy over the old data/ directory and the "localconfig" file to the
+ new installation.
+
+5) Run checksetup.pl after you install the new version.
+
+7) View the Sanity Check page again after you run checksetup.pl.
+
+8) It is recommended that, if possible, you fix any problems you find
+ immediately. Failure to do this may mean that Bugzilla will not work
+ correctly. Be aware that if the sanity check page contains more errors after
+ an upgrade, it doesn't necessarily mean there are more errors in your
+ database, as additional tests are added to the sanity check over time, and
+ it is possible that those errors weren't being checked for in the old
+ version.
+
+9) This version of Bugzilla contains improvements to the email that
+ Bugzilla sends when a bug is changed. The template for that email
+ is contained in the "newchangedmail" parameter. If you would like
+ to take advantage of the email enhancements in this version of
+ Bugzilla, reset that parameter to its default. (You can customize
+ it after that again, if you want.)
+
+
+Code Changes Which May Affect Customizations
+********************************************
+
+CGI.pl is Gone
+--------------
+The CGI.pl file, which used to contain many global functions, and which
+also contained initialization code for every CGI, is gone. The functions
+have been moved to various places and sometimes renamed.
+
+The initialization code that used to happen inside CGI.pl is now inside
+of Bugzilla.pm. All CGIs must "use Bugzilla" in one way or another. (Some
+CGIs "use Bugzilla" by doing "require globals.pl".)
+
+
+Deriving Groups No Longer Happens
+---------------------------------
+Bugzilla no longer needs to "derive groups" in advance. That is, previously
+Bugzilla used to flatten the group heirarchy into the user_group_map
+table. (That is, show that a user was in every group they were in,
+even if they were only in that group because they belonged to *another*
+group.) Now the table only contains groups that the user is in directly,
+and groups that they are in because of a regexp.
+
+Instead, The Bugzilla::User->group function determines the groups a user
+is in when called.
+
+We did this because the group derivation was causing a lot of complexity
+in the code, and also deriving the groups was a slow process that
+frequently had to happen inside of a database lock while sending mail
+or viewing a bug list.
+
+See https://bugzilla.mozilla.org/show_bug.cgi?id=304583 for details.
+
+
+Other Changes
+-------------
+
+- The move.pl script's functionality has been merged into process_bug.cgi.
+
+- $::template and $::vars are gone from globals.pl. Instead of $::template,
+ use Bugzilla->template. Every script creates the $vars variable by itself
+ instead of using a global $::vars variable.
+
+- $::userid is gone. Instead use Bugzilla->user->id.
+
+- QuickSearch is now in perl instead of in JavaScript. The code is in
+ Bugzilla/Search/QuickSearch.pm. This makes it much easier to customize,
+ and it also fixes some long-standing issues that QuickSearch had.
+
+- Attachment data is now in the attach_data table. Other information
+ about attachments is still in the "attachments" table.
+
+- Much like the 2.20 release, many functions have been removed from
+ globals.pl and CGI.pl. They were moved elsewhere and renamed.
+ Search RESOLVED bugs in bugzilla.mozilla.org for the old
+ version of the function name, and that will usually show you
+ the bug where we moved the function, allowing you to find out
+ what the new name and location is.
+
+- This is the last release that contains the deprecated
+ SendSQL, SqlQuote, FetchSqlData, MoreSqlData, and FetchOneColumn
+ functions. Instead, you should use DBI functions. For a very brief
+ example, see:
+
+ http://www.bugzilla.org/docs/developer.html#sql-sendreceive
+
+
+Security Fixes in 2.22 Releases
+*******************************
+
+A long-standing, well-known security issue is finally resolved in Bugzilla
+2.22: Previously, the "Session ID" of each user could be easily guessed,
+given enough time. This could have allowed an attacker to take over a
+user's account, in certain circumstances. Now, the "Session ID" is totally
+random, resolving this issue. See bug 119524 in bugzilla.mozilla.org for
+details.
+
+If you are very concerned about the security of your Bugzilla installation,
+it would be a very good idea to run the following command on your
+database immediately after upgrading:
+
+TRUNCATE TABLE logincookies;
+
+This is actually safe to do at any time--it just forces a logout of
+every single user, even those with saved sessions. (It invalidates
+every login cookie Bugzilla has ever given out.)
+
+Version 2.22.2
+--------------
+
+A Cross-Site Scripting vulnerability is fixed in Bugzilla 2.22.2. You can
+read the details of the fix at:
+
+http://www.bugzilla.org/security/2.20.3/
+
+Version 2.22.1
+--------------
+
+The Bugzilla team fixed two Information Leaks and three Cross-Site
+Scripting vulnerabilities that existed in versions of Bugzilla
+prior to 2.22.1. We strongly recommend that you update any 2.22
+installation to 2.22.1, to be protected from these vulnerabilities.
+
+In addition, we have made an enhancement to security in this version
+of Bugzilla. In previous versions, it was possible for malicious
+users to exploit administrators in certain ways. Although this has
+never happened (to our knowledge) in the real world, we thought it
+was important that we protect administrators from this sort of attack.
+
+You can see details on all the vulnerabilities and enhancements at:
+
+http://www.bugzilla.org/security/2.18.5/
+
+
+Release Notes For Previous Versions
+************************************
+
+***************************************
+*** The Bugzilla 2.20 Release Notes ***
+***************************************
+
+Table of Contents
+*****************
+
+- Introduction
+- Important Updates in this Point Release
+ * Version 2.20.1
+ * Version 2.20.2
+- Minimum Requirements
+ * Perl
+ * For MySQL Users
+ * For PostgreSQL Users
+ * Required Perl Modules
+ * Optional Perl Modules
+- What's New?
+ * Experimental PostgreSQL Support
+ * New User-Interface Color/Style
+ * Higher-Level Categorization of Bugs (above "Product")
+ * Regular Reports by Email of Complex Queries ("Whining")
+ * "Environment Variable" Authentication Method
+ * User-List Drop-Down Menus
+ * Server-Side Comment Wrapping
+ * UI for Editing Priority, OS, Platform, and Severity
+ * Bugzilla Queries as RSS
+ * Choice of E-Mail Sending Methods
+ * "User Preferences"
+ * "Large Attachment" Storage
+ * "User Visibility" Controls
+ * Miscellaneous Improvements
+ * All Changes
+- Deprecated Features
+- Outstanding Issues (<======================== IMPORTANT, PLEASE READ)
+- How to Upgrade From An Older Bugzilla
+ * Steps for Upgrading
+- Code Changes Which May Affect Customizations
+ * The New Database-Compatibility Layer
+ * If You Customize Your Database...
+ * Many Functions Renamed
+ * User Preferences
+ * Other Changes
+- Security Fixes In 2.20 Releases
+- Release Notes for Previous Versions
+
+
+Introduction
+************
+
+This document contains the release notes for Bugzilla 2.20.
+In this document, recently added, changed, and removed features
+of Bugzilla are described. If you are upgrading from an older version,
+you will definitely want to read these release notes in detail, so that
+you have an idea of what has changed.
+
+If you are upgrading from a version before 2.18, also read the 2.18 release
+notes (lower in this file) and any previous release notes.
+
+If you are installing a new Bugzilla, you will still want to look over
+the release notes to see if there is any particularly important information
+that affects your installation.
+
+The 2.20 release has had about nine months of development since 2.18, but
+they were nearly the most active nine months in Bugzilla's history. We hope
+that users will appreciate our many external changes, and that Bugzilla
+administators will find that our internal changes make their lives easier.
+
+If you would like to contribute code to Bugzilla, read our
+Contributor's Guide at:
+
+http://www.bugzilla.org/docs/contributor.html
+
+
+Important Updates In This Point Release
+***************************************
+
+Version 2.20.1
+--------------
+
++ Many PostgreSQL fixes, including fixing whine.pl on Pg 8
+ (bug 301062) and fixing the --regenerate option of collectstats.pl
+ for all versions of Pg (bug 316971). However, users who want full
+ PostgreSQL support are encouraged to use the 2.22 series, as
+ certain PostgreSQL bugs were discovered that will not be fixed
+ in 2.20 (their fixes were too complex).
+
++ In Bugzilla 2.20, the "administrator" user created by checksetup.pl
+ would not ever be sent email, because their email preferences were
+ left blank. This has been fixed for 2.20.1. However, if you created
+ this administrative user with Bugzilla 2.20, make sure to go back
+ and enable their Email Preferences. (bug 317489)
+
++ The bzdbcopy.pl script mentioned in these release notes
+ has now actually been checked-in to the 2.20 branch, and so
+ it's included in this release. (bug 291776)
+
++ When there's only one Classification, you now won't be required
+ to pick a Classification on bug entry. (bug 311489)
+
++ You can no longer add dependencies on bugs you can't see.
+ (bug 141593)
+
++ The CC list is included in "New" bug emails, again. (bug 313661)
+
++ In the original 2.20, certain scripts were not correctly using
+ the "shadow database," if it was specified. This has been fixed
+ in 2.20.1. (bug 313695)
+
++ "Saved Searches" that were saved before Bugzilla 2.20, would throw
+ an error if they contained "Days Since Bug Changed." as part of their
+ criteria. This has been fixed in Bugzilla 2.20.1. (bug 302599)
+
++ You can now successfully delete a product even when Target Milestones
+ are turned off. (bug 317025)
+
++ checksetup.pl now correctly pre-compiles templates for languages other
+ than English. (bug 304417)
+
++ The "All Closed" chart that is created by default in New Charts
+ now actually represents all closed bugs, and not all bugs in the
+ product. (bug 300473)
+
++ CSV bug lists with more than 1000 dates now work properly. (bug 257813)
+
++ Various bugs with upgrading from previous versions of Bugzilla
+ have been fixed. (bug 307662, bug 311047, bug 310108)
+
++ Many, many other bug fixes. See http://www.bugzilla.org/status/changes.html
+ for details on what was fixed between 2.20 and 2.20.1.
+
+
+Version 2.20.2
+--------------
+
++ Adding a new attachment and taking the bug at the same time does not
+ create a referential integrity problem anymore if the bug was marked as
+ a duplicate (bug 332705).
+
++ Some additional admin links have been added to the sidebar (bug 282613).
+
++ A new test has been added to our test suite, named 012throwables.t.
+ It will now make sure that all tags used in ThrowUserError() and
+ ThrowCodeError() are defined, and that there are no unused tags (bug 312042).
+
++ whine.pl now works correctly on MySQL 4.0. MySQL 4.1 is not affected
+ (bug 327348).
+
++ contrib/merge-users.pl allows you to merge two user accounts. This is
+ especially useful when a user opened several accounts and only one
+ should be kept (bug 188264).
+
++ The login form on index.cgi again works correctly on a fresh installation
+ (bug 328108).
+
++ Email preferences are now set correctly when creating a new user account
+ using the ENV method (bug 327355).
+
+
+Minimum Requirements
+********************
+
+Perl
+----
+
+ Perl v5.6.1 (changed from 2.18) (Non-Windows platforms)
+ ActiveState Perl v5.8.1 (Windows only)
+
+For MySQL Users
+---------------
+
+ MySQL v3.23.41 (Note: 2.22 will require MySQL 4.x)
+ perl module: DBD::mysql v2.9003 (changed from 2.18)
+
+For PostgreSQL Users (new in 2.20)
+--------------------
+
+ PostgreSQL 7.3.x (8.x has received less testing)
+ perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+)
+
+Required Perl Modules
+---------------------
+
+ AppConfig v1.52
+ CGI v2.93
+ Data::Dumper (any)
+ Date::Format v2.21
+ DBI v1.38 (changed from 2.18)
+ File::Spec v0.84 (changed from 2.18)
+ File::Temp (any)
+ Template Toolkit v2.08
+ Text::Wrap v2001.0131
+ Mail::Mailer 1.65 (new in 2.20)
+ Storable (any) (new in 2.20)
+
+Optional Perl Modules
+---------------------
+
+ Chart::Base v1.0
+ GD v1.20
+ GD::Graph (any)
+ GD::Text::Align (any)
+ Net::LDAP (any)
+ PatchReader v0.9.4
+ XML::Parser (any)
+
+
+What's New?
+***********
+
+Experimental PostgreSQL Support
+-------------------------------
+
+In addition to MySQL, Bugzilla now also supports PostgreSQL. PostgreSQL
+support is still somewhat experimental. Although most major features of
+Bugzilla work on PostgreSQL in 2.20, there are probably still a few bugs
+that need to be worked out.
+
+PostgreSQL support in 2.20 is acceptable for smaller production
+environments that don't mind running into a bug or two now and then.
+
+
+New User-Interface Color/Style
+------------------------------
+
+You'll notice that Bugzilla looks a bit nicer, now! We've made a few
+color and style changes to update the overall "feel" of Bugzilla's
+User Inteface. We plan to do even more work on the UI for 2.22.
+
+
+Higher-Level Categorization of Bugs (above "Product")
+-----------------------------------------------------
+
+Previous Bugzillas had "Products" that you could file bugs in,
+and "Components" for those products. Now, "Products" can be grouped
+into "Classifications."
+
+To enable this, a Bugzilla administrator can turn on the
+"useclassification" parameter, using editparams.cgi.
+
+
+Regular Reports by Email of Complex Queries ("Whining")
+-------------------------------------------------------
+
+You can now tell Bugzilla to do a specific query (or set of queries)
+every X minutes/hours/days, and send you the results by email. This is
+great for keeping track on a daily basis of what's going on in
+your Bugzilla.
+
+
+"Environment Variable" Authentication Method
+--------------------------------------------
+
+You can now tell Bugzilla to accept a certain value passed in from
+Apache as authentication for Bugzilla users. This means that Bugzilla
+now "supports" any type of authentication that Apache supports.
+
+To use this, set the "user_info_class" parameter to "ENV" and, at a
+minimum, set the "auth_env_email" parameter to the name of the
+Environment variable that passes the authenticated user (usually
+"REMOTE_USER"). If your webserver knows users' real names as well, also
+set the "auth_env_realname" parameter. If you are using a true
+single-signon system that assigns an identifier uniquely to an
+individual, even across changes of email address, then set
+"auth_env_id" to the name of that variable.
+
+
+User-List Drop-Down Menus
+-------------------------
+
+Now, anywhere in Bugzilla where you previously had to type in an
+email address by hand, you have the choice of having Bugzilla instead
+display a drop-down menu of users to pick from.
+
+This feature is best for small installations with few users, because
+on large installations the list grows too large to be useful.
+
+To enable the feature, turn on the "usemenuforusers" parameter in
+editparams.cgi.
+
+
+Server-Side Comment Wrapping
+----------------------------
+
+In older Bugzillas, comments were wrapped to 80 characters by the
+user's web browser, and then stored in the database that way. This caused
+problems because some browsers did not wrap comments properly.
+
+Now, Bugzilla stores comments unwrapped and wraps them at display time, so
+all new comments should be properly wrapped. Also, when you upgrade, Bugzilla
+will look for old "mis-wrapped" comments and attempt to wrap them properly.
+
+Lines beginning with the ">" character are assumed to be quotes, and are
+*not* wrapped.
+
+
+UI for Editing Priority, OS, Platform, and Severity
+---------------------------------------------------
+
+Bugzilla now has a User Interface for adding and removing values
+from the OS, Platform, Priority, and Severity fields. You can also
+rename values. Any user in the "editcomponents" group can click
+on the "Field Values" link in their page footer to edit these fields.
+
+Also, the default list of choices for OS and Platform for new
+installations is now much smaller. Old installations will keep
+the same list they have now.
+
+
+Bugzilla Queries as RSS
+-----------------------
+
+You can now view a Bugzilla query as valid RSS 1.0. This means that you
+could add a particular query to your RSS aggregator, if you wanted, to
+keep track of changes in Bugzilla.
+
+To see a query as RSS, just click on the "RSS" link on the bottom of
+your query results. Your query must return at least 1 result in order
+for you to see the link.
+
+
+Choice of E-Mail Sending Methods
+--------------------------------
+
+Bugzilla now uses perl's Mail::Mailer to send e-mail. This means that
+you have several choices of how Bugzilla can send email. By default, it
+still uses sendmail, but it can also use SMTP, qmail, or send all email
+to a file instead of out to users.
+
+A Bugzilla administrator can change which method is used by setting the
+"mail_delivery_method" parameter in editparams.cgi.
+
+
+"User Preferences"
+------------------
+
+Bugzilla users will now notice a section in their Preferences called
+"General Preferences." Administrators will notice a new link called
+"User Preferences."
+
+The Preferences system allows Bugzilla developers to specify arbitrary
+"user preferences" that change the behavior of certain parts of Bugzilla.
+Administrators can control whether or not users are allowed to use these
+preferences, and what the default settings are for a user who is not
+logged in.
+
+The first two preferences that we have implemented are:
+ + "Show a quip at the top of each bug list"
+ + "When viewing a bug, show comments in this order..."
+
+We plan to implement more preferences in the future.
+
+
+"Large Attachment" Storage
+--------------------------
+
+Bugzilla can now store very large attachments on disk instead of in the
+database. These attachments can't be searched with Boolean Charts, but
+they also don't take up database space, and they can be deleted individually
+by the admin.
+
+When uploading an attachment, a user chooses if it's a "Big File." If so,
+it's stored on the disk instead of in the database.
+
+To enable this feature, set the "maxlocalattachmentsize" parameter to
+a non-zero value, in editparams.cgi.
+
+
+"User Visibility" Controls
+--------------------------
+
+It is now possible to prevent users from encountering all other users when
+using user-matching or drop-down userlists. To enable this restriction,
+enable the "usevisibilitygroups" parameter. Once this is enabled, each
+group's permissions will include a new column for "visible." The members
+of any group for which the group being edited is visible will be
+able to user-match this groups's users or see them in dropdown lists.
+
+This does not control who a user can CC on a bug, only who they can
+see in the user-matching lists or drop-downs.
+
+Miscellaneous Improvements
+--------------------------
+
+- Marking an attachment as obsolete will now cancel all pending flag
+ requests for that attachment. That is, any flag that was set to "?"
+ on that attachment will be cleared.
+
+- You can now see which users are "watching" you, on the email
+ preferences page.
+
+- You can tell Bugzilla to mark certain comments in a different
+ color by adding "&mark=1,2,3,5-7" to the end of the show_bug.cgi URL,
+ where "1,2,3,5-7" means "highlight comment 1, comment 2, comment 3, and
+ comments 5 through 7."
+
+- "QA Contact" now also appears on the New Bug page, if QA Contacts are
+ enabled on your installation.
+
+- Bugzilla email now has the "In-Reply-To" header added to it, so if
+ you use an email client that supports threads, you can view your
+ Bugzilla email in threads. If you are upgrading to a new version of
+ Bugzilla, and you want this support, please see the instructions at:
+ https://bugzilla.mozilla.org/attachment.cgi?id=172267
+
+- The email preferences system has been slightly updated. You will notice
+ the changes on your Email Preferences page.
+
+- You can now negate individual "boolean charts" (in the
+ "Advanced Searching" section at the bottom of the "Advanced
+ Search" page). That is, you can add "NOT" to the front of them.
+
+- You can add the words %assignee%, %reporter%, %user% (yourself), or
+ %qacontact% on the right-hand side of a Boolean Chart. For example, you
+ could make a Boolean Chart which said "Reporter" "does not equal"
+ "%assignee%". That would give you all bugs where the Reporter was not
+ the same as the Assignee.
+
+- You can now search Boolean Charts by "commenter."
+
+- If you have a group with no name, it will be re-named to "group_#" where
+ "#" is the numeric Bugzilla Group ID for that group.
+
+- If you are using time-tracking, you can now see a report of time spent
+ on bugs using summarize_time.cgi.
+
+- If you are using time-tracking, bugzilla will now set "hours remaining"
+ to "0" automatically if you RESOLVE a bug, whether you are in the
+ time-tracking group or not.
+
+
+Deprecated Features
+*******************
+
+- Bugzilla 2.20 is the last Bugzilla version to support MySQL 3.23.x.
+ Starting with Bugzilla 2.22, Bugzilla will require MySQL 4.0.x. This will
+ allow Bugzilla to take advantage of the advanced features of MySQL 4.
+
+
+Outstanding Issues
+******************
+
+- (No Bug Number) VERY IMPORTANT: If you have customized the values in
+ your Status/Resolution field, you must edit checksetup.pl BEFORE YOU
+ RUN IT. Find the line that starts like this:
+
+ bug_status => ["UNCONFIRMED",
+
+ That's where you set the values for the Status field.
+
+ resolution => ["","FIXED",
+
+ And that's where you set values for the Resolution field.
+
+ Those are both near line 1826 in checksetup.pl.
+
+ If you forget to do this, you will have to manually edit the "bug_status"
+ and "resolution" tables in the database to contain the correct values.
+
+- bug 37765: VERY IMPORTANT: If you use the "sendmail" support of Bugzilla,
+ and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.)
+ you MUST turn on the "sendmailnow" parameter or Bugzilla will not send
+ e-mail correctly.
+
+- (No Bug Number) If you close your web browser while the process_bug.cgi
+ or post_bug.cgi screen is running, not all emails will be sent, and
+ the next time that that bug is updated, there will be two updates. This
+ is because of a behavior of Apache that is beyond our control.
+
+- bug 276230: The support for restricting access to particular Categories of
+ New Charts is not complete. You should treat the 'chartgroup' Param as the
+ only access mechanism available. However, additionally, charts migrated from
+ Old Charts will be restricted to the groups that are marked MANDATORY for
+ the corresponding Product. There is currently no way to change this
+ restriction, and the groupings will not be updated if the group configuration
+ for the Product changes. This will not be fixed in the 2.20 branch.
+
+- bug 69621: If you rename or remove a keyword that is in use on bugs, you will
+ need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing
+ the option to rebuild the cache when it asks. Otherwise keywords may not show
+ up properly in search results.
+
+- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for
+ example, if you use a translation of Bugzilla), don't enable the XS::Stash
+ option when you install the Template Toolkit, or your Bugzilla installation
+ may become slow. This problem is fixed in a not-yet-released version of the
+ Template Toolkit (after 2.14).
+
+- If at any time you upgraded from a version of Bugzilla between 2.17.4 -
+ 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in
+ order for them to work. See the following link for instructions on how to do
+ this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18
+ If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer,
+ then you don't need to do this.
+
+- (No Bug Number) If your DBI is really, really old, Bugzilla might fail
+ with a strange error message when you try to run checksetup.pl. Try
+ upgrading your DBI using: perl -MCPAN -e'install DBI'
+
+- Bug 126266: Bugzilla does not use UTF-8 to display pages. This means
+ that if you enter non-ASCII characters into Bugzilla, they may
+ display strangely, or Bugzilla may have other problems. For a workaround,
+ see: http://www.bugzilla.org/docs/tip/html/security-bugzilla.html
+ This has been fixed in the 2.22 series.
+
+- Bug 99215: Flags are not protected by "mid-air collision" detection.
+ Nor are any attachment changes.
+
+- Bug 89822: When changing multiple bugs at the same time, there is no
+ "mid-air collision" protection.
+
+- Bug 285614: importxml.pl may be broken in many different ways.
+ It has been fixed and completely re-written in the 2.22 series.
+
+- (No Bug Number) Note that the email interface (bug_mail.pl) in the
+ contrib/ directory has not been maintained (as it has no maintainer),
+ and so may not be working properly. Contributions are welcome, if
+ anybody would like to work on it.
+
+
+Upgrading From An Older Bugzilla
+************************************
+
+NOTE: Running checksetup.pl to upgrade a large installation (over 10,000 bugs)
+ may take a significant amount of time. checksetup will try to let
+ you know how long it will take, but expect downtime of an hour or
+ more if you have many bugs, many attachments, or many users.
+
+Steps for Upgrading
+-------------------
+
+1) View the Sanity Check (sanitycheck.cgi) page on your installation before
+ upgrading. Attempt to fix all warnings that the page produces before
+ you go any further, or you may experience problems during your upgrade.
+
+2) Make a backup of the Bugzilla database before you upgrade, perhaps
+ by using mysqldump.
+
+ Example:
+
+ mysqldump -u root -p --databases bugs > bugs.db.backup
+
+3) Replace the files in your installation with the new version of Bugzilla,
+ or you can try to use CVS to upgrade. The Bugzilla.org website has
+ instructions on how to do the actual installation.
+
+4) Make sure that you run checksetup.pl after you install the new version.
+
+5) View the Sanity Check page again after you run checksetup.pl.
+
+6) It is recommended that, if possible, you fix any problems you find
+ immediately. Failure to do this may mean that Bugzilla will not work
+ correctly. Be aware that if the sanity check page contains more errors after
+ an upgrade, it doesn't necessarily mean there are more errors in your
+ database, as additional tests are added to the sanity check over time, and
+ it is possible that those errors weren't being checked for in the old
+ version.
+
+7) If you want threading support on your Bugzilla email (see the
+ "Miscellaneous Improvements" section above for a description),
+ you need to follow the instructions at:
+ https://bugzilla.mozilla.org/attachment.cgi?id=172267
+
+
+Code Changes Which May Affect Customizations
+********************************************
+
+The New Database-Compatibility Layer
+------------------------------------
+
+For most customizations, this should have no effect. However, you should
+be aware that Bugzilla->dbh is now an instance of "Bugzilla::DB" instead
+of being a DBI object directly. In fact, it's actually a
+Bugzilla::DB::Mysql for MySQL users, and a Bugzilla::DB::Pg for
+PostgreSQL users.
+
+Anything called from $dbh (like $dbh->bz_last_key) that starts with
+"bz_" or "sql_" is a custom Bugzilla function. Anything *not* starting
+with those two prefixes is a normal DBI function.
+
+Methods whose names start with "sql_" generate a piece of a SQL statement.
+They generate the correct version of the statement for whichever database
+you are using.
+
+Methods whose names start with "bz_" do something directly.
+
+You can see more documentation about this at:
+
+http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm
+
+
+If You Customize Your Database...
+---------------------------------
+
+In order to support multiple databases, we had to do something sort of
+tricky. Bugzilla now stores what it *thinks* the current database schema
+is, in a table called bz_schema.
+
+This means that when checksetup changes the database, it updates the
+bz_schema table. When *you* update the database, without using
+checksetup to do it, the bz_schema table is *not* updated.
+
+So, if you're going to add/remove a new column/table to Bugzilla, or if you're
+going to change the definition of a column, try to do it by adding code to
+checksetup in the correct place. (It's one of the places where you find
+the word "--TABLE--".)
+
+You can see the documentation on the $dbh functions used to do this at:
+
+http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm#schema_modification_methods
+
+
+Many Functions Renamed
+----------------------
+
+We are reorganizing the Bugzilla code so that it can support mod_perl. As
+part of this, we are moving all functions out of globals.pl and CGI.pl, and
+into modules in the Bugzilla/ directory.
+
+Sometimes when we moved them, we also renamed them. The new Bugzilla standard
+is to have functions_named_like_this, instead of FunctionsNamedLikeThis.
+
+So if you were using a FunctionNamedLikeThis that no longer works, try just
+using it as function_named_like_this. If that doesn't work, you may have to
+search for where we put it, and what we renamed it to. Most of the functions
+moved to logical places.
+
+If you really can't find it, search bugzilla.mozilla.org using the name
+of the old function. We usually moved one function per bug, so the new
+name will be somewhere in a bug report.
+
+
+User Preferences
+----------------
+
+Bugzilla now has a "User Preferences" system! These preferences are stored
+in the database, and specified by a Bugzilla developer. The Bugzilla
+developers actually call these "settings," but we called them "User
+Preferences" in the UI to make things clearer.
+
+You access a user's settings differently depending on if you are in a
+.cgi file or in a template file:
+
+CGI: Bugzilla->user->settings->{'setting_name'}->value
+Template: Bugzilla.user.settings.setting_name.value
+
+Where "setting_name" is the name of the setting. You can see the current
+setting names in the "setting" table in the database.
+
+Remember that sometimes you may want to check a user's settings when
+making a customization.
+
+To see how to add new settings, search for "add_setting" in checksetup.pl.
+Also see the template: template/en/default/global/setting-descs.none.tmpl.
+
+Other Changes
+-------------
+
+- The $::unconfirmedstate variable has been replaced by the actual string
+ "UNCONFIRMED" everywhere in Bugzilla code.
+
+- The %::FORM and %::MFORM variables are no longer used to access form
+ data. Instead, use $cgi->param(). There are many examples of how to do
+ this, all over the Bugzilla code.
+
+- SendSQL() and related calls are deprecated, and the various $dbh methods
+ should be used instead, such as $dbh->prepare() and $dbh->execute().
+ Bugzilla->dbh is the $dbh handle to use. For more information on how
+ to use the $dbh methods, see: http://search.cpan.org/dist/DBI/DBI.pm
+
+- The $::userid variable will be going away. Use Bugzilla->user->id instead.
+
+- All global variables (any that start with $::, @::, or %::) will
+ be entirely gone by Bugzilla 2.24.
+
+
+Security Fixes in 2.20 Releases
+*******************************
+
+2.20.1
+------
+
+There were three security issues discovered after the release of
+Bugzilla 2.20 that we resolved for Bugzilla 2.20.1. One SQL Injection
+(from an administrator only), one Cross-Site Scripting vulnerability
+(that mostly affects only the user who can exploit it), and one minor,
+extremely specific information leak.
+
+To see details on the vulnerabilities that were fixed, see the
+Security Advisory at:
+
+http://www.bugzilla.org/security/2.16.10/
+
+
+Release Notes for Previous Versions
+***********************************
+
+*****************************************
+*** The Bugzilla 2.18.x Release Notes ***
+*****************************************
+
+Table of Contents
+*****************
+
+- Introduction
+- Important Updates In This Point Release
+ * Version 2.18.1
+ * Version 2.18.2
+- Requirements
+ * Dependency Requirements
+- What's New?
+ * Generic Reporting
+ * Generic Charting
+ * Request System
+ * Enterprise Group Support
+ * User Wildcard Matching
+ * Support for "Insiders"
+ * Time Tracking
+ * Authentication module/LDAP improvements
+ * Improved localization support
+ * Patch Viewer
+ * Comment Reply Links
+ * Full-Text Search
+ * Email Address Munging
+ * Simple Search
+ * Miscellaneous Improvements
+ * All Changes
+- What's Changed?
+ * Flag Names
+ * New Saved Search User Interface
+ * Rules for changing fields
+- Removed Features
+- Code Changes Which May Affect Customizations
+- Recommended Practice for the Upgrade
+ * Note About Upgrading From MySQL With ISAM Tables
+ * Steps for Upgrading
+- Outstanding Issues (<======================== IMPORTANT, PLEASE READ)
+- Security Fixes In 2.18 Releases
+- Detailed Version-To-Version Release Notes
+
+
+Introduction
+************
+
+This document contains the release notes for Bugzilla 2.18 and
+the bugfix releases after 2.18. In this document, recently added,
+changed, and removed features of Bugzilla are described.
+
+The 2.18 release is our current stable series, containing the results
+of over two years of hard and dedicated work by volunteers all over
+the world under the lead of Dave Miller.
+
+
+Important Updates In This Point Release
+***************************************
+
+There are usually many other bug fixes than those listed below,
+but the below fixes are the ones that we thought System Administrators
+would like to specifically know about.
+
+To see a listing of all changes in this release, you can use the
+table available at:
+
+http://www.bugzilla.org/status/changes.html
+
+Version 2.18.1
+--------------
+
++ You can now enter a negative time for "Hours Worked"
+ in the time-tracking area. (Bug 271276)
+
++ The BugMail.pm customization required for Windows (as
+ described in the Bugzilla Guide) now actually works. (Bug 280911)
+
++ Users who were using Bugzilla 2.8 can now successfully upgrade
+ to 2.18.1 (they couldn't upgrade to 2.18). (Bug 283403)
+
++ Dependency mails are now properly sent during a mass-change of bugs.
+ (Bug 178157)
+
+
+Version 2.18.2
+--------------
+
++ You can now create accounts with createaccount.cgi even
+ when the "requirelogin" parameter is turned on. (Bug 294778)
+
++ Bugs that are in disabled groups may not show a padlock
+ on the bug list, or may otherwise behave strangely. You
+ can now fix this using sanitycheck.cgi. (Bug 277454)
+
++ If sendmail dies while you are marking a bug
+ as a duplicate, the duplicates table will no longer become
+ corrupted. (Bug 225042)
+
+
+Requirements
+************
+
+Dependency Requirements
+-----------------------
+
+Minimum software requirements:
+
+ MySQL v3.23.41 (changed from 2.16)
+ Perl v5.6.0 (changed from 2.16) (Non-Windows platforms)
+ ActiveState Perl v5.8.1 (Windows only)
+
+Required Perl modules:
+
+ AppConfig v1.52
+ CGI v2.93 (new since 2.16) (changed from 2.17.7)
+ Data::Dumper (any)
+ Date::Format v2.21 (changed from 2.16)
+ DBI v1.36 (changed from 2.16) (changed from 2.17.7)
+ DBD::mysql v2.1010 (changed from 2.16)
+ File::Spec v0.82
+ File::Temp (any)
+ Template Toolkit v2.08 (changed from 2.16)
+ Text::Wrap v2001.0131
+
+Optional Perl modules:
+
+ Chart::Base v1.0 (changed from 2.16) (changed from 2.17.7)
+ GD v1.20 (changed from 2.16)
+ GD::Graph (any) (new since 2.16)
+ GD::Text::Align (any) (new since 2.16)
+ Net::LDAP (any) (new since 2.16)
+ PatchReader v0.9.4 (new since 2.16) (changed from 2.17.7)
+ XML::Parser (any)
+
+
+What's New?
+***********
+
+Generic Reporting
+-----------------
+
+Bugzilla has a new mechanism for generating reports of the current state of
+the bug database. It has two related parts: a table-based view, and several
+graphical views.
+
+The table-based view allows you to specify an x, y and z (multiple tables of
+data) axis to plot, and then restrict the bugs plotted using the standard
+query form. You can view the resulting data as an HTML or CSV export (e.g.:
+for importing into a spreadsheet).
+
+There are also bar, line and pie charts, which are defined in a very similar
+way. These views may be more appropriate for particular data types, and are
+suitable for saving and then putting into presentations or web pages.
+
+
+Generic Charting
+----------------
+
+Bugzilla has a new mechanism for generating charts (graphs over time) of any
+arbitrary search. This is known as "New Charts." Legacy data from the previous
+charting mechanism ("Old Charts") is migrated into the "New Charts" when you
+upgrade. The Old Charts mechanism remains, but is deprecated and will be
+removed in a future version of Bugzilla.
+
+Individual users can see/create charts as long as they are a member of the
+group specified in the Param 'chartgroup'. Data can be collected for
+personal charts every seven days (or a longer period, as set by the user).
+Charts created by an administrator can be made public (visible to all). Data
+is collected for administrator charts every day (or a longer period, as set
+by the admin).
+
+The data is collected by the collectstats.pl script, which an administrator
+will need to arrange to be run once every day (see the manual). Chart data can
+be plotted in a number of different ways, and different data sets can be
+plotted on the same graph for comparison.
+
+Please see the Known Bugs section for some important limitations relating to
+access controls on charts.
+
+
+Request System
+---------------
+
+The Request System (RS) is a set of enhancements that adds powerful flag
+(superset of the old attachment status) features to the bugs.
+
+RS allows for four states: off, granted, denied, and (optionally) requested,
+where "granted" is the equivalent of "on". These additions mean it is no
+longer necessary to define a status to negate another status (e.g.
+"needs-work" to negate "has-review") because negation is built into each
+status via the status' "denied" state. Bug statuses: Previously only
+attachments could have these kinds of statuses. RS enables them for bugs as
+well. This feature can be used to request and grant/deny certain properties
+for a bug, such as inclusion for a specific milestone or approval for checkin.
+This way, Bugzilla supports the natural decision-making process in your
+organization.
+
+- Requests: Flags can now optionally be made requestable, which means users
+ can ask other users to set them. When a user requests a flag, Bugzilla
+ emails the requestee and adds the request to a browsable queue so both the
+ requester and the requestee can keep track of its status. Once the
+ requestee fulfills the request by setting the flag to either granted or
+ denied, Bugzilla emails the requestee and removes the request from the
+ queue. This feature supports workflow like the mozilla.org code review
+ and milestone approval processes, whereby code is peer reviewed before
+ being committed and patches get approved by product release managers for
+ inclusion in specific product releases.
+
+- Product/component specificity: Previously flags were product-specific, and
+ if you wanted the same flag for multiple products you had to define
+ multiple flags with the same name. Flags are now
+ product/component-specific, and a single flag can be enabled or disabled
+ for multiple product/component combinations via inclusions and exclusions
+ lists. Flags are enabled for all combinations on their inclusions list
+ except those that appear on their exclusions list.
+
+
+Enterprise Group Support
+------------------------
+
+Bugzilla is no longer limited to 55 access control groups. Administrators can
+define an arbitrary number of access groups composed of individual users or
+other groups. The groups can be configured via the web interface to achieve a
+wide variety of access control policies. See the documentation section on
+'Groups And Group Controls' for details.
+
+
+User Wildcard Matching
+----------------------
+
+Sites can now enable the use of wildcards and substrings in bug entry and
+editing forms. If the user enters an incomplete username, he'll get a list of
+users that matched the given username.
+
+
+Support for "Insiders"
+----------------------
+
+If the 'insidergroup' parameter is defined, a specific group of users can be
+designated insiders who can designate comments and attachments as private to
+other insiders. These comments and attachments will be invisible to other
+users who are not members of the insiders group even if the bugs to which they
+apply are visible. Other insiders will see the comments and attachments with a
+visual tinting indicating that they are private.
+
+
+Time Tracking
+-------------
+
+Controls for tracking time spent fixing bugs are included in the bug form for
+members of the group specified by the 'timetrackinggroup' parameter. Any time
+comments are added to the bug, members of the time tracking group can add an
+amount of time they spent, and it's figured into the total and displayed at
+the top of the bug. Shown in the bug are your original estimate, the amount of
+time spent so far, the revised estimate of how much time is remaining, and
+your gain/loss on the original estimate.
+
+
+Authentication module/LDAP improvements
+---------------------------------------
+
+Bugzilla's authentication mechanisms have been modularized, making pluggable
+authentication schemes for Bugzilla a reality. Both the existing database and
+LDAP systems were ported as part of modularization process. Additionally, the
+CGI portion of the backend was redesigned to allow for authentication from
+other sources, including (theoretically) email, which will help Bug 94850.
+
+As part of this conversion, LDAP logins now use Perl's standard Net::LDAP
+module, which has no external library dependencies.
+
+
+Improved localization support
+-----------------------------
+
+Bugzilla administrators can now configure which languages are supported by
+their installations and automatically serve correct, localized content to
+users based on the HTTP 'Accept-Language' header sent from users' browsers.
+
+There are currently localized templates available for: Arabic, Belarusian,
+Chinese, French, German, Italian, Korean, Portuguese (Brazil) Spanish (Spain
+or Mexico) and Russian. These localized template packs are third-party
+contributions, may only be available for specific versions, and may not be
+supported in the future. (http://www.bugzilla.org/download/#localizations)
+
+
+Patch Viewer
+------------
+
+Viewing and reviewing patches in Bugzilla is often difficult due to lack of
+context, improper format and the inherent readability issues that raw patches
+present. Patch Viewer is an enhancement to Bugzilla designed to fix that by
+offering increased context, linking to sections, and integrating with Bonsai,
+LXR and CVS.
+
+
+Comment Reply Links
+-------------------
+
+In Edit Bug, each bug comment now includes a convenient (reply) link that
+quotes the comment text into the textarea. This feature is only enabled in
+Javascript-capable browsers, but causes no inconvenience to other user agents.
+
+
+Full-Text Search
+----------------
+
+It is now possible to query the Bugzilla database using full-text searching,
+which spans comments and summaries, and which searches for substrings and stem
+variations of the search term. Basically, it's like using Google.
+
+
+Email Address Munging
+---------------------
+
+The fact that raw email addresses are displayed in Bugzilla makes it trivial
+for bots that spamharvest to spider through Bugzilla, in particular, through
+Bugzilla's buglists. This change adds HTML obfuscation of email addresses as
+they appear in the Bugzilla web pages.
+
+
+Google-like Bug Search
+----------------------
+
+Bugzilla now includes a very simple, Google-like "Find a Specific Bug" page,
+in addition to its advanced search page.
+
+
+Miscellaneous Improvements
+--------------------------
+
+- The "Assigned To" field on the new bug page is now prefilled with the default
+ component owner.
+
+- A bug alias column is now available in the buglist page.
+
+- Lists of bugs containing errors in the sanity check page now have a "view as
+ buglist" link in addition to the individual bug links.
+
+- Autolinkification Page - It's now possible to apply Bugzilla's comment
+ hyperlinking algorithm to any text you like. This should be useful for status
+ updates and other web pages which give lists of bugs. The bug links created
+ include the subject, status and resolution of the bug as a tooltip.
+
+- There are more <link> tags on the links toolbar for navigating quickly between
+ different areas.
+
+- Buglists are now available as comma-separated value files (CSV) and JavaScript
+ (JS) as well as HTML and RDF.
+
+- Keywords and dependencies can now be entered during initial bug entry.
+
+- A CSS id signature unique to each Bugzilla installation is now added to the
+ <body> tag on Bugzilla pages to allow custom end-user CSS to explicitly affect
+ Bugzilla.
+
+- Perl's path has been changed to a normal /usr/bin/perl from the original
+ legacy "bonsaitools" path specifier.
+
+- A new "always-require-login" parameter allows administrators to require a
+ login before being able to view any page, except the front page.
+
+- A developer may add an attachment, and also reassign a bug to himself as part
+ of that single action.
+
+- Bugzilla is now able to use the replication facilities provided by the
+ MySQL database to handle updates from the main database to the secondaries.
+
+- Mail handling is now between 125% to 175% faster.
+
+- Guided Bug Entry: You can see a sample enter_bug.cgi template at
+ enter_bug.cgi?format=guided that "guides" users through the process of
+ filing a "good" bug. It needs to be modified before use in your organization.
+
+- There is now a "Give me some help" link on the Advanced Search page that will
+ enable pop-up help for every field on the page.
+
+- The Bugzilla administrator can now forbid users from marking bugs RESOLVED
+ when there are unresolved dependencies.
+
+
+All Changes
+-----------
+
+To see a list of EVERY bug that was fixed between 2.16 and 2.18 (over 1000),
+see: http://tinyurl.com/6m3e4
+
+
+What's Changed?
+***************
+
+
+Flag names
+----------
+
+Prerelease versions of Bugzilla 2.17 and 2.18 inadvertantly allowed
+commas and spaces in the names of flags, which due to the way they're
+processed, caused lots of internal havoc if you named flags to have
+any commas or spaces in them. Having commas or spaces in the names
+can cause errors in the notification emails and in the bug activity
+log. The ability to create new flags with these characters has been
+removed. If you have any existing flags that you named that way,
+running checksetup will attempt to automatically rename them by
+replacing commas and spaces with underscores.
+
+
+New Saved Search User Interface
+-------------------------------
+
+In previous Bugzilla versions, you could specify on the search page that you
+wanted to save a search and store it as a link in your footer. This option has
+now moved to the search results page (buglist.cgi), where you will see a
+"Remember search" button with a box next to it to enter the name of the search.
+
+You can manage your saved searches on the Preferences page.
+
+
+Rules for changing fields
+-------------------------
+
+There have been some changes to the rules governing who can change which fields
+of a bug report. The rules for Bugzilla version 2.16 and 2.18, along with
+differences between them, are listed below. Bear in mind that there are other
+restrictions on bug manipulation besides the ones listed below. In particular,
+the groups system enforces restrictions on who can create, edit, or even see
+any given bug.
+
+Bugzilla 2.16 rules:
+
+- anyone can make a null change;
+- anyone can add a comment;
+- anyone in the editbugs group can make any change;
+- the reporter can make any change to the status;
+- anyone in the canconfirm group can change the status
+ to any opened state (NEW, REOPENED, ASSIGNED).
+- anyone can change the status to any opened state
+ if the everconfirmed flag is set;
+- the owner, QA contact, or reporter can make any change
+ *except* changing the status to an opened state;
+- No other changes are permitted.
+
+[Note that these rules combine to allow the reporter to make any change
+to the bug.]
+
+Bugzilla 2.18 rules:
+
+- anyone can make a null change;
+- anyone can add a comment;
+- anyone in the editbugs group can make any change;
+- anyone in the canconfirm group can change the status
+ from UNCONFIRMED to any opened state;
+- the owner or QA contact can make any change;
+- the reporter can make any change *except*:
+ - changing the status from UNCONFIRMED to any opened state; or
+ - changing the target milestone; or
+ - changing the priority (unless the letsubmitterchoosepriority
+ parameter is set).
+- No other changes are permitted.
+
+The effective differences in the rules:
+
+- In 2.16, the reporter could always change anything about a bug.
+
+ In 2.18, the reporter can't:
+
+ - confirm the bug unless he is in the canconfirm group;
+ - change the target milestone;
+ - change the priority (unless the 'letsubmitterchoosepriority'
+ parameter is set;
+
+ (unless he is also the owner, the QA contact, or in the editbugs
+ group, in which case he can do all these things).
+
+- In 2.16, the owner or QA contact (if the 'useqacontact' parameter
+ is set) can't change the bug status to an opened status unless they
+ are also the reporter, or have editbugs or canconfirm, or the
+ everconfirmed flag is set on the bug).
+
+ In 2.18 the owner or QA contact can make any change to a bug.
+
+- In 2.16, a member of the canconfirm group can set the status
+ to any opened status.
+
+ In 2.18 this is only possible if the status was previously
+ the unconfirmed status.
+
+- In 2.16, the status can be set to anything by anybody
+ if the 'everconfirmed' flag is set.
+
+ In 2.18, this authorization code does not pay any attention
+ to the 'everconfirmed' flag.
+
+
+Removed Features
+****************
+
+- Please note that Bugzilla no longer supports MySQL 3.22. The minimum required
+ version is now 3.23.41.
+
+- The "shadow database" mechanism is no longer used. Instead, use MySQL's
+ built-in replication feature.
+
+- If you have placed any comments in the localconfig file, they may be removed
+ by checksetup.pl.
+
+
+Code Changes Which May Affect Customizations
+********************************************
+
+- A mechanism (called "Template Hooks") for third party extensions to plug into
+ existing templates without having to patch or replace distributed templates
+ has been added. More information on this can be found in the documentation.
+
+- Header output now uses CGI.pm, in a step towards enabling mod_perl
+ compatibility. This change will affect users that had customized charsets in
+ their CGI files: previously the charset had to be added everywhere that
+ printed the Content-Type header; now it only needs changing in one spot, in
+ Bugzilla/CGI.pm.
+
+- $::FORM{} and $::COOKIE{} are deprecated. Use the $cgi methods to access
+ them.
+
+- $::userid is gone in favor of Bugzilla->user->id
+
+- ConnectToDatabase() is gone (it's done automatically when you initialize the
+ Bugzilla object)
+
+- quietly_check_login() and confirm_login() are gone, use Bugzilla->login()
+ with parameters for whether the login is required or not.
+
+- Use Bugzilla->user->login in place of $::COOKIE{Bugzilla_login}
+
+- You can tell if there's a user logged in or not by using
+ Bugzilla->user rather than looking for $::userid==0.
+ In new 2.18 code, use defined(Bugzilla->user) && (Bugzilla->user->id)
+ In 2.20, this will become just (Bugzilla->user->id)
+ In templates, always test [% IF user.id %] rather than [% IF user %]
+
+- SendSQL() and related calls are deprecated, and the various $dbh methods
+ should be used instead, such as $dbh->prepare() and $dbh->execute().
+ Bugzilla->dbh is the $dbh handle to use.
+
+
+Recommended Practice for the Upgrade
+************************************
+
+Note About Upgrading From MySQL With ISAM Tables
+------------------------------------------------
+As previously noted in the Dependency Requirements MySQL is now required
+to be at least version 3.23.41. This implies that all tables of type ISAM will
+be converted by the checksetup.pl script to MyISAM.
+
+
+Steps for Upgrading
+-------------------
+
+1) View the Sanity Check (sanitycheck.cgi) page on your installation before
+ upgrading.
+
+2) As with any upgrade it is recommended that you make a backup of the
+ Bugzilla database before you upgrade, perhaps by using mysqldump.
+
+ Example:
+
+ mysqldump -u root -p --databases bugs > bugs.db.backup
+
+3) Replace the files in your installation, or you can try to use CVS to upgrade.
+ The Bugzilla.org website has instructions on how to do the actual
+ installation.
+
+4) Make sure that you run checksetup.pl after you install the new version.
+
+5) View the Sanity Check page again after you run checksetup.pl.
+
+6) It is recommended that, if possible, you fix any problems you find
+ immediately. Failure to do this may mean that Bugzilla will not work
+ correctly. Be aware that if the sanity check page contains more errors after
+ an upgrade, it doesn't necessarily mean there are more errors in your
+ database, as additional tests are added to the sanity check over time, and
+ it is possible that those errors weren't being checked for in the old
+ version.
+
+
+Outstanding Issues
+******************
+
+These are known problems with the release that we think you should know about.
+They each have a bug number for http://bugzilla.mozilla.org/
+
+- If at any time you upgraded from a version of Bugzilla between 2.17.4 -
+ 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in
+ order for them to work. See the following link for instructions on how to do
+ this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18
+ If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer,
+ then you don't need to do this.
+
+- bug 37765: If you use an MTA other than sendmail (such as Postfix, Exim,
+ etc.) you MUST turn on the "sendmailnow" parameter or Bugzilla will not send
+ e-mail correctly.
+
+- bug 276230: The support for restricting access to particular Categories of
+ New Charts is not complete. You should treat the 'chartgroup' Param as the
+ only access mechanism available. However, additionally, charts migrated from
+ Old Charts will be restricted to the groups that are marked MANDATORY for
+ the corresponding Product. There is currently no way to change this
+ restriction, and the groupings will not be updated if the group configuration
+ for the Product changes.
+
+- bug 69621: If you rename or remove a keyword that is in use on bugs, you will
+ need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing
+ the option to rebuild the cache when it asks. Otherwise keywords may not show
+ up properly in search results.
+
+- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for
+ example, if you use a translation of Bugzilla), don't enable the XS::Stash
+ option when you install the Template Toolkit, or your Bugzilla installation
+ may become slow. This problem is fixed in a not-yet-released version of the
+ Template Toolkit (after 2.14).
+
+- bug 266579: Users may be able to circumvent not having "canconfirm" privileges
+ in some circumstances. This is fixed starting with 2.19.3, but will not
+ be fixed in any 2.18 release, as the changes required to fix it are quite
+ large.
+
+- bug 99215: Attachment changes have no mid-air collision detection, unlike bug
+ changes.
+
+- bug 57350: Searching using the "commenter is" option may be VERY slow. Note
+ that searching for "field: comment, changed by: user@domain.com" is fast,
+ though.
+
+- bug 151509: Using the boolean chart option "contains the string" with the
+ "flag name" field or certain other fields will cause Bugzilla to emit an
+ error. This is fixed in 2.20rc1, but will not be fixed in the 2.18 series.
+
+- bug 234159: Bugzilla may sometimes send multiple notices in one email.
+
+- bug 237107: If you search for attachment information using the Boolean Charts
+ at the bottom of the Advanced Query page, bugs without attachments will not
+ show up in the result list.
+
+
+Security Fixes In 2.18 Releases
+*******************************
+
+Version 2.18
+------------
+
+Summary: XSS in Internal Error messages in Bugzilla 2.16.7 and 2.18rc3
+CVE Name: CAN-2004-1061
+Reference: https://bugzilla.mozilla.org/show_bug.cgi?id=272620
+Details:
+ It is possible to send a carefully crafted URL to Bugzilla designed to
+trigger an error message. The Internal Error message includes javascript code
+which displays the URL the user is visiting. The javascript code does not
+escape the URL before displaying it, allowing scripts contained in the URL to
+be executed by the browser. Many browsers do not allow unescaped URLs to be
+sent to a webserver (thus complying with RFC 2616 section 2.3.1 and RFC 2396
+section 2.4.3), and are thus immune to this issue.
+ Browsers which are known to be immune: Firefox 1.0, Mozilla 1.7.5,
+Camino 0.8.2, Netscape 7.2, Safari 1.2.4
+ Browsers known to be susceptible: Internet Explorer 6 SP2,
+Konqueror 3.2
+ Browsers not listed here have not been tested.
+
+
+Version 2.18.1
+--------------
+
+Two security issues were fixed in Bugzilla 2.18.1, neither of them
+critical.
+
+See http://www.bugzilla.org/security/2.16.8/ for details.
+
+
+Version 2.18.2
+--------------
+
+Two security issues were fixed in Bugzilla 2.18.2. One of them
+is a major Information Leak/Unauthorized Bug Change. The other
+is a minor Information Leak.
+
+See http://www.bugzilla.org/security/2.18.1/ for details.
+
+
+Detailed Version-To-Version Release Notes
+*****************************************
+
+*********************************************************
+*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.7 ***
+*********************************************************
+
+*** Security fixes ***
+
+- It is possible to send a carefully crafted HTTP POST message to
+ process_bug.cgi which will remove keywords from a bug even if you don't have
+ permissions to edit all bug fields (the "editbugs" permission). Such changes
+ are reported in "bug changed" email notifications, so they are easily
+ detected and reversed if someone abuses it. Users are now prevented from
+ making changes to keywords if they do not have editbugs privileges. (bug
+ 252638)
+
+*** Bug fixes of note ***
+
+- Enforce a minimum of 10 minutes between attempts to reset a password, so
+ we don't mailbomb the user if someone submits the form many times in a
+ row. (bug 250897)
+
+- Put products in alphabetical order on the create attachment status page.
+ (bug 251427)
+
+- Specify MyISAM as the table type when creating new tables. MySQL 4.1 and
+ up default to InnoDB, which doesn't support some of the indexing methods
+ that we use. (bug 263165)
+
+*********************************************************
+*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.6 ***
+*********************************************************
+
+*** Security fixes ***
+
+- If Bugzilla is configured to hide entire products from some users, both
+ duplicates.cgi and the form for mass-editing a list of bugs in buglist.cgi
+ can disclose the names of those hidden products to such users.
+ (bugs 234825 and 234855)
+
+- Several administration CGIs echo invalid data back to the user without
+ escaping it. (bug 235265)
+
+- A user with privileges to grant membership to any group (i.e. usually an
+ administrator) can trick editusers.cgi into executing arbitrary SQL.
+ (bug 244272)
+
+*** Bug fixes of note ***
+
+- Allow XML import to function when there are regexp metacharacters in product
+ names (bug 237591)
+
+- Allow the bug_email.pl contrib script to work with useqacontact (bug 239912)
+
+- Improve the error message used by checksetup.pl when the MySQL requirements
+ are not met (bug 240228)
+
+- Elimnate the warning in checksetup.pl about the minimum sendmail version (bug
+ 240060)
+
+- $webservergroup now defaults to group 'apache' in new installations (bug
+ 224477)
+
+- Correct a situation where a bugmail message could be sent twice to a user
+ being added to the CC list if the address was entered in a different case
+ than the user registered with. (bug 117297)
+
+- Various documentation updates
+
+*********************************************************
+*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.4 ***
+*********************************************************
+
+*** Bug fixes of note ***
+
+- Fix a "used only once" warning that ocurred only in perl 5.00503
+ (bug 2321691)
+
+- When a user is creating a new account and enters an invalid email
+ address, the error page sent the "Content-type" header twice, causing
+ the second one to be visible at the top of the page.
+ (bug 137121)
+
+- An HTML encoding issue which only affected Internet Explorer was
+ corrected in the "Change several bugs at once" page.
+ (bug 181106)
+
+- During initial setup, using invalid characters in the administrator
+ password would present an error message stating your password was
+ too long or too short instead of telling you it had invalid
+ characters.
+ (bug 166755)
+
+- When a user reset their own password via an emailed token, the new
+ password in the first field would be accepted if the second password
+ field was left blank.
+ (bug 123077)
+
+- Reopening bugs from the "change several bugs at once" page now works.
+ (bug 95430)
+
+- Fix a regression in xml.cgi caused by the previous bugfix for MySQL
+ SUM() changes. The original fix didn't work properly either.
+ (bug 225474)
+
+- No longer use server push with the "Safari" browser, which claims to
+ use the Mozilla layout engine but doesn't.
+ (bug 188712)
+
+- Creating a shadow database no longer fails with taint mode errors.
+ (bug 227510)
+
+- If you change your cookiepath setting at some stage (because you have
+ moved the directory Bugzilla resides on your webserver), users can
+ have login cookies with the old cookiepath, and their browsers will
+ send multiple logincookies. Bugzilla now uses the first rather than
+ the last in order to get the most specific cookie which will be the
+ correct one.
+ (bug 121419)
+
+- Fixed a regression caused by the previous DBD::mysql fixes, that
+ caused older versions of DBD::mysql to break due to not supporting
+ the new DBI syntax.
+ (bug 224815)
+
+- Bugzilla no longer sends out invalid dates for cookie expiry. This
+ bug had no known user visible ramifications.
+ (bug 228706)
+
+- Update the shadow database parameters description to tell the user
+ about permissions requirements for creating a shadow database.
+ (bug 227513)
+
+- Various documentation updates.
+
+*********************************************************
+*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.3 ***
+*********************************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- A user with 'editproducts' privileges (i.e. usually an administrator)
+ can select arbitrary SQL to be run by the nightly statistics cron job
+ (collectstats.pl), by giving a product a special name.
+ (bug 214290)
+
+- A user with 'editkeywords' privileges (i.e. usually an administrator)
+ can inject arbitrary SQL via the URL used to edit an existing keyword.
+ (bug 219044)
+
+- When deleting products and the 'usebuggroups' parameter is on, the
+ privilege which allows someone to add people to the group which is
+ being deleted does not get removed, allowing people with that
+ privilege to get that privilege for the next group that is created
+ which reuses that group ID. Note that this only allows someone who
+ had been granted privileges in the past to retain them.
+ (bug 219690)
+
+- If you know the email address of someone who has voted on a secure
+ bug, you can access the summary of that bug even if you do not have
+ sufficient permissions to view the bug itself.
+ (bug 209376)
+
+*** Bug fixes of note ***
+
+Perl 5.8.0 Compatibility fixes:
+
+- Two taint errors were fixed, one in process_bug.cgi, and
+ another in post_bug.cgi.
+ (bugs 220332 and 177828)
+
+MySQL 4.0 Compatibility fixes:
+
+- A cosmetic fix was applied to votes.cgi (if there were no
+ votes, the "0" was not displayed) due to a change in semantics
+ in SUM() in MySQL 4.0.
+ (bug 217422)
+
+DBD::mysql > 2.1026 Compatibility fixes:
+
+- DBD::mysql versions after 2.1026 return the table list quoted, which
+ broke the existing "table exists" check in checksetup.pl, which caused
+ the second and subsequent attempts to run checksetup.pl to fail.
+ (bug 212095)
+
+Miscellaneous bug fixes:
+
+- A Mozilla-specific reference was removed from one of the report
+ templates.
+ (bug 221626)
+
+- It was possible to enter a situation where you were unable to get to
+ editparams.cgi to turn the shutdownhtml param back off after you
+ turned it on when Apache was configured to run Bugzilla in suexec
+ mode.
+ (bug 213384)
+
+- The processmail rescanall task would not send e-mails about more than
+ one bug to the same address.
+ (bug 219508)
+
+- If Bugzilla hadn't been accessed in the last hour when the
+ collectstats.pl or whineatnews.pl cron jobs ran, the versioncache
+ would get recreated with the file owner being the user the cron job
+ was running as (usually not the webserver user), causing subsequent
+ access to Bugzilla by the webserver to fail until the permissions were
+ fixed. Now if versioncache isn't readable when accessing from the
+ webserver, we pretend it doesn't exist and recreate it again.
+ (bug 160422)
+
+- The 'sendmailnow' param is now on by default in new installations
+ (this does not affect existing installations).
+ (bug 146087)
+
+- The 008filter.t test would fail if you had multiple language packs
+ installed. It now properly tests all of the installed language packs.
+ (bug 203318)
+
+- A few minor documentation changes were committed.
+
+*********************************************************
+*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.2 ***
+*********************************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- A cross site scripting (XSS) vulnerability was fixed in which bug
+ summaries were not properly filtered when a user viewed a dependency graph
+ allowing JavaScript to be embedded on that page.
+ (bug 192661)
+
+- Several XSS vulnerabilities were fixed in which user
+ input was not escaped when being displayed. A new
+ test has been added to warn about unfiltered data in template
+ files (t/008filter.t).
+ (bug 192677)
+
+- An issue was fixed in which the QA contact was still treated as the QA
+ contact even after the 'useqacontact' setting was turned off. This also
+ allowed the QA contact to edit the security groups and view secured bugs that
+ he/she was allowed to access prior to the 'useqacontact' setting being
+ deactivated.
+ (bug 194394)
+
+- Fixed a situation where an attacker (with local access to the webserver)
+ could overwrite any file on the webserver to which the webserver user
+ has write access by creating appropriately named symbolic links in the
+ data and webdot directories (world-writable in many configurations).
+ Bugzilla now uses File::Temp to create secure temporary files. File::Temp
+ is part of the Perl distribution for Perl 5.6.1 and later, but if you're
+ using an older version of Perl you'll need to install it with CPAN.
+ (bug 197153)
+
+** IMPORTANT CHANGES ***
+
+- New module requirement: File::Temp, as mentioned above.
+
+*** Bug fixes of note ***
+
+- An issue was fixed in which administrator rights could be removed from an
+ administrator who deleted a product while the 'usebuggroups' setting is
+ activated.
+ (bug 157704)
+
+- Fixed an issue in which importxml.pl would fail the test suite when running
+ under perl 5.8.0 with the optional XML::Parse module.
+ (bug 172331)
+
+- There was previously a bug in CGI.pl in which the following warning
+ would be given under certain conditions:
+ "Character in "c" format wrapped at CGI.pl..."
+ This is now fixed. In some cases the warning was filling up web server log
+ files.
+ (bug 194125)
+
+- Fixed a bug in which long component names (in excess of 50 characters) would
+ be accepted when creating the component but would cause problems when trying
+ to use that component on a bug because it would get truncated. It is now no
+ longer possible to create components with names in excess of 50 characters.
+ (bug 197180)
+
+- Fixed a bug in checksetup.pl in which permissions were not being fixed
+ on the 'data/comments' file, the quip file.
+ (bug 160279)
+
+*****************************************************************
+*** USERS UPGRADING FROM 2.16.1 OR EARLIER, 2.14.4 OR EARLIER ***
+*****************************************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- Fixed a cross site scriptability issue in quips. This is only a problem
+ if quips with HTML could have been inserted into your quips files. Bugzilla
+ has not allowed this since 2.12.
+ (bug 179329)
+- checksetup.pl will now attempt to prevent access to "editor backups" of
+ localconfig.
+ (bug 186383)
+- collectstats.pl no longer makes data/mining (which contains graphing
+ information) world writeable.
+ (bug 183188)
+
+***********************************************
+*** USERS UPGRADING FROM 2.16.0 OR EARLIER ***
+***********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- Apostrophes were not properly handled in email addresses. This was a
+ regression introduced in 2.16. It is not known whether this was
+ exploitable.
+ (bug 165221)
+
+See also next major section.
+
+*** Bug fixes of note ***
+
+- The VERSION cookie which allowed the previously entered version of a product
+ to be remembered was not correctly set. It was only set as a session
+ cookie, and under some circumstances could interfere with other cookies
+ (such as the login information) send at the same time.
+ (bug 160227)
+
+- importxml.pl would fail if the versioncache needed to be updated.
+ (bug 164464)
+
+- Bug changes going through intermediate pages would munge fields with
+ multiple fields, such as CCs.
+ (bug 161203)
+
+- On failure in template->new, Bugzilla will now die rather than futilely
+ attempt to use an error template.
+ (bug 166023)
+
+- Fixed a problem where checksetup had problems converting old installations
+ that didn't have a duplicates table.
+ (bug 151619)
+
+- Fixed a problem that caused taint errors when viewing or editing user
+ preferences with Perl 5.005 and Template 2.08.
+ (bug 160710)
+
+See also next section.
+
+******************************************************
+*** USERS UPGRADING FROM 2.16.0, 2.14.3 OR EARLIER ***
+******************************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- When a new product is added to an installation with 47 groups or more and
+ "usebuggroups" is enabled, the new group will be assigned a groupset bit
+ using Perl math that is not exact beyond 2^48. This results in the new
+ group being defined with a "bit" that has several bits set. As users are
+ given access to the new group, those users will also gain access to
+ spurious lower group privileges. Also, group bits were not always reused
+ when groups were deleted.
+ (bug 167485)
+
+- The email interface had another insecure single parameter system call. This
+ could potentially allow arbitrary shell commands to be run. This file is
+ not supported at this time, but as long as we knew about the problem, we
+ couldn't overlook it.
+ (bug 163024)
+
+*** Bug fixes of note ***
+
+- The email interface was broken. This was a 2.14.3 regression. This file
+ is not supported at this time, but as long as we knew about the problem, we
+ couldn't overlook it.
+ (bug 160631)
+
+***********************************************
+*** USERS UPGRADING FROM 2.14.5 OR EARLIER ***
+***********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- The bug reporter could set the priority even when
+ 'letsubmitterchoosepriority' was off.
+ (bug 63018)
+
+- Most CGIs are now templatized. This helps to make it
+ easier to remember to HTML filter values and easier to spot
+ when they are not, preventing cross site scripting attacks.
+ (bug 86168)
+
+- Most CGIs now run in taint mode. This helps to prevent
+ failure to validate errors.
+ (bug 108982)
+
+*** IMPORTANT CHANGES ***
+
+- 2.16 introduces "templatization", a new feature that allows
+ administrators to easily customize the HTML output (the "look and feel")
+ of Bugzilla without altering Perl code. Bugzilla uses the
+ "Template Toolkit" for this. Please see the "Template Customization"
+ section of the Bugzilla Guide for more details.
+
+ Administrators who ran the 2.15 development version with custom
+ templates should check the templates are still valid, as file names
+ and file paths have changed.
+
+ Most output is now templatized. This process will be complete next
+ milestone.
+
+ For speed, compiled templates are cached on disk. If you modify the
+ templates, the toolkit will normally detect the changes, and recompile the
+ changed templates.
+
+ Adding new directories anywhere inside the template directory may cause
+ permission errors if you don't have a webservergroup specified in
+ localconfig. If you see these, rerun checksetup.pl as root. If you do not
+ have root access, or cannot get someone who does to do this for you, you can
+ rename the data/template directory to data/template.old (or any other name
+ Bugzilla doesn't use). Then rerun checksetup.pl to regenerate the compiled
+ templates.
+ (bug 86168, 97832)
+
+- Administrators can now configure maximum attachment sizes. These
+ should remain below the maximum size for your MySQL server, or you
+ will get obscure MySQL errors if you attach a bigger attachment.
+
+ To find out the current size attachment that MySQL can accept, type
+ the command 'mysqladmin variables' and find out the value of the
+ 'max_allowed_packet' varible in bytes.
+
+ To change the maximum size that MySQL can accept you can alter this
+ variable in your 'my.cnf' file.
+ (bug 91664)
+
+- Perl 5.004 is no longer supported because the Template Toolkit
+ requires 5.005.
+ (bug 97721)
+
+- New module requirements: Text::Wrap, Template [requires AppConfig],
+ File::Spec.
+ (bugs 97784, 84338, 103778)
+
+- The index page is now a CGI instead of an HTML page. You should remove
+ any existing index.html file and make sure your web server allows index.cgi
+ to be the default page in a directory. If you are not able to do that you
+ can instead set index_html in the 'localconfig' file to 1 and checksetup.pl
+ will create a redirect page for you.
+ (bug 80183)
+
+- It is now recommended that administrators run "processmail rescanall"
+ after upgrading to 2.16 or beyond.
+
+ This will send out notification emails for changes that were
+ made but not emailed, due to Bugzilla bugs. All known
+ causes of this have been fixed in this version (bug 104589 and 99519).
+
+ It is also recommended that this be run nightly to avoid
+ lengthy delays in future if this problem reoccurs.
+ (bug 106377)
+
+- In parallel with templatization, a lot of changes have been made to the HTML
+ output of the Bugzilla CGIs. This could break code that attempts to parse
+ such code. For example, this breaks mozbot.
+ (no bug number)
+
+- The "HTML template" parameters (headerhtml, bodyhtml, footerhtml,
+ errorhtml, bannerhtml, blurbhtml, mostfreqhtml, entryheaderhtml) have now
+ been moved to Template Toolkit templates. If you have modified these
+ parameters you will need to make corresponding changes to the corresponding
+ templates. Your old parameter values will be moved to a file called
+ old-params.txt by checksetup.pl.
+
+ The old parameters correspond to files in template/en/default as follows:
+
+ headerhtml: global/header.html.tmpl
+ footerhtml: global/footer.html.tmpl
+ bannerhtml: global/banner.html.tmpl
+ blurbhtml: global/banner.html.tmpl
+ mostfreqhtml: reports/duplicates*.html.tmpl
+ entryheaderhtml: bug/create/user-message.html.tmpl
+
+ (bug 140437)
+
+*** Other changes of note ***
+
+- The query page has been redesigned for better user friendliness.
+ (bug 98707)
+- Users can now change their email account.
+ (bug 23067)
+- "Dependent Bug Changed" notification emails now contain the
+ dependent bug's summary and URL.
+ (bug 28736, 113383)
+- Bugs with severity "critical", "blocker", and "enhancement" are
+ visually differentiated on bug lists for browsers with sufficient
+ CSS support.
+ (bug 28884)
+- Bugzilla now has a sidebar for the Mozilla browser.
+ (bug 37339)
+- A link to just created attachments now appears in notification
+ email.
+ (bug 66651)
+- Comments now have numbers and can be referenced with
+ autohyperlinkifying similar to bugs.
+ (bug 71840)
+- The attachment system has been rewritten, supporting new
+ "attachment statuses" (like keywords, but for attachments),
+ the ability to obsolete attachments, edit attachment MIME type,
+ and edit whether the attachment is a patch.
+ (bugs 84338, 75176)
+- syncshadowdb now supports a configurable temp file location,
+ and properly shuts down Bugzilla while running.
+ (bug 75840)
+- Dependency tree now lets you exclude resolved bugs and bugs
+ below a specified depth.
+ (bugs 83058)
+- The "strictvaluechecks" parameter has gone away. These checks
+ are now always done.
+ (bug 119715)
+- The midair collision page now shows all changes since the bug
+ page was loaded, not just the last one.
+ (bug 108312)
+- Added support for making dependency graphs with 'dot', which
+ is better at creating complex graphs than 'webdot'.
+ (bug 120537)
+
+*** Bug fixes of note ***
+
+- Bugzilla scripts are now usually not terminated when the browser
+ window they are running in is closed. This caused hard to
+ reproduce bugs.
+ (bug 104589)
+- On browsers that "reflow" the page, large component / milestone /
+ version fields were extremely slow to reflow when you altered
+ the product field.
+ (bug 96534)
+- The selection in the component / milestone / version fields is
+ no longer lost when you change the selection in the product
+ field or use the back/forward buttons in your browser to return
+ to the page.
+ (bug 97966)
+- You could not reverse dependencies in one step.
+ (bug 82143)
+- Mass reassignment of non-open bugs will no longer reopen them.
+ (bug 30731)
+- Attempting to bulk change no bugs will now give a user-friendly
+ error message.
+ (bug 90333)
+- If you make a change to a bug where you only add yourself to CC,
+ email notifications are now properly sent out for MySQL 3.23.
+ (bug 99519)
+- Bug entry now properly validates the data it has been sent.
+ (bug 107743)
+- Midair collision checks will now properly work in all situations
+ where dependencies have changed.
+ (bug 73502)
+- Browsers can no longer corrupt the params file if they use the "wrong"
+ end-of-line markers.
+ (bug 92500)
+- The MySQL port defined in localconfig is now properly honoured.
+ (bug 98368)
+- Apostrophes in component/milestone/version names no longer cause
+ a problem on the query page.
+ (bug 30689/42810)
+- File attachment comments will now wrap.
+ (bug 52060)
+- Saved queries are no longer mangled if you need to log in again,
+ for example if you had cookies off.
+ (bug 38835)
+- Bug counts (on reports.cgi) were very slow if you had to
+ count a lot of bugs.
+ (bug 63249)
+- 2.14 introduced options to let people see a bug when their name
+ is on it but who aren't in the groups the bug is restricted
+ to. These only allowed the people to view the bugs directly,
+ and not see them on buglists and receive email about them.
+ (bugs 95024, 97469)
+- A new 'cookiepath' parameter on editparams.cgi allows multiple
+ Bugzilla installations to exist on one host without problems.
+ (bug 19910)
+- whineatnews.pl now respects the 'sendmailnow' parameter.
+ (bug 52782)
+- The query page came up even when Bugzilla was shut down.
+ (bug 121747)
+- Quicksearch gave a weird error message when Bugzilla was
+ shut down.
+ (bug 121741)
+- Operating system detection fixes.
+ (bugs 92763, 135666)
+- QA contacts now receive emails when a new bug is created and
+ their only email preference was being added or removed from QA.
+ (bug 143091)
+
+***********************************************
+*** USERS UPGRADING FROM 2.14.4 OR EARLIER ***
+***********************************************
+
+See section above about users upgrading from 2.16.1 or earlier,
+2.14.4 or earlier.
+
+***********************************************
+*** USERS UPGRADING FROM 2.14.3 OR EARLIER ***
+***********************************************
+
+See section above about users upgrading from 2.16.0 or earlier.
+
+***********************************************
+*** USERS UPGRADING FROM 2.14.2 OR EARLIER ***
+***********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- Basic maintenance on contrib/bug_email.pl and
+ contrib/bugzilla_email_append.pl which also fixes a
+ possible security hole with a misuse of a system() call.
+ These files are not supported at this time, but as long
+ as we knew about the problem, we couldn't overlook it.
+ (bug 154008)
+
+*** Bug fixes of note ***
+
+- The fix for bug 130821 in 2.14.2 broke being able to sort
+ bug lists on more than one field. buglist.cgi now allows
+ you to sort on more than one field again.
+ (bug 152138)
+
+***********************************************
+*** USERS UPGRADING FROM 2.14.1 OR EARLIER ***
+***********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- queryhelp.cgi no longer shows confidential products to
+ people it shouldn't.
+ (bug 126801)
+
+- It was possible for a user to bypass the IP check by
+ setting up a fake reverse DNS, if the Bugzilla web server
+ was configured to do reverse DNS lookups. Apache is not
+ configured as such by default. This is not a complete
+ exploit, as the user's login cookie would also need to
+ be divulged for this to be a problem.
+ (bug 129466)
+
+- In some situations the data directory became world writeable.
+ (bug 134575)
+
+- Any user with access to editusers.cgi could delete a user
+ regardless of whether 'allowuserdeletion' is on.
+ (bug 141557)
+
+- Real names were not HTML filtered, causing possible cross
+ site scripting attacks.
+ (bug 146447, 147486)
+
+- Mass change would set the groupset of every bug to be the
+ groupset of the first bug.
+ (bug 107718)
+
+- Some browsers (eg NetPositive) interacted with Bugzilla
+ badly and could have various form problems, including
+ removing group restrictions on bugs.
+ (bug 148674)
+
+- It was possible for random confidential information to be
+ divulged, if the shadow database was in use and became
+ corrupted.
+ (bug 92263)
+
+- The bug list sort order is now stricter about the SQL it will accept,
+ ensuring you use correct column name syntax. Before this, there were
+ some syntax checks, so it is not known whether this problem was
+ exploitable.
+ (bug 130821)
+
+********************************************
+*** USERS UPGRADING FROM 2.14 OR EARLIER ***
+********************************************
+
+The 2.14.1 release fixes several security issues that became
+known to us after the Bugzilla 2.14 release.
+
+*** SECURITY ISSUES RESOLVED ***
+
+- If LDAP Authentication was being used, Bugzilla would allow
+ you to log in as anyone if you left the password blank.
+ (bug 54901)
+
+- It was possible to add comments or file a bug as someone else
+ by editing the HTML on the appropriate submission page before
+ submitting the form. User identity is checked now, and the
+ form values suggesting the user are now ignored.
+ (bug 108385, 108516)
+
+- The Product popup menu on the show_bug form listed all
+ products, even if the user didn't have access to all of them.
+ It now only shows products the user has access to (and the
+ product the bug is in, if the user is viewing it because of
+ some other override).
+ (bug 102141)
+
+- If a user had any blessgroupset privileges (the ability to
+ change only specific privileges for other users), it was
+ possible to change your own groupset (privileges) by
+ altering the page HTML before submitting on editusers.cgi.
+ (bug 108821)
+
+- An untrusted variable was echoed back to user in the HTML
+ output if there was a login error while editing votes.
+ (bug 98146)
+
+- buglist.cgi had an undocumented parameter that allowed you
+ to pass arbitrary SQL for the "WHERE" part of a query.
+ This has been disabled.
+ (bug 108812)
+
+- It was possible for a user to send arbitrary SQL by inserting
+ single quotes in the "mybugslink" field in the user
+ preferences.
+ (bug 108822)
+
+- buglist.cgi was not validating that the field names being
+ passed from the "boolean chart" query form were valid field
+ names, thus allowing arbitrary SQL to be inserted if you
+ edited the HTML by hand before submitting the form.
+ (bug 109679)
+
+- long_list.cgi was not validating that the bug ID parameter
+ was actually a number, allowing arbitrary SQL to be inserted
+ if you edited the HTML by hand.
+ (bug 109690)
+
+********************************************
+*** USERS UPGRADING FROM 2.12 OR EARLIER ***
+********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- Multiple instances of unauthorized access to confidential
+ bugs have been fixed.
+ (bug 39524, 39526, 39527, 39531, 39533, 70189, 82781)
+
+- Multiple instances of untrusted parameters not being
+ checked/escaped was fixed. These included definite security
+ holes.
+ (bug 38854, 38855, 38859, 39536, 87701, 95235)
+
+- After logging in passwords no longer appear in the URL.
+ (bug 15980)
+
+- Procedures to prevent unauthorized access to confidential
+ files are now simpler. In particular the shadow directory
+ no longer exists and the data/comments file no longer needs
+ to be directly accessible, so the entire data directory can
+ be blocked. However, no changes are required here if you
+ have a properly secured 2.12 installation as no new files
+ must be protected.
+ (bug 71552, 73191)
+
+- If they do not already exist, checksetup.pl will attempt to
+ write Apache .htaccess files by default, to prevent
+ unauthorized access to confidential files. You can turn this
+ off in the localconfig file.
+ (bug 76154)
+
+- Sanity check can now only be run by people in the 'editbugs'
+ group. Although it would be better to have a separate
+ group, this is not possible until the limitation on the
+ number of groups allowed has been removed.
+ (bug 54556)
+
+- The password is no longer stored in plaintext form. It will
+ be eradicated next time you run checksetup.pl. A user must
+ now change their password via a password change request that
+ gets validated at their e-mail account, rather than have it
+ mailed to them.
+ (bug 74032)
+
+- When you are using product groups and you move a bug between
+ products (single or mass change), the bug will no longer be
+ restricted to the old product's group (if it was) and will
+ be restricted to the new product's group.
+ (bug 66235)
+
+- There are now options on a bug to choose whether the
+ reporter, and CCs can access a bug even if they aren't in
+ groups the bug it is restricted to.
+ (bug 39816)
+
+- You can no longer mark a bug as a duplicate of a bug you
+ can't see, and if you mark a bug a duplicate of a bug
+ the reporter cannot see you will be given options as to
+ what to do regarding adding the reporter of the resolved
+ bug to the CC of the open bug.
+ (bug 96085)
+
+*** IMPORTANT CHANGES ***
+
+- Bugzilla 2.14 no longer supports old email tech. Upon
+ upgrading, all users will be moved over to new email tech.
+ This should speed up upgrading for installations with
+ a large number of bugs.
+ (bug 71552)
+
+- There is new functionality for people to see why they are
+ receiving notification mails.
+
+ Previously, some people filtered old email tech
+ notifications depending on whether they were in the To or the
+ CC header, in order to get a limited way of determining why
+ they were receiving the notification for filtering purposes.
+
+ Existing installations will need to make changes to support
+ this feature. The receive reasons can be added to the
+ notifications as a header and/or in the body. To add these
+ you will need to modify your newchangedmail parameter on
+ editparams.cgi, either by resetting it or appropriately
+ modifying it. The header value is specified by
+ %reasonsheader% and the body by %reasonsbody%. For example,
+ the new default parameter is:
+
+ --------------------------------------------------
+ From: bugzilla-daemon
+ To: %to%
+ Subject: [Bug %bugid%] %neworchanged%%summary%
+ X-Bugzilla-Reason: %reasonsheader%
+
+ %urlbase%show_bug.cgi?id=%bugid%
+
+ %diffs%
+
+
+
+ %reasonsbody%
+ --------------------------------------------------
+
+ (bug 26194)
+
+- Very long fields (especially multi-valued fields like keywords,
+ CCs, dependencies) on bug activity and notifications previously
+ could get truncated, resulting in useless notifications and data
+ loss on bug activity. Now the multi-valued fields only show
+ changes, and very big changes are split into multiple lines.
+ Where data loss has already occurred on bug activity, it is
+ indicated using question marks.
+ (bug 55161, 92266)
+
+- Previously, when a product's voting preferences changed all
+ votes were removed from all the bugs in the product. Also,
+ when a bug was moved to another product, all of its votes
+ were removed. This no longer occurs.
+
+ Instead, if the action would leave one or more bugs with
+ greater than the maximum number of votes per person per bug,
+ the number of votes will be reduced to the maximum. The
+ person will still be notified of this as before.
+
+ If the action would leave a user with more votes in a product
+ than is allowed, the limit will be breached so as to not lose
+ votes. However the user will not be able to update their
+ votes except to fix this situation. No further action is taken
+ in this version to make sure that the user does this.
+ (bug 28882, 92593)
+
+*** Other changes of note ***
+
+- Groups can now be marked inactive, so you can't add a new
+ restriction on that group to a bug, while leaving bugs that
+ were previously restricted on that group alone.
+ (bug 75482)
+- backdoor.cgi has been removed from the installation. It was
+ old code that was Netscape-specific and its name was scaring
+ people.
+ (bug 87983)
+- You can now add or remove from CC on the bulk change page.
+ (bug 12819)
+- New users created by administrators are now automatically
+ inserted into groups according to the group's regular
+ expression. Administrators must edit the user in a second
+ step to override these choices. Previously the
+ administrator specified these explicitly which could lead
+ to incorrect settings.
+ (bug 45164)
+- The userregexp of system groups can now be edited without
+ resorting to direct database access.
+ (bug 65290)
+
+*** Bug fixes of note ***
+
+- The bug list page was sometimes bringing up a not logged in
+ footer when the user was logged in and the installation was
+ using a shadow database.
+ (bug 47914)
+- You can now view the bug summary in your browser title for
+ a group-restricted bug if you have proper permissions.
+ (bug 71767)
+- Quick search for search terms did not work in IE5.
+ This has been worked around.
+ (bug 77699)
+- Quick search for search terms crashed NN4.76/4.77 for Unix.
+ This has been worked around.
+ (bug 83619)
+- Queries on bugs you have commented on using the "added
+ comment" feature should be a lot faster and not time out
+ on large installations due to the addition of an index.
+ (bug 57350)
+- You can now alter group settings on bulk change for groups
+ that aren't on for all bugs or off for all bugs.
+ (bug 84714)
+- New bug notifications now include the CC and QA fields.
+ (bug 28458)
+- Bugzilla is now more Windows friendly, although it is still
+ not an official platform.
+ (bug 88179, 29064)
+- Passwords are now encrypted using Perl's encrypt function.
+ This makes Bugzilla more portable to more operating systems.
+ (bug 77473)
+- Bugzilla didn't properly shut down when told to - some
+ queries could still be sent to the database.
+ (bug 95082)
+
+********************************************
+*** USERS UPGRADING FROM 2.10 OR EARLIER ***
+********************************************
+
+*** SECURITY ISSUES RESOLVED ***
+
+- Some security holes have been fixed where shell escape characters
+ could be passed to Bugzilla, allowing remote users to execute
+ system commands on the web server.
+
+*** IMPORTANT CHANGES ***
+
+- There is now a facility for users to choose the sort of
+ notifications they wish to receive. This facility will
+ probably be improved in future versions.
+ (bug 17464)
+
+- "Changed" will no longer appear on the subject line of
+ change notification emails. Because of this, you should
+ change the subject line in your 'changedmail' and
+ 'newchangedmail' params on editparams.cgi. The subject
+ line needs to be changed from
+
+ Subject: [Bug %bugid%] %neworchanged% - %summary%
+
+ to:
+
+ Subject: [Bug %bugid%] %neworchanged%%summary%
+
+ or whatever is appropriate for the subject you are using
+ on your system. Note the removal of the " - " in the
+ middle.
+ (bug 29820)
+
+*** Other changes of note ***
+
+- Bug titles now appear in the page title, and will hence
+ display in the user's browser's bookmarks and history.
+ (bug 22041)
+- Edit groups functionality (editgroups.cgi).
+ (bug 25010)
+- Support for moving bugs to other Bugzilla databases.
+ (bug 36133)
+- Bugzilla now can generate a frequently reported bugs list
+ based on what duplicates you receive.
+ (bug 25693)
+- When installing Bugzilla fresh, the administrator account is
+ now created in checksetup.pl.
+ (bug 17773)
+- Stored queries now show their name above the bug list, which
+ helps the user when they have multiple bug lists in multiple
+ browser windows. It also appears in the page title, and will
+ hence display in the user's browser's bookmarks and history.
+ (bug 52228)
+- All states and resolutions can now be collected for charting.
+ (bug 6682)
+- A new search-engine-like "quick search" feature appears on
+ the front page to try and making searching easier.
+ (bug 69793)
+- Querying on dependencies now works in the advanced query
+ section of the query page.
+ (bug 30823)
+- When a bug is marked as a duplicate, the reporter of the
+ resolved bug is automatically added to the CC list of the
+ open bug.
+ (bug 28676)
+
+*** Bug fixes of note ***
+
+- Notification emails will now always be sent to QA contacts.
+ Previously they wouldn't if you were using new email tech.
+ (bug 30826)
+- When marking a bug as a duplicate, the duplicate stamp marked
+ on the open bug will no longer be written too early (such as
+ on mid-air collisions).
+ (bug 7873)
+- Various bug fixes were made to the initial assignee and QA
+ of a component. It is no longer possible to enter an
+ invalid address. They will also now properly update when
+ a user's email address is changed. Sanity check will now
+ check these.
+ (bug 66876)
+- Administrators can no longer create an email accounts that do
+ not match the global email regular expression parameter.
+ Previously this could occur and would cause sanity check
+ errors.
+ (bug 32971)
+- The resolution field can no longer become empty when the
+ bug is resolved. This occurred because of midair collisions.
+ (bug 49306)
+
+*******************************************
+*** USERS UPGRADING FROM 2.8 OR EARLIER ***
+*******************************************
+
+Release notes were not compiled for versions of Bugzilla before
+2.12.
+
+The file 'UPGRADING-pre-2.8' contains instructions you may
+need to perform in addition to running 'checksetup.pl' if you
+are running a pre 2.8 version.
+
--- /dev/null
+bugzilla.ent
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+ <!ENTITY % myents SYSTEM "bugzilla.ent">
+ %myents;
+
+<!-- Include macros -->
+<!ENTITY about SYSTEM "about.xml">
+<!ENTITY conventions SYSTEM "conventions.xml">
+<!ENTITY doc-index SYSTEM "index.xml">
+<!ENTITY gfdl SYSTEM "gfdl.xml">
+<!ENTITY glossary SYSTEM "glossary.xml">
+<!ENTITY installation SYSTEM "installation.xml">
+<!ENTITY administration SYSTEM "administration.xml">
+<!ENTITY security SYSTEM "security.xml">
+<!ENTITY using SYSTEM "using.xml">
+<!ENTITY integration SYSTEM "integration.xml">
+<!ENTITY index SYSTEM "index.xml">
+<!ENTITY customization SYSTEM "customization.xml">
+<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
+<!ENTITY patches SYSTEM "patches.xml">
+<!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY modules SYSTEM "modules.xml">
+
+<!-- Things to change for a stable release:
+ * bz-ver to current stable
+ * bz-nexver to next stable
+ * bz-date to the release date
+ * landfillbase to the branch install
+ * Remove the BZ-DEVEL comments
+ - COMPILE DOCS AND CHECKIN -
+ Also, tag and tarball before completing
+ * bz-ver to devel version
+
+ For a devel release, simple bump bz-ver and bz-date
+-->
+
+<!ENTITY bz-ver "3.1.3">
+<!ENTITY bz-nextver "3.2">
+<!ENTITY bz-date "2008-02-01">
+<!ENTITY current-year "2008">
+
+<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/">
+<!ENTITY bz "http://www.bugzilla.org/">
+<!ENTITY bzg-bugs "<ulink url='https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation'>Bugzilla Documentation</ulink>">
+<!ENTITY mysql "http://www.mysql.com/">
+
+<!ENTITY min-perl-ver "5.8.1">
+]>
+
+
+<!-- Coding standards for this document
+
+* Other than the GFDL, please use the "section" tag instead of "sect1",
+ "sect2", etc.
+* Use Entities to include files for new chapters in Bugzilla-Guide.xml.
+* Try to use Entities for frequently-used passages of text as well.
+* Ensure all documents compile cleanly to HTML after modification.
+ The warning, "DTDDECL catalog types not supported" is normal.
+* Try to index important terms wherever possible.
+* Use "glossterm" whenever you introduce a new term.
+* Follow coding standards at http://www.tldp.org, and
+ check out the KDE guidelines (they are nice, too)
+ http://i18n.kde.org/doc/markup.html
+* All tags should be lowercase.
+* Please use sensible spacing. The comments at the very end of each
+ file define reasonable defaults for PSGML mode in EMACS.
+* Double-indent tags, use double spacing whenever possible, and
+ try to avoid clutter and feel free to waste space in the code to make it
+ more readable.
+
+-->
+
+<book id="index">
+
+<!-- Header -->
+
+ <bookinfo>
+ <title>The Bugzilla Guide - &bz-ver;
+ <!-- BZ-DEVEL -->Development <!-- /BZ-DEVEL -->
+ Release</title>
+
+ <authorgroup>
+ <corpauthor>The Bugzilla Team</corpauthor>
+ </authorgroup>
+
+ <pubdate>&bz-date;</pubdate>
+
+ <abstract>
+ <para>
+ This is the documentation for Bugzilla, a
+ bug-tracking system from mozilla.org.
+ Bugzilla is an enterprise-class piece of software
+ that tracks millions of bugs and issues for hundreds of
+ organizations around the world.
+ </para>
+
+ <para>
+ The most current version of this document can always be found on the
+ <ulink url="http://www.bugzilla.org/docs/">Bugzilla
+ Documentation Page</ulink>.
+ </para>
+
+ </abstract>
+
+ <keywordset>
+ <keyword>Bugzilla</keyword>
+ <keyword>Guide</keyword>
+ <keyword>installation</keyword>
+ <keyword>FAQ</keyword>
+ <keyword>administration</keyword>
+ <keyword>integration</keyword>
+ <keyword>MySQL</keyword>
+ <keyword>Mozilla</keyword>
+ <keyword>webtools</keyword>
+ </keywordset>
+ </bookinfo>
+
+<!-- About This Guide -->
+&about;
+
+<!-- Installing Bugzilla -->
+&installation;
+
+<!-- Administering Bugzilla -->
+&administration;
+
+<!-- Securing Bugzilla -->
+&security;
+
+<!-- Using Bugzilla -->
+&using;
+
+<!-- Customizing Bugzilla -->
+&customization;
+
+<!-- Appendix: Troubleshooting -->
+&troubleshooting;
+
+<!-- Appendix: Custom Patches -->
+&patches;
+
+<!-- Appendix: Manually Installing Perl Modules -->
+&modules;
+
+<!-- Appendix: GNU Free Documentation License -->
+&gfdl;
+
+<!-- Glossary -->
+&glossary;
+
+<!-- Index -->
+&index;
+
+
+</book>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!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-¤t-year; by the various
+ Bugzilla contributors who wrote it.</para>
+
+ <blockquote>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation
+ License, Version 1.1 or any later version published by the
+ Free Software Foundation; with no Invariant Sections, no
+ Front-Cover Texts, and with no Back-Cover Texts. A copy of
+ the license is included in <xref linkend="gfdl"/>.
+ </para>
+ </blockquote>
+ <para>
+ If you have any questions regarding this document, its
+ copyright, or publishing this document in non-electronic form,
+ please contact the Bugzilla Team.
+ </para>
+ </section>
+
+ <section id="disclaimer">
+ <title>Disclaimer</title>
+ <para>
+ No liability for the contents of this document can be accepted.
+ Follow the instructions herein at your own risk.
+ This document may contain errors
+ and inaccuracies that may damage your system, cause your partner
+ to leave you, your boss to fire you, your cats to
+ pee on your furniture and clothing, and global thermonuclear
+ war. Proceed with caution.
+ </para>
+ <para>
+ Naming of particular products or brands should not be seen as
+ endorsements, with the exception of the term "GNU/Linux". We
+ wholeheartedly endorse the use of GNU/Linux; it is an extremely
+ versatile, stable,
+ and robust operating system that offers an ideal operating
+ environment for Bugzilla.
+ </para>
+ <para>
+ Although the Bugzilla development team has taken great care to
+ ensure that all exploitable bugs have been fixed, security holes surely
+ exist in any piece of code. Great care should be taken both in
+ the installation and usage of this software. The Bugzilla development
+ team members assume no liability for your use of Bugzilla. You have
+ the source code, and are responsible for auditing it yourself to ensure
+ your security needs are met.
+ </para>
+ </section>
+
+<!-- Section 2: New Versions -->
+
+ <section id="newversions">
+ <title>New Versions</title>
+ <para>
+ This is the &bz-ver; version of The Bugzilla Guide. It is so named
+ to match the current version of Bugzilla.
+ <!-- BZ-DEVEL --> This version of the guide, like its associated Bugzilla version, is a
+ development version.<!-- /BZ-DEVEL -->
+ </para>
+ <para>
+ The latest version of this guide can always be found at <ulink
+ url="http://www.bugzilla.org"/>, or checked out via CVS by
+ following the <ulink url="http://www.mozilla.org/cvs.html">Mozilla
+ CVS</ulink> instructions and check out the
+ <filename>mozilla/webtools/bugzilla/docs/</filename>
+ subtree. However, you should read the version
+ which came with the Bugzilla release you are using.
+ </para>
+ <para>
+ The Bugzilla Guide, or a section of it, is also available in
+ the following languages:
+ <ulink url="http://www.traduc.org/docs/guides/lecture/bugzilla/">French</ulink>,
+ <ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>,
+ <ulink url="http://www.bugzilla.jp/docs/2.18/">Japanese</ulink>.
+ Note that these may be outdated or not up to date.
+ </para>
+
+ <para>
+ In addition, there are Bugzilla template localization projects in
+ the following languages. They may have translated documentation
+ available:
+ <ulink url="http://sourceforge.net/projects/bugzilla-ar/">Arabic</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-be/">Belarusian</ulink>,
+ <ulink url="http://openfmi.net/projects/mozilla-bg/">Bulgarian</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-br/">Brazilian Portuguese</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-cn/">Chinese</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-fr/">French</ulink>,
+ <ulink url="http://germzilla.ganderbay.net/">German</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-it/">Italian</ulink>,
+ <ulink url="http://www.bugzilla.jp/about/jp.html">Japanese</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-kr/">Korean</ulink>,
+ <ulink url="http://sourceforge.net/projects/bugzilla-ru/">Russian</ulink> and
+ <ulink url="http://sourceforge.net/projects/bugzilla-es/">Spanish</ulink>.
+ </para>
+
+ <para>
+ If you would like to volunteer to translate the Guide into additional
+ languages, please contact
+ <ulink url="mailto:justdave@bugzilla.org">Dave Miller</ulink>.
+ </para>
+ </section>
+
+ <section id="credits">
+ <title>Credits</title>
+ <para>
+ The people listed below have made enormous contributions to the
+ creation of this Guide, through their writing, dedicated hacking efforts,
+ numerous e-mail and IRC support sessions, and overall excellent
+ contribution to the Bugzilla community:
+ </para>
+
+ <!-- TODO: This is evil... there has to be a valid way to get this look -->
+ <variablelist>
+ <varlistentry>
+ <term>Matthew P. Barnson <email>mbarnson@sisna.com</email></term>
+ <listitem>
+ <para>for the Herculean task of pulling together the Bugzilla Guide
+ and shepherding it to 2.14.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Terry Weissman <email>terry@mozilla.org</email></term>
+ <listitem>
+ <para>for initially writing Bugzilla and creating the README upon
+ which the UNIX installation documentation is largely based.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Tara Hernandez <email>tara@tequilarists.org</email></term>
+ <listitem>
+ <para>for keeping Bugzilla development going strong after Terry left
+ mozilla.org and for running landfill.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Dave Lawrence <email>dkl@redhat.com</email></term>
+ <listitem>
+ <para>for providing insight into the key differences between Red
+ Hat's customized Bugzilla.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Dawn Endico <email>endico@mozilla.org</email></term>
+ <listitem>
+ <para>for being a hacker extraordinaire and putting up with Matthew's
+ incessant questions and arguments on irc.mozilla.org in #mozwebtools
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Jacob Steenhagen <email>jake@bugzilla.org</email></term>
+ <listitem>
+ <para>for taking over documentation during the 2.17 development
+ period.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Dave Miller <email>justdave@bugzilla.org</email></term>
+ <listitem>
+ <para>for taking over as project lead when Tara stepped down and
+ continually pushing for the documentation to be the best it can be.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+
+ <para>
+ Thanks also go to the following people for significant contributions
+ to this documentation:
+ <simplelist type="inline">
+ <member>Kevin Brannen</member>
+ <member>Vlad Dascalu</member>
+ <member>Ben FrantzDale</member>
+ <member>Eric Hanson</member>
+ <member>Zach Lipton</member>
+ <member>Gervase Markham</member>
+ <member>Andrew Pearson</member>
+ <member>Joe Robins</member>
+ <member>Spencer Smith</member>
+ <member>Ron Teitelbaum</member>
+ <member>Shane Travis</member>
+ <member>Martin Wulffeld</member>
+ </simplelist>.
+ </para>
+
+ <para>
+ Also, thanks are due to the members of the
+ <ulink url="news://news.mozilla.org/mozilla.support.bugzilla">
+ mozilla.support.bugzilla</ulink>
+ newsgroup (and its predecessor, netscape.public.mozilla.webtools).
+ Without your discussions, insight, suggestions, and patches,
+ this could never have happened.
+ </para>
+ </section>
+
+ <!-- conventions used here (didn't want to give it a chapter of its own) -->
+&conventions;
+ </chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End: -->
+
--- /dev/null
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<chapter id="administration">
+ <title>Administering Bugzilla</title>
+
+ <section id="parameters">
+ <title>Bugzilla Configuration</title>
+
+ <para>
+ Bugzilla is configured by changing various parameters, accessed
+ from the "Parameters" link in the Administration page (the
+ Administration page can be found by clicking the "Administration"
+ link in the footer). The parameters are divided into several categories,
+ accessed via the menu on the left. Following is a description of the
+ different categories and important parameters within those categories.
+ </para>
+
+ <section id="param-requiredsettings">
+ <title>Required Settings</title>
+
+ <para>
+ The core required parameters for any Bugzilla installation are set
+ here. These parameters must be set before a new Bugzilla installation
+ can be used. Administrators should review this list before
+ deploying a new Bugzilla installation.
+ </para>
+
+ <indexterm>
+ <primary>checklist</primary>
+ </indexterm>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ maintainer
+ </term>
+ <listitem>
+ <para>
+ Email address of the person
+ responsible for maintaining this Bugzilla installation.
+ The address need not be that of a valid Bugzilla account.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ urlbase
+ </term>
+ <listitem>
+ <para>
+ Defines the fully qualified domain name and web
+ server path to this Bugzilla installation.
+ </para>
+ <para>
+ For example, if the Bugzilla query page is
+ <filename>http://www.foo.com/bugzilla/query.cgi</filename>,
+ the <quote>urlbase</quote> should be set
+ to <filename>http://www.foo.com/bugzilla/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ docs_urlbase
+ </term>
+ <listitem>
+ <para>
+ Defines path to the Bugzilla documentation. This can be a fully
+ qualified domain name, or a path relative to "urlbase".
+ </para>
+ <para>
+ For example, if the "Bugzilla Configuration" page
+ of the documentation is
+ <filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>,
+ set the <quote>docs_urlbase</quote>
+ to <filename>http://www.foo.com/bugzilla/docs/html/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ sslbase
+ </term>
+ <listitem>
+ <para>
+ Defines the fully qualified domain name and web
+ server path for HTTPS (SSL) connections to this Bugzilla installation.
+ </para>
+ <para>
+ For example, if the Bugzilla main page is
+ <filename>https://www.foo.com/bugzilla/index.cgi</filename>,
+ the <quote>sslbase</quote> should be set
+ to <filename>https://www.foo.com/bugzilla/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ ssl
+ </term>
+ <listitem>
+ <para>
+ Determines when Bugzilla will force HTTPS (SSL) connections, using
+ the URL defined in <command>sslbase</command>.
+ Options include "always", "never", and "authenticated sessions".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ cookiedomain
+ </term>
+ <listitem>
+ <para>
+ Defines the domain for Bugzilla cookies. This is typically left blank.
+ If there are multiple hostnames that point to the same webserver, which
+ require the same cookie, then this parameter can be utilized. For
+ example, If your website is at
+ <filename>https://www.foo.com/</filename>, setting this to
+ <filename>.foo.com/</filename> will also allow
+ <filename>bar.foo.com/</filename> to access Bugzilla cookies.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ cookiepath
+ </term>
+ <listitem>
+ <para>
+ Defines a path, relative to the web server root, that Bugzilla
+ cookies will be restricted to. For example, if the
+ <command>urlbase</command> is set to
+ <filename>http://www.foo.com/bugzilla/</filename>, the
+ <command>cookiepath</command> should be set to
+ <filename>/bugzilla/</filename>. Setting it to "/" will allow all sites
+ served by this web server or virtual host to read Bugzilla cookies.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ timezone
+ </term>
+ <listitem>
+ <para>
+ Timezone of server. The timezone is displayed with timestamps. If
+ this parameter is left blank, the timezone is not displayed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ utf8
+ </term>
+ <listitem>
+ <para>
+ Determines whether to use UTF-8 (Unicode) encoding for all text in
+ Bugzilla. New installations should set this to true to avoid character
+ encoding problems. Existing databases should set this to true only
+ after the data has been converted from existing legacy character
+ encoding to UTF-8, using the
+ <filename>contrib/recode.pl</filename> script.
+ </para>
+ <note>
+ <para>
+ If you turn this parameter from "off" to "on", you must re-run
+ <filename>checksetup.pl</filename> immediately afterward.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ shutdownhtml
+ </term>
+ <listitem>
+ <para>
+ If there is any text in this field, this Bugzilla installation will
+ be completely disabled and this text will appear instead of all
+ Bugzilla pages for all users, including Admins. Used in the event
+ of site maintenance or outage situations.
+ </para>
+ <note>
+ <para>
+ Although regular log-in capability is disabled while
+ <command>shutdownhtml</command>
+ is enabled, safeguards are in place to protect the unfortunate
+ admin who loses connection to Bugzilla. Should this happen to you,
+ go directly to the <filename>editparams.cgi</filename> (by typing
+ the URL in manually, if necessary). Doing this will prompt you to
+ log in, and your name/password will be accepted here (but nowhere
+ else).
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ announcehtml
+ </term>
+ <listitem>
+ <para>
+ Any text in this field will be displayed at the top of every HTML
+ page in this Bugzilla installation. The text is not wrapped in any
+ tags. For best results, wrap the text in a <quote><div></quote>
+ tag. Any style attributes from the CSS can be applied. For example,
+ to make the text green inside of a red box, add <quote>id=message</quote>
+ to the <quote><div></quote> tag.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ proxy_url
+ </term>
+ <listitem>
+ <para>
+ If this Bugzilla installation is behind a proxy, enter the proxy
+ information here to enable Bugzilla to access the Internet. Bugzilla
+ requires Internet access to utilize the
+ <command>upgrade_notification</command> parameter (below). If the
+ proxy requires authentication, use the syntax:
+ <filename>http://user:pass@proxy_url/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ upgrade_notification
+ </term>
+ <listitem>
+ <para>
+ Enable or disable a notification on the homepage of this Bugzilla
+ installation when a newer version of Bugzilla is available. This
+ notification is only visible to administrators. Choose "disabled",
+ to turn off the notification. Otherwise, choose which version of
+ Bugzilla you want to be notified about: "development_snapshot" is the
+ latest release on the trunk; "latest_stable_release" is the most
+ recent release available on the most recent stable branch;
+ "stable_branch_release" the most recent release on the branch
+ this installation is based on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-admin-policies">
+ <title>Administrative Policies</title>
+ <para>
+ This page contains parameters for basic administrative functions.
+ Options include whether to allow the deletion of bugs and users, whether
+ to allow users to change their email address, and whether to allow
+ user watching (one user receiving all notifications of a selected
+ other user).
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ supportwatchers
+ </term>
+ <listitem>
+ <para>
+ Turning on this option allows users to ask to receive copies
+ of bug mail sent to another user. Watching a user with
+ different group permissions is not a way to 'get around' the
+ system; copied emails are still subject to the normal groupset
+ permissions of a bug, and <quote>watchers</quote> will only be
+ copied on emails from bugs they would normally be allowed to view.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-user-authentication">
+ <title>User Authentication</title>
+ <para>
+ This page contains the settings that control how this Bugzilla
+ installation will do its authentication. Choose what authentication
+ mechanism to use (the Bugzilla database, or an external source such
+ as LDAP), and set basic behavioral parameters. For example, choose
+ whether to require users to login to browse bugs, the management
+ of authentication cookies, and the regular expression used to
+ validate email addresses. Some parameters are highlighted below.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ emailregexp
+ </term>
+ <listitem>
+ <para>
+ Defines the regular expression used to validate email addresses
+ used for login names. The default attempts to match fully
+ qualified email addresses (i.e. 'user@example.com'). Some
+ Bugzilla installations allow only local user names (i.e 'user'
+ instead of 'user@example.com'). In that case, the
+ <command>emailsuffix</command> parameter should be used to define
+ the email domain.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ emailsuffix
+ </term>
+ <listitem>
+ <para>
+ This string is appended to login names when actually sending
+ email to a user. For example,
+ If <command>emailregexp</command> has been set to allow
+ local usernames,
+ then this parameter would contain the email domain for all users
+ (i.e. '@example.com').
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-attachments">
+ <title>Attachments</title>
+ <para>
+ This page allows for setting restrictions and other parameters
+ regarding attachments to bugs. For example, control size limitations
+ and whether to allow pointing to external files via a URI.
+ </para>
+ </section>
+
+ <section id="param-bug-change-policies">
+ <title>Bug Change Policies</title>
+ <para>
+ Set policy on default behavior for bug change events. For example,
+ choose which status to set a bug to when it is marked as a duplicate,
+ and choose whether to allow bug reporters to set the priority or
+ target milestone. Also allows for configuration of what changes
+ should require the user to make a comment, described below.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ commenton*
+ </term>
+ <listitem>
+ <para>
+ All these fields allow you to dictate what changes can pass
+ without comment, and which must have a comment from the
+ person who changed them. Often, administrators will allow
+ users to add themselves to the CC list, accept bugs, or
+ change the Status Whiteboard without adding a comment as to
+ their reasons for the change, yet require that most other
+ changes come with an explanation.
+ </para>
+
+ <para>
+ Set the "commenton" options according to your site policy. It
+ is a wise idea to require comments when users resolve, reassign, or
+ reopen bugs at the very least.
+ </para>
+
+ <note>
+ <para>
+ It is generally far better to require a developer comment
+ when resolving bugs than not. Few things are more annoying to bug
+ database users than having a developer mark a bug "fixed" without
+ any comment as to what the fix was (or even that it was truly
+ fixed!)
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ noresolveonopenblockers
+ </term>
+ <listitem>
+ <para>
+ This option will prevent users from resolving bugs as FIXED if
+ they have unresolved dependencies. Only the FIXED resolution
+ is affected. Users will be still able to resolve bugs to
+ resolutions other than FIXED if they have unresolved dependent
+ bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-bugfields">
+ <title>Bug Fields</title>
+ <para>
+ The parameters in this section determine the default settings of
+ several Bugzilla fields for new bugs, and also control whether
+ certain fields are used. For example, choose whether to use the
+ "target milestone" field or the "status whiteboard" field.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ useqacontact
+ </term>
+ <listitem>
+ <para>
+ This allows you to define an email address for each component,
+ in addition to that of the default assignee, who will be sent
+ carbon copies of incoming bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ usestatuswhiteboard
+ </term>
+ <listitem>
+ <para>
+ This defines whether you wish to have a free-form, overwritable field
+ associated with each bug. The advantage of the Status Whiteboard is
+ that it can be deleted or modified with ease, and provides an
+ easily-searchable field for indexing some bugs that have some trait
+ in common.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-bugmoving">
+ <title>Bug Moving</title>
+ <para>
+ This page controls whether this Bugzilla installation allows certain
+ users to move bugs to an external database. If bug moving is enabled,
+ there are a number of parameters that control bug moving behaviors.
+ For example, choose which users are allowed to move bugs, the location
+ of the external database, and the default product and component that
+ bugs moved <emphasis>from</emphasis> other bug databases to this
+ Bugzilla installation are assigned to.
+ </para>
+
+ </section>
+
+ <section id="param-dependency-graphs">
+ <title>Dependency Graphs</title>
+ <para>
+ This page has one parameter that sets the location of a Web Dot
+ server, or of the Web Dot binary on the local system, that is used
+ to generate dependency graphs. Web Dot is a CGI program that creates
+ images from <filename>.dot</filename> graphic description files. If
+ no Web Dot server or binary is specified, then dependency graphs will
+ be disabled.
+ </para>
+ </section>
+
+ <section id="param-group-security">
+ <title>Group Security</title>
+ <para>
+ Bugzilla allows for the creation of different groups, with the
+ ability to restrict the visibility of bugs in a group to a set of
+ specific users. Specific products can also be associated with
+ groups, and users restricted to only see products in their groups.
+ Several parameters are described in more detail below. Most of the
+ configuration of groups and their relationship to products is done
+ on the "Groups" and "Product" pages of the "Administration" area.
+ The options on this page control global default behavior.
+ For more information on Groups and Group Security, see
+ <xref linkend="groups"/>
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ makeproductgroups
+ </term>
+ <listitem>
+ <para>
+ Determines whether or not to automatically create groups
+ when new products are created. If this is on, the groups will be
+ used for querying bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ useentrygroupdefault
+ </term>
+ <listitem>
+ <para>
+ Bugzilla products can have a group associated with them, so that
+ certain users can only see bugs in certain products. When this
+ parameter is set to <quote>on</quote>, this
+ causes the initial group controls on newly created products
+ to place all newly-created bugs in the group
+ having the same name as the product immediately.
+ After a product is initially created, the group controls
+ can be further adjusted without interference by
+ this mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ usevisibilitygroups
+ </term>
+ <listitem>
+ <para>
+ If selected, user visibility will be restricted to members of
+ groups, as selected in the group configuration settings.
+ Each user-defined group can be allowed to see members of selected
+ other groups.
+ For details on configuring groups (including the visibility
+ restrictions) see <xref linkend="edit-groups"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ querysharegroup
+ </term>
+ <listitem>
+ <para>
+ The name of the group of users who are allowed to share saved
+ searches with one another. For more information on using
+ saved searches, see <xref linkend="savedsearches"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="bzldap">
+ <title>LDAP Authentication</title>
+
+ <para>LDAP authentication is a module for Bugzilla's plugin
+ authentication architecture. This page contains all the parameters
+ necessary to configure Bugzilla for use with LDAP authentication.
+ </para>
+
+ <para>
+ The existing authentication
+ scheme for Bugzilla uses email addresses as the primary user ID, and a
+ password to authenticate that user. All places within Bugzilla that
+ require a user ID (e.g assigning a bug) use the email
+ address. The LDAP authentication builds on top of this scheme, rather
+ than replacing it. The initial log-in is done with a username and
+ password for the LDAP directory. Bugzilla tries to bind to LDAP using
+ those credentials and, if successful, tries to map this account to a
+ Bugzilla account. If an LDAP mail attribute is defined, the value of this
+ attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
+ username to form a full email address. If an account for this address
+ already exists in the Bugzilla installation, it will log in to that account.
+ If no account for that email address exists, one is created at the time
+ of login. (In this case, Bugzilla will attempt to use the "displayName"
+ or "cn" attribute to determine the user's full name.) After
+ authentication, all other user-related tasks are still handled by email
+ address, not LDAP username. For example, bugs are still assigned by
+ email address and users are still queried by email address.
+ </para>
+
+ <caution>
+ <para>Because the Bugzilla account is not created until the first time
+ a user logs in, a user who has not yet logged is unknown to Bugzilla.
+ This means they cannot be used as an assignee or QA contact (default or
+ otherwise), added to any CC list, or any other such operation. One
+ possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
+ script in the
+ <glossterm linkend="gloss-contrib">
+ <filename class="directory">contrib</filename></glossterm>
+ directory. Another possible solution is fixing
+ <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
+ 201069</ulink>.
+ </para>
+ </caution>
+
+ <para>Parameters required to use LDAP Authentication:</para>
+
+ <variablelist>
+ <varlistentry id="param-user_verify_class_for_ldap">
+ <term>user_verify_class</term>
+ <listitem>
+ <para>If you want to list <quote>LDAP</quote> here,
+ make sure to have set up the other parameters listed below.
+ Unless you have other (working) authentication methods listed as
+ well, you may otherwise not be able to log back in to Bugzilla once
+ you log out.
+ If this happens to you, you will need to manually edit
+ <filename>data/params</filename> and set user_verify_class to
+ <quote>DB</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPserver">
+ <term>LDAPserver</term>
+ <listitem>
+ <para>This parameter should be set to the name (and optionally the
+ port) of your LDAP server. If no port is specified, it assumes
+ the default LDAP port of 389.
+ </para>
+ <para>Ex. <quote>ldap.company.com</quote>
+ or <quote>ldap.company.com:3268</quote>
+ </para>
+ <para>You can also specify a LDAP URI, so as to use other
+ protocols, such as LDAPS or LDAPI. If port was not specified in
+ the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
+ schemes respectively.
+ </para>
+ <para>Ex. <quote>ldap://ldap.company.com</quote>,
+ <quote>ldaps://ldap.company.com</quote> or
+ <quote>ldapi://%2fvar%2flib%2fldap_sock</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPbinddn">
+ <term>LDAPbinddn [Optional]</term>
+ <listitem>
+ <para>Some LDAP servers will not allow an anonymous bind to search
+ the directory. If this is the case with your configuration you
+ should set the LDAPbinddn parameter to the user account Bugzilla
+ should use instead of the anonymous bind.
+ </para>
+ <para>Ex. <quote>cn=default,cn=user:password</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPBaseDN">
+ <term>LDAPBaseDN</term>
+ <listitem>
+ <para>The LDAPBaseDN parameter should be set to the location in
+ your LDAP tree that you would like to search for email addresses.
+ Your uids should be unique under the DN specified here.
+ </para>
+ <para>Ex. <quote>ou=People,o=Company</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPuidattribute">
+ <term>LDAPuidattribute</term>
+ <listitem>
+ <para>The LDAPuidattribute parameter should be set to the attribute
+ which contains the unique UID of your users. The value retrieved
+ from this attribute will be used when attempting to bind as the
+ user to confirm their password.
+ </para>
+ <para>Ex. <quote>uid</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPmailattribute">
+ <term>LDAPmailattribute</term>
+ <listitem>
+ <para>The LDAPmailattribute parameter should be the name of the
+ attribute which contains the email address your users will enter
+ into the Bugzilla login boxes.
+ </para>
+ <para>Ex. <quote>mail</quote></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section id="bzradius">
+ <title>RADIUS Authentication</title>
+
+ <para>
+ RADIUS authentication is a module for Bugzilla's plugin
+ authentication architecture. This page contains all the parameters
+ necessary for configuring Bugzilla to use RADIUS authentication.
+ </para>
+ <note>
+ <para>
+ Most caveats that apply to LDAP authentication apply to RADIUS
+ authentication as well. See <xref linkend="bzldap"/> for details.
+ </para>
+ </note>
+
+ <para>Parameters required to use RADIUS Authentication:</para>
+
+ <variablelist>
+ <varlistentry id="param-user_verify_class_for_radius">
+ <term>user_verify_class</term>
+ <listitem>
+ <para>If you want to list <quote>RADIUS</quote> here,
+ make sure to have set up the other parameters listed below.
+ Unless you have other (working) authentication methods listed as
+ well, you may otherwise not be able to log back in to Bugzilla once
+ you log out.
+ If this happens to you, you will need to manually edit
+ <filename>data/params</filename> and set user_verify_class to
+ <quote>DB</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_server">
+ <term>RADIUS_server</term>
+ <listitem>
+ <para>This parameter should be set to the name (and optionally the
+ port) of your RADIUS server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_secret">
+ <term>RADIUS_secret</term>
+ <listitem>
+ <para>This parameter should be set to the RADIUS server's secret.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_email_suffix">
+ <term>RADIUS_email_suffix</term>
+ <listitem>
+ <para>Bugzilla needs an e-mail address for each user account.
+ Therefore, it needs to determine the e-mail address corresponding
+ to a RADIUS user.
+ Bugzilla offers only a simple way to do this: it can concatenate
+ a suffix to the RADIUS user name to convert it into an e-mail
+ address.
+ You can specify this suffix in the RADIUS_email_suffix parameter.
+ </para>
+ <para>If this simple solution does not work for you, you'll
+ probably need to modify
+ <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your
+ requirements.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section id="param-email">
+ <title>Email</title>
+ <para>
+ This page contains all of the parameters for configuring how
+ Bugzilla deals with the email notifications it sends. See below
+ for a summary of important options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ mail_delivery_method
+ </term>
+ <listitem>
+ <para>
+ This is used to specify how email is sent, or if it is sent at
+ all. There are several options included for different MTAs,
+ along with two additional options that disable email sending.
+ "Test" does not send mail, but instead saves it in
+ <filename>data/mailer.testfile</filename> for later review.
+ "None" disables email sending entirely.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ mailfrom
+ </term>
+ <listitem>
+ <para>
+ This is the email address that will appear in the "From" field
+ of all emails sent by this Bugzilla installation. Some email
+ servers require mail to be from a valid email address, therefore
+ it is recommended to choose a valid email address here.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ sendmailnow
+ </term>
+ <listitem>
+ <para>
+ When Bugzilla is using Sendmail older than 8.12, turning this option
+ off will improve performance by not waiting for Sendmail to actually
+ send mail. If Sendmail 8.12 or later is being used, there is
+ nothing to gain by turning this off. If another MTA is being used,
+ such as Postfix, then this option *must* be turned on (even if you
+ are using the fake sendmail executable that Postfix provides).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ whinedays
+ </term>
+ <listitem>
+ <para>
+ Set this to the number of days you want to let bugs go
+ in the NEW or REOPENED state before notifying people they have
+ untouched new bugs. If you do not plan to use this feature, simply
+ do not set up the whining cron job described in the installation
+ instructions, or set this value to "0" (never whine).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ globalwatcher
+ </term>
+ <listitem>
+ <para>
+ This allows you to define specific users who will
+ receive notification each time a new bug in entered, or when
+ an existing bug changes, according to the normal groupset
+ permissions. It may be useful for sending notifications to a
+ mailing-list, for instance.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-patchviewer">
+ <title>Patch Viewer</title>
+ <para>
+ This page contains configuration parameters for the CVS server,
+ Bonsai server and LXR server that Bugzilla will use to enable the
+ features of the Patch Viewer. Bonsai is a tool that enables queries
+ to a CVS tree. LXR is a tool that can cross reference and index source
+ code.
+ </para>
+ </section>
+
+ <section id="param-querydefaults">
+ <title>Query Defaults</title>
+ <para>
+ This page controls the default behavior of Bugzilla in regards to
+ several aspects of querying bugs. Options include what the default
+ query options are, what the "My Bugs" page returns, whether users
+ can freely add bugs to the quip list, and how many duplicate bugs are
+ needed to add a bug to the "most frequently reported" list.
+ </para>
+ </section>
+
+ <section id="param-shadowdatabase">
+ <title>Shadow Database</title>
+ <para>
+ This page controls whether a shadow database is used, and all the
+ parameters associated with the shadow database. Versions of Bugzilla
+ prior to 3.2 used the MyISAM table type, which supports
+ only table-level write locking. With MyISAM, any time someone is making a change to
+ a bug, the entire table is locked until the write operation is complete.
+ Locking for write also blocks reads until the write is complete.
+ </para>
+ <para>
+ The <quote>shadowdb</quote> parameter was designed to get around
+ this limitation. While only a single user is allowed to write to
+ a table at a time, reads can continue unimpeded on a read-only
+ shadow copy of the database.
+ </para>
+
+ <note>
+ <para>
+ As of version 3.2, Bugzilla no longer uses the MyISAM table type.
+ Instead, InnoDB is used, which can do transaction-based locking.
+ Therefore, the limitations the Shadow Database feature was designed
+ to workaround no longer exist.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="admin-usermatching">
+ <title>User Matching</title>
+ <para>
+ The settings on this page control how users are selected and queried
+ when adding a user to a bug. For example, users need to be selected
+ when choosing who the bug is assigned to, adding to the CC list or
+ selecting a QA contact. With the "usemenuforusers" parameter, it is
+ possible to configure Bugzilla to
+ display a list of users in the fields instead of an empty text field.
+ This should only be used in Bugzilla installations with a small number
+ of users. If users are selected via a text box, this page also
+ contains parameters for how user names can be queried and matched
+ when entered.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="useradmin">
+ <title>User Administration</title>
+
+ <section id="defaultuser">
+ <title>Creating the Default User</title>
+
+ <para>When you first run checksetup.pl after installing Bugzilla, it
+ will prompt you for the administrative username (email address) and
+ password for this "super user". If for some reason you delete
+ the "super user" account, re-running checksetup.pl will again prompt
+ you for this username and password.</para>
+
+ <tip>
+ <para>If you wish to add more administrative users, add them to
+ the "admin" group and, optionally, edit the tweakparams, editusers,
+ creategroups, editcomponents, and editkeywords groups to add the
+ entire admin group to those groups (which is the case by default).
+ </para>
+ </tip>
+ </section>
+
+ <section id="manageusers">
+ <title>Managing Other Users</title>
+
+ <section id="user-account-search">
+ <title>Searching for existing users</title>
+
+ <para>
+ If you have <quote>editusers</quote> privileges or if you are allowed
+ to grant privileges for some groups, the <quote>Users</quote> link
+ will appear in the Administration page.
+ </para>
+
+ <para>
+ The first screen is a search form to search for existing user
+ accounts. You can run searches based either on the user ID, real
+ name or login name (i.e. the email address, or just the first part
+ of the email address if the "emailsuffix" parameter is set).
+ The search can be conducted
+ in different ways using the listbox to the right of the text entry
+ box. You can match by case-insensitive substring (the default),
+ regular expression, a <emphasis>reverse</emphasis> regular expression
+ match (which finds every user name which does NOT match the regular
+ expression), or the exact string if you know exactly who you are
+ looking for. The search can be restricted to users who are in a
+ specific group. By default, the restriction is turned off.
+ </para>
+
+ <para>
+ The search returns a list of
+ users matching your criteria. User properties can be edited by clicking
+ the login name. The Account History of a user can be viewed by clicking
+ the "View" link in the Account History column. The Account History
+ displays changes that have been made to the user account, the time of
+ the change and the user who made the change. For example, the Account
+ History page will display details of when a user was added or removed
+ from a group.
+ </para>
+ </section>
+
+ <section id="createnewusers">
+ <title>Creating new users</title>
+
+ <section id="self-registration">
+ <title>Self-registration</title>
+
+ <para>
+ By default, users can create their own user accounts by clicking the
+ <quote>New Account</quote> link at the bottom of each page (assuming
+ they aren't logged in as someone else already). If you want to disable
+ this self-registration, or if you want to restrict who can create his
+ own user account, you have to edit the <quote>createemailregexp</quote>
+ parameter in the <quote>Configuration</quote> page, see
+ <xref linkend="parameters" />.
+ </para>
+ </section>
+
+ <section id="user-account-creation">
+ <title>Accounts created by an administrator</title>
+
+ <para>
+ Users with <quote>editusers</quote> privileges, such as administrators,
+ can create user accounts for other users:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>After logging in, click the "Users" link at the footer of
+ the query page, and then click "Add a new user".</para>
+ </listitem>
+
+ <listitem>
+ <para>Fill out the form presented. This page is self-explanatory.
+ When done, click "Submit".</para>
+
+ <note>
+ <para>Adding a user this way will <emphasis>not</emphasis>
+ send an email informing them of their username and password.
+ While useful for creating dummy accounts (watchers which
+ shuttle mail to another system, for instance, or email
+ addresses which are a mailing list), in general it is
+ preferable to log out and use the <quote>New Account</quote>
+ button to create users, as it will pre-populate all the
+ required fields and also notify the user of her account name
+ and password.</para>
+ </note>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+
+ <section id="modifyusers">
+ <title>Modifying Users</title>
+
+ <para>Once you have found your user, you can change the following
+ fields:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Login Name</emphasis>:
+ This is generally the user's full email address. However, if you
+ have are using the <quote>emailsuffix</quote> parameter, this may
+ just be the user's login name. Note that users can now change their
+ login names themselves (to any valid email address).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Real Name</emphasis>: The user's real name. Note that
+ Bugzilla does not require this to create an account.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Password</emphasis>:
+ You can change the user's password here. Users can automatically
+ request a new password, so you shouldn't need to do this often.
+ If you want to disable an account, see Disable Text below.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Bugmail Disabled</emphasis>:
+ Mark this checkbox to disable bugmail and whinemail completely
+ for this account. This checkbox replaces the data/nomail file
+ which existed in older versions of Bugzilla.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Disable Text</emphasis>:
+ If you type anything in this box, including just a space, the
+ user is prevented from logging in, or making any changes to
+ bugs via the web interface.
+ The HTML you type in this box is presented to the user when
+ they attempt to perform these actions, and should explain
+ why the account was disabled.
+ </para>
+ <para>
+ Users with disabled accounts will continue to receive
+ mail from Bugzilla; furthermore, they will not be able
+ to log in themselves to change their own preferences and
+ stop it. If you want an account (disabled or active) to
+ stop receiving mail, simply check the
+ <quote>Bugmail Disabled</quote> checkbox above.
+ </para>
+ <note>
+ <para>
+ Even users whose accounts have been disabled can still
+ submit bugs via the e-mail gateway, if one exists.
+ The e-mail gateway should <emphasis>not</emphasis> be
+ enabled for secure installations of Bugzilla.
+ </para>
+ </note>
+ <warning>
+ <para>
+ Don't disable all the administrator accounts!
+ </para>
+ </warning>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis><groupname></emphasis>:
+ If you have created some groups, e.g. "securitysensitive", then
+ checkboxes will appear here to allow you to add users to, or
+ remove them from, these groups.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>canconfirm</emphasis>:
+ This field is only used if you have enabled the "unconfirmed"
+ status. If you enable this for a user,
+ that user can then move bugs from "Unconfirmed" to a "Confirmed"
+ status (e.g.: "New" status).</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>creategroups</emphasis>:
+ This option will allow a user to create and destroy groups in
+ Bugzilla.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>editbugs</emphasis>:
+ Unless a user has this bit set, they can only edit those bugs
+ for which they are the assignee or the reporter. Even if this
+ option is unchecked, users can still add comments to bugs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>editcomponents</emphasis>:
+ This flag allows a user to create new products and components,
+ as well as modify and destroy those that have no bugs associated
+ with them. If a product or component has bugs associated with it,
+ those bugs must be moved to a different product or component
+ before Bugzilla will allow them to be destroyed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>editkeywords</emphasis>:
+ If you use Bugzilla's keyword functionality, enabling this
+ feature allows a user to create and destroy keywords. As always,
+ the keywords for existing bugs containing the keyword the user
+ wishes to destroy must be changed before Bugzilla will allow it
+ to die.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>editusers</emphasis>:
+ This flag allows a user to do what you're doing right now: edit
+ other users. This will allow those with the right to do so to
+ remove administrator privileges from other users or grant them to
+ themselves. Enable with care.</para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ <emphasis>tweakparams</emphasis>:
+ This flag allows a user to change Bugzilla's Params
+ (using <filename>editparams.cgi</filename>.)</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis><productname></emphasis>:
+ This allows an administrator to specify the products
+ in which a user can see bugs. If you turn on the
+ <quote>makeproductgroups</quote> parameter in
+ the Group Security Panel in the Parameters page,
+ then Bugzilla creates one group per product (at the time you create
+ the product), and this group has exactly the same name as the
+ product itself. Note that for products that already exist when
+ the parameter is turned on, the corresponding group will not be
+ created. The user must still have the <quote>editbugs</quote>
+ privilege to edit bugs in these products.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="user-account-deletion">
+ <title>Deleting Users</title>
+ <para>
+ If the <quote>allowuserdeletion</quote> parameter is turned on, see
+ <xref linkend="parameters" />, then you can also delete user accounts.
+ Note that this is most of the time not the best thing to do. If only
+ a warning in a yellow box is displayed, then the deletion is safe.
+ If a warning is also displayed in a red box, then you should NOT try
+ to delete the user account, else you will get referential integrity
+ problems in your database, which can lead to unexpected behavior,
+ such as bugs not appearing in bug lists anymore, or data displaying
+ incorrectly. You have been warned!
+ </para>
+ </section>
+
+ <section id="impersonatingusers">
+ <title>Impersonating Users</title>
+
+ <para>
+ There may be times when an administrator would like to do something as
+ another user. The <command>sudo</command> feature may be used to do
+ this.
+ </para>
+
+ <note>
+ <para>
+ To use the sudo feature, you must be in the
+ <emphasis>bz_sudoers</emphasis> group. By default, all
+ administrators are in this group.</para>
+ </note>
+
+ <para>
+ If you have access to this feature, you may start a session by
+ going to the Edit Users page, Searching for a user and clicking on
+ their login. You should see a link below their login name titled
+ "Impersonate this user". Click on the link. This will take you
+ to a page where you will see a description of the feature and
+ instructions for using it. After reading the text, simply
+ enter the login of the user you would like to impersonate, provide
+ a short message explaining why you are doing this, and press the
+ button.</para>
+
+ <para>
+ As long as you are using this feature, everything you do will be done
+ as if you were logged in as the user you are impersonating.</para>
+
+ <warning>
+ <para>
+ The user you are impersonating will not be told about what you are
+ doing. If you do anything that results in mail being sent, that
+ mail will appear to be from the user you are impersonating. You
+ should be extremely careful while using this feature.</para>
+ </warning>
+ </section>
+ </section>
+ </section>
+
+ <section id="classifications" xreflabel="Classifications">
+ <title>Classifications</title>
+
+ <para>Classifications tend to be used in order to group several related
+ products into one distinct entity.</para>
+
+ <para>The classifications layer is disabled by default; it can be turned
+ on or off using the useclassification parameter,
+ in the <emphasis>Bug Fields</emphasis> section of the edit parameters screen.</para>
+
+ <para>Access to the administration of classifications is controlled using
+ the <emphasis>editclassifications</emphasis> system group, which defines
+ a privilege for creating, destroying, and editing classifications.</para>
+
+ <para>When activated, classifications will introduce an additional
+ step when filling bugs (dedicated to classification selection), and they
+ will also appear in the advanced search form.</para>
+ </section>
+
+ <section id="products" xreflabel="Products">
+ <title>Products</title>
+
+ <para>
+ <glossterm linkend="gloss-product" baseform="product">
+ Products</glossterm> typically represent real-world
+ shipping products. Products can be given
+ <xref linkend="classifications"/>.
+ For example, if a company makes computer games,
+ they could have a classification of "Games", and a separate
+ product for each game. This company might also have a
+ <quote>Common</quote> product for units of technology used
+ in multiple games, and perhaps a few special products that
+ represent items that are not actually shipping products
+ (for example, "Website", or "Administration").
+ </para>
+
+ <para>
+ Many of Bugzilla's settings are configurable on a per-product
+ basis. The number of <quote>votes</quote> available to
+ users is set per-product, as is the number of votes
+ required to move a bug automatically from the UNCONFIRMED
+ status to the NEW status.
+ </para>
+
+ <para>
+ When creating or editing products the following options are
+ available:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ Product
+ </term>
+ <listitem>
+ <para>
+ The name of the product
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Description
+ </term>
+ <listitem>
+ <para>
+ A brief description of the product
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ URL describing milestones for this product
+ </term>
+ <listitem>
+ <para>
+ If there is reference URL, provide it here
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Default milestone
+ </term>
+ <listitem>
+ <para>
+ Select the default milestone for this product.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Closed for bug entry
+ </term>
+ <listitem>
+ <para>
+ Select this box to prevent new bugs from being
+ entered against this product.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Maximum votes per person
+ </term>
+ <listitem>
+ <para>
+ Maximum votes a user is allowed to give for this
+ product
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Maximum votes a person can put on a single bug
+ </term>
+ <listitem>
+ <para>
+ Maximum votes a user is allowed to give for this
+ product in a single bug
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Confirmation threshold
+ </term>
+ <listitem>
+ <para>
+ Number of votes needed to automatically remove any
+ bug against this product from the UNCONFIRMED state
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Version
+ </term>
+ <listitem>
+ <para>
+ Specify which version of the product bugs will be
+ entered against.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Create chart datasets for this product
+ </term>
+ <listitem>
+ <para>
+ Select to make chart datasets available for this product.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ When editing a product there is also a link to edit Group Access Controls,
+ see <xref linkend="product-group-controls"/>.
+ </para>
+
+ <section id="create-product">
+ <title>Creating New Products</title>
+
+ <para>
+ To create a new product:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Select <quote>Administration</quote> from the footer and then
+ choose <quote>Products</quote> from the main administration page.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Select the <quote>Add</quote> link in the bottom right.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Enter the name of the product and a description. The
+ Description field may contain HTML.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When the product is created, Bugzilla will give a message
+ stating that a component must be created before any bugs can
+ be entered against the new product. Follow the link to create
+ a new component. See <xref linkend="components"/> for more
+ information.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ </section>
+
+ <section id="edit-products">
+ <title>Editing Products</title>
+
+ <para>
+ To edit an existing product, click the "Products" link from the
+ "Administration" page. If the 'useclassification' parameter is
+ turned on, a table of existing classifications is displayed,
+ including an "Unclassified" category. The table indicates how many products
+ are in each classification. Click on the classification name to see its
+ products. If the 'useclassification' parameter is not in use, the table
+ lists all products directly. The product table summarizes the information
+ about the product defined
+ when the product was created. Click on the product name to edit these
+ properties, and to access links to other product attributes such as the
+ product's components, versions, milestones, and group access controls.
+ </para>
+
+ </section>
+
+ <section id="comps-vers-miles-products">
+ <title>Adding or Editing Components, Versions and Target Milestones</title>
+ <para>
+ To edit existing, or add new, Components, Versions or Target Milestones
+ to a Product, select the "Edit Components", "Edit Versions" or "Edit
+ Milestones" links from the "Edit Product" page. A table of existing
+ Components, Versions or Milestones is displayed. Click on a item name
+ to edit the properties of that item. Below the table is a link to add
+ a new Component, Version or Milestone.
+ </para>
+ <para>
+ For more information on components, see <xref linkend="components"/>.
+ </para>
+ <para>
+ For more information on versions, see <xref linkend="versions"/>.
+ </para>
+ <para>
+ For more information on milestones, see <xref linkend="milestones"/>.
+ </para>
+ </section>
+
+ <section id="product-group-controls">
+ <title>Assigning Group Controls to Products</title>
+
+ <para>
+ On the <quote>Edit Product</quote> page, there is a link called
+ <quote>Edit Group Access Controls</quote>. The settings on this page
+ control the relationship of the groups to the product being edited.
+ </para>
+
+ <para>
+ Group Access Controls are an important aspect of using groups for
+ isolating products and restricting access to bugs filed against those
+ products. For more information on groups, including how to create, edit
+ add users to, and alter permission of, see <xref linkend="groups"/>.
+ </para>
+
+ <para>
+ After selecting the "Edit Group Access Controls" link from the "Edit
+ Product" page, a table containing all user-defined groups for this
+ Bugzilla installation is displayed. The system groups that are created
+ when Bugzilla is installed are not applicable to Group Access Controls.
+ Below is description of what each of these fields means.
+ </para>
+
+ <para>
+ Groups may be applicable (e.g bugs in this product can be associated
+ with this group) , default (e.g. bugs in this product are in this group
+ by default), and mandatory (e.g. bugs in this product must be associated
+ with this group) for each product. Groups can also control access
+ to bugs for a given product, or be used to make bugs for a product
+ totally read-only unless the group restrictions are met. The best way to
+ understand these relationships is by example. See
+ <xref linkend="group-control-examples"/> for examples of
+ product and group relationships.
+ </para>
+
+ <note>
+ <para>
+ Products and Groups are not limited to a one-to-one relationship.
+ Multiple groups can be associated with the same product, and groups
+ can be associated with more than one product.
+ </para>
+ </note>
+
+ <para>
+ If any group has <emphasis>Entry</emphasis> selected, then the
+ product will restrict bug entry to only those users
+ who are members of <emphasis>all</emphasis> the groups with
+ <emphasis>Entry</emphasis> selected.
+ </para>
+
+ <para>
+ If any group has <emphasis>Canedit</emphasis> selected,
+ then the product will be read-only for any users
+ who are not members of <emphasis>all</emphasis> of the groups with
+ <emphasis>Canedit</emphasis> selected. <emphasis>Only</emphasis> users who
+ are members of all the <emphasis>Canedit</emphasis> groups
+ will be able to edit bugs for this product. This is an additional
+ restriction that enables finer-grained control over products rather
+ than just all-or-nothing access levels.
+ </para>
+
+ <para>
+ The following settings let you
+ choose privileges on a <emphasis>per-product basis</emphasis>.
+ This is a convenient way to give privileges to
+ some users for some products only, without having
+ to give them global privileges which would affect
+ all products.
+ </para>
+
+ <para>
+ Any group having <emphasis>editcomponents</emphasis>
+ selected allows users who are in this group to edit all
+ aspects of this product, including components, milestones
+ and versions.
+ </para>
+
+ <para>
+ Any group having <emphasis>canconfirm</emphasis> selected
+ allows users who are in this group to confirm bugs
+ in this product.
+ </para>
+
+ <para>
+ Any group having <emphasis>editbugs</emphasis> selected allows
+ users who are in this group to edit all fields of
+ bugs in this product.
+ </para>
+
+ <para>
+ The <emphasis>MemberControl</emphasis> and
+ <emphasis>OtherControl</emphasis> are used in tandem to determine which
+ bugs will be placed in this group. The only allowable combinations of
+ these two parameters are listed in a table on the "Edit Group Access Controls"
+ page. Consult this table for details on how these fields can be used.
+ Examples of different uses are described below.
+ </para>
+
+ <section id="group-control-examples">
+ <title>Common Applications of Group Controls</title>
+
+ <para>
+ The use of groups is best explained by providing examples that illustrate
+ configurations for common use cases. The examples follow a common syntax:
+ <emphasis>Group: Entry, MemberControl, OtherControl, CanEdit,
+ EditComponents, CanConfirm, EditBugs</emphasis>. Where "Group" is the name
+ of the group being edited for this product. The other fields all
+ correspond to the table on the "Edit Group Access Controls" page. If any
+ of these options are not listed, it means they are not checked.
+ </para>
+
+ <para>
+ Basic Product/Group Restriction
+ </para>
+
+ <para>
+ Suppose there is a product called "Bar". The
+ "Bar" product can only have bugs entered against it by users in the
+ group "Foo". Additionally, bugs filed against product "Bar" must stay
+ restricted to users to "Foo" at all times. Furthermore, only members
+ of group "Foo" can edit bugs filed against product "Bar", even if other
+ users could see the bug. This arrangement would achieved by the
+ following:
+ </para>
+
+ <programlisting>
+Product Bar:
+foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
+ </programlisting>
+
+ <para>
+ Perhaps such strict restrictions are not needed for product "Bar". A
+ more lenient way to configure product "Bar" and group "Foo" would be:
+ </para>
+
+ <programlisting>
+Product Bar:
+foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS
+ </programlisting>
+
+ <para>
+ The above indicates that for product "Bar", members of group "Foo" can
+ enter bugs. Any one with permission to edit a bug against product "Bar"
+ can put the bug
+ in group "Foo", even if they themselves are not in "Foo". Anyone in group
+ "Foo" can edit all aspects of the components of product "Bar", can confirm
+ bugs against product "Bar", and can edit all fields of any bug against
+ product "Bar".
+ </para>
+
+ <para>
+ General User Access With Security Group
+ </para>
+
+ <para>
+ To permit any user to file bugs against "Product A",
+ and to permit any user to submit those bugs into a
+ group called "Security":
+ </para>
+
+ <programlisting>
+Product A:
+security: SHOWN/SHOWN
+ </programlisting>
+
+ <para>
+ General User Access With A Security Product
+ </para>
+
+ <para>
+ To permit any user to file bugs against product called "Security"
+ while keeping those bugs from becoming visible to anyone
+ outside the group "SecurityWorkers" (unless a member of the
+ "SecurityWorkers" group removes that restriction):
+ </para>
+
+ <programlisting>
+Product Security:
+securityworkers: DEFAULT/MANDATORY
+ </programlisting>
+
+ <para>
+ Product Isolation With a Common Group
+ </para>
+
+ <para>
+ To permit users of "Product A" to access the bugs for
+ "Product A", users of "Product B" to access the bugs for
+ "Product B", and support staff, who are members of the "Support
+ Group" to access both, three groups are needed:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>Support Group: Contains members of the support staff.</para>
+ </listitem>
+
+ <listitem>
+ <para>AccessA Group: Contains users of product A and the Support group.</para>
+ </listitem>
+
+ <listitem>
+ <para>AccessB Group: Contains users of product B and the Support group.</para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Once these three groups are defined, the product group controls
+ can be set to:
+ </para>
+
+ <programlisting>
+Product A:
+AccessA: ENTRY, MANDATORY/MANDATORY
+Product B:
+AccessB: ENTRY, MANDATORY/MANDATORY
+ </programlisting>
+
+ <para>
+ Perhaps the "Support Group" wants more control. For example,
+ the "Support Group" could be permitted to make bugs inaccessible to
+ users of both groups "AccessA" and "AccessB".
+ Then, the "Support Group" could be permitted to publish
+ bugs relevant to all users in a third product (let's call it
+ "Product Common") that is read-only
+ to anyone outside the "Support Group". In this way the "Support Group"
+ could control bugs that should be seen by both groups.
+ That configuration would be:
+ </para>
+
+ <programlisting>
+Product A:
+AccessA: ENTRY, MANDATORY/MANDATORY
+Support: SHOWN/NA
+Product B:
+AccessB: ENTRY, MANDATORY/MANDATORY
+Support: SHOWN/NA
+Product Common:
+Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
+ </programlisting>
+
+ <para>
+ Make a Product Read Only
+ </para>
+
+ <para>
+ Sometimes a product is retired and should no longer have
+ new bugs filed against it (for example, an older version of a software
+ product that is no longer supported). A product can be made read-only
+ by creating a group called "readonly" and adding products to the
+ group as needed:
+ </para>
+
+ <programlisting>
+Product A:
+ReadOnly: ENTRY, NA/NA, CANEDIT
+ </programlisting>
+
+ <note>
+ <para>
+ For more information on Groups outside of how they relate to products
+ see <xref linkend="groups"/>.
+ </para>
+ </note>
+
+ </section>
+
+ </section>
+
+ </section>
+
+ <section id="components" xreflabel="Components">
+ <title>Components</title>
+
+ <para>Components are subsections of a Product. E.g. the computer game
+ you are designing may have a "UI"
+ component, an "API" component, a "Sound System" component, and a
+ "Plugins" component, each overseen by a different programmer. It
+ often makes sense to divide Components in Bugzilla according to the
+ natural divisions of responsibility within your Product or
+ company.</para>
+
+ <para>
+ Each component has a default assignee and (if you turned it on in the parameters),
+ a QA Contact. The default assignee should be the primary person who fixes bugs in
+ that component. The QA Contact should be the person who will ensure
+ these bugs are completely fixed. The Assignee, QA Contact, and Reporter
+ will get email when new bugs are created in this Component and when
+ these bugs change. Default Assignee and Default QA Contact fields only
+ dictate the
+ <emphasis>default assignments</emphasis>;
+ these can be changed on bug submission, or at any later point in
+ a bug's life.</para>
+
+ <para>To create a new Component:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Select the <quote>Edit components</quote> link
+ from the <quote>Edit product</quote> page</para>
+ </listitem>
+
+ <listitem>
+ <para>Select the <quote>Add</quote> link in the bottom right.</para>
+ </listitem>
+
+ <listitem>
+ <para>Fill out the <quote>Component</quote> field, a
+ short <quote>Description</quote>, the
+ <quote>Default Assignee</quote>, <quote>Default CC List</quote>
+ and <quote>Default QA Contact</quote> (if enabled).
+ The <quote>Component Description</quote> field may contain a
+ limited subset of HTML tags. The <quote>Default Assignee</quote>
+ field must be a login name already existing in the Bugzilla database.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="versions">
+ <title>Versions</title>
+
+ <para>Versions are the revisions of the product, such as "Flinders
+ 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
+ field; the usual practice is to select the earliest version known to have
+ the bug.
+ </para>
+
+ <para>To create and edit Versions:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>From the "Edit product" screen, select "Edit Versions"</para>
+ </listitem>
+
+ <listitem>
+ <para>You will notice that the product already has the default
+ version "undefined". Click the "Add" link in the bottom right.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enter the name of the Version. This field takes text only.
+ Then click the "Add" button.</para>
+ </listitem>
+
+ </orderedlist>
+ </section>
+
+ <section id="milestones">
+ <title>Milestones</title>
+
+ <para>Milestones are "targets" that you plan to get a bug fixed by. For
+ example, you have a bug that you plan to fix for your 3.0 release, it
+ would be assigned the milestone of 3.0.</para>
+
+ <note>
+ <para>Milestone options will only appear for a Product if you turned
+ on the "usetargetmilestone" Param in the "Edit Parameters" screen.
+ </para>
+ </note>
+
+ <para>To create new Milestones, set Default Milestones, and set
+ Milestone URL:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Select "Edit milestones" from the "Edit product" page.</para>
+ </listitem>
+
+ <listitem>
+ <para>Select "Add" in the bottom right corner.
+ text</para>
+ </listitem>
+
+ <listitem>
+ <para>Enter the name of the Milestone in the "Milestone" field. You
+ can optionally set the "sortkey", which is a positive or negative
+ number (-32768 to 32767) that defines where in the list this particular
+ milestone appears. This is because milestones often do not
+ occur in alphanumeric order For example, "Future" might be
+ after "Release 1.2". Select "Add".</para>
+ </listitem>
+
+ <listitem>
+ <para>From the Edit product screen, you can enter the URL of a
+ page which gives information about your milestones and what
+ they mean. </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="flags-overview">
+ <title>Flags</title>
+
+ <para>
+ Flags are a way to attach a specific status to a bug or attachment,
+ either <quote>+</quote> or <quote>-</quote>. The meaning of these symbols depends on the text
+ the flag itself, but contextually they could mean pass/fail,
+ accept/reject, approved/denied, or even a simple yes/no. If your site
+ allows requestable flags, then users may set a flag to <quote>?</quote> as a
+ request to another user that they look at the bug/attachment, and set
+ the flag to its correct status.
+ </para>
+
+ <section id="flags-simpleexample">
+ <title>A Simple Example</title>
+
+ <para>
+ A developer might want to ask their manager,
+ <quote>Should we fix this bug before we release version 2.0?</quote>
+ They might want to do this for a <emphasis>lot</emphasis> of bugs,
+ so it would be nice to streamline the process...
+ </para>
+ <para>
+ In Bugzilla, it would work this way:
+ <orderedlist>
+ <listitem>
+ <para>
+ The Bugzilla administrator creates a flag type called
+ <quote>blocking2.0</quote> that shows up on all bugs in
+ your product.
+ </para>
+
+ <para>
+ It shows up on the <quote>Show Bug</quote> screen
+ as the text <quote>blocking2.0</quote> with a drop-down box next
+ to it. The drop-down box contains four values: an empty space,
+ <quote>?</quote>, <quote>-</quote>, and <quote>+</quote>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The developer sets the flag to <quote>?</quote>.</para>
+ </listitem>
+ <listitem>
+ <para>
+ The manager sees the <computeroutput>blocking2.0</computeroutput>
+ flag with a <quote>?</quote> value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the manager thinks the feature should go into the product
+ before version 2.0 can be released, he sets the flag to
+ <quote>+</quote>. Otherwise, he sets it to <quote>-</quote>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now, every Bugzilla user who looks at the bug knows whether or
+ not the bug needs to be fixed before release of version 2.0.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ </section>
+
+ <section id="flags-about">
+ <title>About Flags</title>
+
+ <section id="flag-values">
+ <title>Values</title>
+ <para>
+ Flags can have three values:
+ <variablelist>
+ <varlistentry>
+ <term><computeroutput>?</computeroutput></term>
+ <listitem><simpara>
+ A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput>-</computeroutput></term>
+ <listitem><simpara>
+ The status has been set negatively. (The question has been answered <quote>no</quote>.)
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput>+</computeroutput></term>
+ <listitem><simpara>
+ The status has been set positively.
+ (The question has been answered <quote>yes</quote>.)
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ Actually, there's a fourth value a flag can have --
+ <quote>unset</quote> -- which shows up as a blank space. This
+ just means that nobody has expressed an opinion (or asked
+ someone else to express an opinion) about this bug or attachment.
+ </para>
+ </section>
+ </section>
+
+ <section id="flag-askto">
+ <title>Using flag requests</title>
+ <para>
+ If a flag has been defined as 'requestable', and a user has enough privileges
+ to request it (see below), the user can set the flag's status to <quote>?</quote>.
+ This status indicates that someone (a.k.a. <quote>the requester</quote>) is asking
+ someone else to set the flag to either <quote>+</quote> or <quote>-</quote>.
+ </para>
+ <para>
+ If a flag has been defined as 'specifically requestable',
+ a text box will appear next to the flag into which the requester may
+ enter a Bugzilla username. That named person (a.k.a. <quote>the requestee</quote>)
+ will receive an email notifying them of the request, and pointing them
+ to the bug/attachment in question.
+ </para>
+ <para>
+ If a flag has <emphasis>not</emphasis> been defined as 'specifically requestable',
+ then no such text-box will appear. A request to set this flag cannot be made of
+ any specific individual, but must be asked <quote>to the wind</quote>.
+ A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank.
+ </para>
+ </section>
+
+ <section id="flag-types">
+ <title>Two Types of Flags</title>
+
+ <para>
+ Flags can go in two places: on an attachment, or on a bug.
+ </para>
+
+ <section id="flag-type-attachment">
+ <title>Attachment Flags</title>
+
+ <para>
+ Attachment flags are used to ask a question about a specific
+ attachment on a bug.
+ </para>
+ <para>
+ Many Bugzilla installations use this to
+ request that one developer <quote>review</quote> another
+ developer's code before they check it in. They attach the code to
+ a bug report, and then set a flag on that attachment called
+ <quote>review</quote> to
+ <computeroutput>review?boss@domain.com</computeroutput>.
+ boss@domain.com is then notified by email that
+ he has to check out that attachment and approve it or deny it.
+ </para>
+
+ <para>
+ For a Bugzilla user, attachment flags show up in three places:
+ <orderedlist>
+ <listitem>
+ <para>
+ On the list of attachments in the <quote>Show Bug</quote>
+ screen, you can see the current state of any flags that
+ have been set to ?, +, or -. You can see who asked about
+ the flag (the requester), and who is being asked (the
+ requestee).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When you <quote>Edit</quote> an attachment, you can
+ see any settable flag, along with any flags that have
+ already been set. This <quote>Edit Attachment</quote>
+ screen is where you set flags to ?, -, +, or unset them.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Requests are listed in the <quote>Request Queue</quote>, which
+ is accessible from the <quote>My Requests</quote> link (if you are
+ logged in) or <quote>Requests</quote> link (if you are logged out)
+ visible in the footer of all pages.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ </section>
+
+ <section id="flag-type-bug">
+ <title>Bug Flags</title>
+
+ <para>
+ Bug flags are used to set a status on the bug itself. You can
+ see Bug Flags in the <quote>Show Bug</quote> and <quote>Requests</quote>
+ screens, as described above.
+ </para>
+ <para>
+ Only users with enough privileges (see below) may set flags on bugs.
+ This doesn't necessarily include the assignee, reporter, or users with the
+ <computeroutput>editbugs</computeroutput> permission.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="flags-admin">
+ <title>Administering Flags</title>
+
+ <para>
+ If you have the <quote>editcomponents</quote> permission, you can
+ edit Flag Types from the main administration page. Clicking the
+ <quote>Flags</quote> link will bring you to the <quote>Administer
+ Flag Types</quote> page. Here, you can select whether you want
+ to create (or edit) a Bug flag, or an Attachment flag.
+ </para>
+ <para>
+ No matter which you choose, the interface is the same, so we'll
+ just go over it once.
+ </para>
+
+ <section id="flags-edit">
+ <title>Editing a Flag</title>
+ <para>
+ To edit a flag's properties, just click on the <quote>Edit</quote>
+ link next to the flag's description. That will take you to the same
+ form as described below (<xref linkend="flags-create"/>).
+ </para>
+ </section>
+
+ <section id="flags-create">
+ <title>Creating a Flag</title>
+
+ <para>
+ When you click on the <quote>Create a Flag Type for...</quote>
+ link, you will be presented with a form. Here is what the fields in
+ the form mean:
+ </para>
+
+ <section id="flags-create-field-name">
+ <title>Name</title>
+ <para>
+ This is the name of the flag. This will be displayed
+ to Bugzilla users who are looking at or setting the flag.
+ The name may contain any valid Unicode characters except commas
+ and spaces.
+ </para>
+ </section>
+
+ <section id="flags-create-field-description">
+ <title>Description</title>
+ <para>
+ The description describes the flag in more detail. It is visible
+ in a tooltip when hovering over a flag either in the <quote>Show Bug</quote>
+ or <quote>Edit Attachment</quote> pages. This field can be as
+ long as you like, and can contain any character you want.
+ </para>
+ </section>
+
+ <section id="flags-create-field-category">
+ <title>Category</title>
+
+ <para>
+ Default behaviour for a newly-created flag is to appear on
+ products and all components, which is why <quote>__Any__:__Any__</quote>
+ is already entered in the <quote>Inclusions</quote> box.
+ If this is not your desired behaviour, you must either set some
+ exclusions (for products on which you don't want the flag to appear),
+ or you must remove <quote>__Any__:__Any__</quote> from the Inclusions box
+ and define products/components specifically for this flag.
+ </para>
+
+ <para>
+ To create an Inclusion, select a Product from the top drop-down box.
+ You may also select a specific component from the bottom drop-down box.
+ (Setting <quote>__Any__</quote> for Product translates to,
+ <quote>all the products in this Bugzilla</quote>.
+ Selecting <quote>__Any__</quote> in the Component field means
+ <quote>all components in the selected product.</quote>)
+ Selections made, press <quote>Include</quote>, and your
+ Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right.
+ </para>
+
+ <para>
+ To create an Exclusion, the process is the same; select a Product from the
+ top drop-down box, select a specific component if you want one, and press
+ <quote>Exclude</quote>. The Product/Component pairing will show up in the
+ <quote>Exclusions</quote> box on the right.
+ </para>
+
+ <para>
+ This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any
+ products/components that appearing in the <quote>Inclusions</quote> box
+ (or which fall under the appropriate <quote>__Any__</quote>).
+ This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on
+ any products appearing in the <quote>Exclusions</quote> box.
+ <emphasis> IMPORTANT: Exclusions override inclusions.</emphasis>
+ </para>
+
+ <para>
+ You may select a Product without selecting a specific Component,
+ but you can't select a Component without a Product, or to select a
+ Component that does not belong to the named Product. If you do so,
+ Bugzilla will display an error message, even if all your products
+ have a component by that name.
+ </para>
+
+ <para><emphasis>Example:</emphasis> Let's say you have a product called
+ <quote>Jet Plane</quote> that has thousands of components. You want
+ to be able to ask if a problem should be fixed in the next model of
+ plane you release. We'll call the flag <quote>fixInNext</quote>.
+ But, there's one component in <quote>Jet Plane,</quote>
+ called <quote>Pilot.</quote> It doesn't make sense to release a
+ new pilot, so you don't want to have the flag show up in that component.
+ So, you include <quote>Jet Plane:__Any__</quote> and you exclude
+ <quote>Jet Plane:Pilot</quote>.
+ </para>
+ </section>
+
+ <section id="flags-create-field-sortkey">
+ <title>Sort Key</title>
+ <para>
+ Flags normally show up in alphabetical order. If you want them to
+ show up in a different order, you can use this key set the order on each flag.
+ Flags with a lower sort key will appear before flags with a higher
+ sort key. Flags that have the same sort key will be sorted alphabetically,
+ but they will still be after flags with a lower sort key, and before flags
+ with a higher sort key.
+ </para>
+ <para>
+ <emphasis>Example:</emphasis> I have AFlag (Sort Key 100), BFlag (Sort Key 10),
+ CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in
+ the order: DFlag, BFlag, CFlag, AFlag.
+ </para>
+ </section>
+
+ <section id="flags-create-field-active">
+ <title>Active</title>
+ <para>
+ Sometimes, you might want to keep old flag information in the
+ Bugzilla database, but stop users from setting any new flags of this type.
+ To do this, uncheck <quote>active</quote>. Deactivated
+ flags will still show up in the UI if they are ?, +, or -, but they
+ may only be cleared (unset), and cannot be changed to a new value.
+ Once a deactivated flag is cleared, it will completely disappear from a
+ bug/attachment, and cannot be set again.
+ </para>
+ </section>
+
+ <section id="flags-create-field-requestable">
+ <title>Requestable</title>
+ <para>
+ New flags are, by default, <quote>requestable</quote>, meaning that they
+ offer users the <quote>?</quote> option, as well as <quote>+</quote>
+ and <quote>-</quote>.
+ To remove the ? option, uncheck <quote>requestable</quote>.
+ </para>
+ </section>
+
+ <section id="flags-create-field-specific">
+ <title>Specifically Requestable</title>
+ <para>
+ By default this box is checked for new flags, meaning that users may make
+ flag requests of specific individuals. Unchecking this box will remove the
+ text box next to a flag; if it is still requestable, then requests may
+ only be made <quote>to the wind.</quote> Removing this after specific
+ requests have been made will not remove those requests; that data will
+ stay in the database (though it will no longer appear to the user).
+ </para>
+ </section>
+
+ <section id="flags-create-field-multiplicable">
+ <title>Multiplicable</title>
+ <para>
+ Any flag with <quote>Multiplicable</quote> set (default for new flags is 'on')
+ may be set more than once. After being set once, an unset flag
+ of the same type will appear below it with <quote>addl.</quote> (short for
+ <quote>additional</quote>) before the name. There is no limit to the number of
+ times a Multiplicable flags may be set on the same bug/attachment.
+ </para>
+ </section>
+
+ <section id="flags-create-field-cclist">
+ <title>CC List</title>
+
+ <para>
+ If you want certain users to be notified every time this flag is
+ set to ?, -, +, or unset, add them here. This is a comma-separated
+ list of email addresses that need not be restricted to Bugzilla usernames.
+ </para>
+ </section>
+
+ <section id="flags-create-grant-group">
+ <title>Grant Group</title>
+ <para>
+ When this field is set to some given group, only users in the group
+ can set the flag to <quote>+</quote> and <quote>-</quote>. This
+ field does not affect who can request or cancel the flag. For that,
+ see the <quote>Request Group</quote> field below. If this field
+ is left blank, all users can set or delete this flag. This field is
+ useful for restricting which users can approve or reject requests.
+ </para>
+ </section>
+
+ <section id="flags-create-request-group">
+ <title>Request Group</title>
+ <para>
+ When this field is set to some given group, only users in the group
+ can request or cancel this flag. Note that this field has no effect
+ if the <quote>grant group</quote> field is empty. You can set the
+ value of this field to a different group, but both fields have to be
+ set to a group for this field to have an effect.
+ </para>
+ </section>
+ </section> <!-- flags-create -->
+
+ <section id="flags-delete">
+ <title>Deleting a Flag</title>
+
+ <para>
+ When you are at the <quote>Administer Flag Types</quote> screen,
+ you will be presented with a list of Bug flags and a list of Attachment
+ Flags.
+ </para>
+ <para>
+ To delete a flag, click on the <quote>Delete</quote> link next to
+ the flag description.
+ </para>
+ <warning>
+ <para>
+ Once you delete a flag, it is <emphasis>gone</emphasis> from
+ your Bugzilla. All the data for that flag will be deleted.
+ Everywhere that flag was set, it will disappear,
+ and you cannot get that data back. If you want to keep flag data,
+ but don't want anybody to set any new flags or change current flags,
+ unset <quote>active</quote> in the flag Edit form.
+ </para>
+ </warning>
+ </section>
+
+ </section> <!-- flags-admin -->
+
+ <!-- XXX We should add a "Uses of Flags" section, here, with examples. -->
+
+ </section> <!-- flags -->
+
+ <section id="keywords">
+ <title>Keywords</title>
+
+ <para>
+ The administrator can define keywords which can be used to tag and
+ categorise bugs. For example, the keyword "regression" is commonly used.
+ A company might have a policy stating all regressions
+ must be fixed by the next release - this keyword can make tracking those
+ bugs much easier.
+ </para>
+ <para>
+ Keywords are global, rather than per-product. If the administrator changes
+ a keyword currently applied to any bugs, the keyword cache must be rebuilt
+ using the <xref linkend="sanitycheck"/> script. Currently keywords can not
+ be marked obsolete to prevent future usage.
+ </para>
+ <para>
+ Keywords can be created, edited or deleted by clicking the "Keywords"
+ link in the admin page. There are two fields for each keyword - the keyword
+ itself and a brief description. Once created, keywords can be selected
+ and applied to individual bugs in that bug's "Details" section.
+ </para>
+ </section>
+
+ <section id="custom-fields">
+ <title>Custom Fields</title>
+
+ <para>
+ The release of Bugzilla 3.0 added the ability to create Custom Fields.
+ Custom Fields are treated like any other field - they can be set in bugs
+ and used for search queries. Administrators should keep in mind that
+ adding too many fields can make the user interface more complicated and
+ harder to use. Custom Fields should be added only when necessary and with
+ careful consideration.
+ </para>
+ <tip>
+ <para>
+ Before adding a Custom Field, make sure that Bugzilla can not already
+ do the desired behavior. Many Bugzilla options are not enabled by
+ default, and many times Administrators find that simply enabling
+ certain options that already exist is sufficient.
+ </para>
+ </tip>
+ <para>
+ Administrators can manage Custom Fields using the
+ <quote>Custom Fields</quote> link on the Administration page. The Custom
+ Fields administration page displays a list of Custom Fields, if any exist,
+ and a link to "Add a new custom field".
+ </para>
+
+ <section id="add-custom-fields">
+ <title>Adding Custom Fields</title>
+
+ <para>
+ To add a new Custom Field, click the "Add a new custom field" link. This
+ page displays several options for the new field, described below.
+ </para>
+
+ <para>
+ The following attributes must be set for each new custom field:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Name:</emphasis>
+ The name of the field in the database, used internally. This name
+ MUST begin with <quote>cf_</quote> to prevent confusion with
+ standard fields. If this string is omitted, it will
+ be automatically added to the name entered.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Description:</emphasis>
+ A brief string which is used as the label for this Custom Field.
+ That is the string that users will see, and should be
+ short and explicit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Type:</emphasis>
+ The type of field to create. There are
+ several types available:
+ <simplelist>
+ <member>
+ Large Text Box: A multiple line box for entering free text.
+ </member>
+ <member>
+ Free Text: A single line box for entering free text.
+ </member>
+ <member>
+ Multiple-Selection Box: A list box where multiple options
+ can be selected. After creating this field, it must be edited
+ to add the selection options. See
+ <xref linkend="edit-values-list" /> for information about
+ editing legal values.
+ </member>
+ <member>
+ Drop Down: A list box where only one option can be selected.
+ After creating this field, it must be edited to add the
+ selection options. See
+ <xref linkend="edit-values-list" /> for information about
+ editing legal values.
+ </member>
+ <member>
+ Date/Time: A date field. This field appears with a
+ calendar widget for choosing the date.
+ </member>
+ </simplelist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Sortkey:</emphasis>
+ Integer that determines in which order Custom Fields are
+ displayed in the User Interface, especially when viewing a bug.
+ Fields with lower values are displayed first.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Can be set on bug creation:</emphasis>
+ Boolean that determines whether this field can be set on
+ bug creation. If not selected, then a bug must be created
+ before this field can be set. See <xref linkend="bugreports" />
+ for information about filing bugs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Displayed in bugmail for new bugs:</emphasis>
+ Boolean that determines whether the value set on this field
+ should appear in bugmail when the bug is filed. This attribute
+ has no effect if the field cannot be set on bug creation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Is obsolete:</emphasis>
+ Boolean that determines whether this field should
+ be displayed at all. Obsolete Custom Fields are hidden.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="edit-custom-fields">
+ <title>Editing Custom Fields</title>
+
+ <para>
+ As soon as a Custom Field is created, its name and type cannot be
+ changed. If this field is a drop down menu, its legal values can
+ be set as described in <xref linkend="edit-values-list" />. All
+ other attributes can be edited as described above.
+ </para>
+ </section>
+
+ <section id="delete-custom-fields">
+ <title>Deleting Custom Fields</title>
+
+ <para>
+ It is only possible to delete obsolete Custom Fields
+ if the field has never been used in the database.
+ To remove a field which already has content,
+ mark it as obsolete.
+ </para>
+ </section>
+ </section>
+
+ <section id="edit-values">
+ <title>Legal Values</title>
+
+ <para>
+ Since Bugzilla 2.20 RC1, legal values for Operating Systems, platforms,
+ bug priorities and severities can be edited from the User Interface
+ directly. This means that it is no longer required to manually edit
+ <filename>localconfig</filename>. Starting with Bugzilla 2.23.3,
+ the list of valid resolutions can be customized from the same interface.
+ Since Bugzilla 3.1.1 the list of valid bug statuses can be customized
+ as well.
+ </para>
+
+ <section id="edit-values-list">
+ <title>Viewing/Editing legal values</title>
+ <para>
+ Editing legal values requires <quote>admin</quote> privileges.
+ Select "Legal Values" from the Administration page. A list of all
+ fields, both system fields and Custom Fields, for which legal values
+ can be edited appears. Click a field name to edit its legal values.
+ </para>
+ <para>
+ There is no limit to how many values a field can have, but each value
+ must be unique to that field. The sortkey is important to display these
+ values in the desired order.
+ </para>
+ </section>
+
+ <section id="edit-values-delete">
+ <title>Deleting legal values</title>
+ <para>
+ Legal values from Custom Fields can be deleted, but only if the
+ following two conditions are respected:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>The value is not used by default for the field.</para>
+ </listitem>
+
+ <listitem>
+ <para>No bug is currently using this value.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ If any of these conditions is not respected, the value cannot be deleted.
+ The only way to delete these values is to reassign bugs to another value
+ and to set another value as default for the field.
+ </para>
+ </section>
+ </section>
+
+ <section id="bug_status_workflow">
+ <title>Bug Status Workflow</title>
+
+ <para>
+ The bug status workflow is no longer hardcoded but can be freely customized
+ from the web interface. Only one bug status cannot be renamed nor deleted,
+ UNCONFIRMED, but the workflow involving it is free. The configuration
+ page displays all existing bug statuses twice, first on the left for bug
+ statuses we come from and on the top for bug statuses we move to.
+ If the checkbox is checked, then the transition between the two bug statuses
+ is legal, else it's forbidden independently of your privileges. The bug status
+ used for the "duplicate_or_move_bug_status" parameter must be part of the
+ workflow as that is the bug status which will be used when duplicating or
+ moving a bug, so it must be available from each bug status.
+ </para>
+ <para>
+ When the workflow is set, the "View Current Triggers" link below the table
+ lets you set which transitions require a comment from the user.
+ </para>
+ </section>
+
+ <section id="voting">
+ <title>Voting</title>
+
+ <para>Voting allows users to be given a pot of votes which they can allocate
+ to bugs, to indicate that they'd like them fixed.
+ This allows developers to gauge
+ user need for a particular enhancement or bugfix. By allowing bugs with
+ a certain number of votes to automatically move from "UNCONFIRMED" to
+ "NEW", users of the bug system can help high-priority bugs garner
+ attention so they don't sit for a long time awaiting triage.</para>
+
+ <para>To modify Voting settings:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Navigate to the "Edit product" screen for the Product you
+ wish to modify</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Maximum Votes per person</emphasis>:
+ Setting this field to "0" disables voting.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Maximum Votes a person can put on a single
+ bug</emphasis>:
+ It should probably be some number lower than the
+ "Maximum votes per person". Don't set this field to "0" if
+ "Maximum votes per person" is non-zero; that doesn't make
+ any sense.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Number of votes a bug in this product needs to
+ automatically get out of the UNCONFIRMED state</emphasis>:
+ Setting this field to "0" disables the automatic move of
+ bugs from UNCONFIRMED to NEW.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Once you have adjusted the values to your preference, click
+ "Update".</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="quips">
+ <title>Quips</title>
+
+ <para>
+ Quips are small text messages that can be configured to appear
+ next to search results. A Bugzilla installation can have its own specific
+ quips. Whenever a quip needs to be displayed, a random selection
+ is made from the pool of already existing quips.
+ </para>
+
+ <para>
+ Quips are controlled by the <emphasis>enablequips</emphasis> parameter.
+ It has several possible values: on, approved, frozen or off.
+ In order to enable quips approval you need to set this parameter
+ to "approved". In this way, users are free to submit quips for
+ addition but an administrator must explicitly approve them before
+ they are actually used.
+ </para>
+
+ <para>
+ In order to see the user interface for the quips, it is enough to click
+ on a quip when it is displayed together with the search results. Or
+ it can be seen directly in the browser by visiting the quips.cgi URL
+ (prefixed with the usual web location of the Bugzilla installation).
+ Once the quip interface is displayed, it is enough to click the
+ "view and edit the whole quip list" in order to see the administration
+ page. A page with all the quips available in the database will
+ be displayed.
+ </para>
+
+ <para>
+ Next to each tip there is a checkbox, under the
+ "Approved" column. Quips who have this checkbox checked are
+ already approved and will appear next to the search results.
+ The ones that have it unchecked are still preserved in the
+ database but they will not appear on search results pages.
+ User submitted quips have initially the checkbox unchecked.
+ </para>
+
+ <para>
+ Also, there is a delete link next to each quip,
+ which can be used in order to permanently delete a quip.
+ </para>
+ </section>
+
+ <section id="groups">
+ <title>Groups and Group Security</title>
+
+ <para>
+ Groups allow for separating bugs into logical divisions.
+ Groups are typically used to
+ to isolate bugs that should only be seen by certain people. For
+ example, a company might create a different group for each one of its customers
+ or partners. Group permissions could be set so that each partner or customer would
+ only have access to their own bugs. Or, groups might be used to create
+ variable access controls for different departments within an organization.
+ Another common use of groups is to associate groups with products,
+ creating isolation and access control on a per-product basis.
+ </para>
+
+ <para>
+ Groups and group behaviors are controlled in several places:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ The group configuration page. To view or edit existing groups, or to
+ create new groups, access the "Groups" link from the "Administration"
+ page. This section of the manual deals primarily with the aspect of
+ group controls accessed on this page.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Global configuration parameters. Bugzilla has several parameters
+ that control the overall default group behavior and restriction
+ levels. For more information on the parameters that control
+ group behavior globally, see <xref linkend="param-group-security"/>.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ Product association with groups. Most of the functionality of groups
+ and group security is controlled at the product level. Some aspects
+ of group access controls for products are discussed in this section,
+ but for more detail see <xref linkend="product-group-controls"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Group access for users. See <xref linkend="users-and-groups"/> for
+ details on how users are assigned group access.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Group permissions are such that if a bug belongs to a group, only members
+ of that group can see the bug. If a bug is in more than one group, only
+ members of <emphasis>all</emphasis> the groups that the bug is in can see
+ the bug. For information on granting read-only access to certain people and
+ full edit access to others, see <xref linkend="product-group-controls"/>.
+ </para>
+
+ <note>
+ <para>
+ By default, bugs can also be seen by the Assignee, the Reporter, and
+ by everyone on the CC List, regardless of whether or not the bug would
+ typically be viewable by them. Visibility to the Reporter and CC List can
+ be overridden (on a per-bug basis) by bringing up the bug, finding the
+ section that starts with <quote>Users in the roles selected below...</quote>
+ and un-checking the box next to either 'Reporter' or 'CC List' (or both).
+ </para>
+ </note>
+
+ <section id="create-groups">
+ <title>Creating Groups</title>
+
+ <para>
+ To create a new group, follow the steps below:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Select the <quote>Administration</quote> link in the page footer,
+ and then select the <quote>Groups</quote> link from the
+ Administration page.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A table of all the existing groups is displayed. Below the table is a
+ description of all the fields. To create a new group, select the
+ <quote>Add Group</quote> link under the table of existing groups.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are five fields to fill out. These fields are documented below
+ the form. Choose a name and description for the group. Decide whether
+ this group should be used for bugs (in all likelihood this should be
+ selected). Optionally, choose a regular expression that will
+ automatically add any matching users to the group, and choose an
+ icon that will help identify user comments for the group. The regular
+ expression can be useful, for example, to automatically put all users
+ from the same company into one group (if the group is for a specific
+ customer or partner).
+ </para>
+ <note>
+ <para>
+ If <quote>User RegExp</quote> is filled out, users whose email
+ addresses match the regular expression will automatically be
+ members of the group as long as their email addresses continue
+ to match the regular expression. If their email address changes
+ and no longer matches the regular expression, they will be removed
+ from the group. Versions 2.16 and older of Bugzilla did not automatically
+ remove users who's email addresses no longer matched the RegExp.
+ </para>
+ </note>
+ <warning>
+ <para>
+ If specifying a domain in the regular expression, end
+ the regexp with a "$". Otherwise, when granting access to
+ "@mycompany\.com", access will also be granted to
+ 'badperson@mycompany.com.cracker.net'. Use the syntax,
+ '@mycompany\.com$' for the regular expression.
+ </para>
+ </warning>
+ </listitem>
+
+ <listitem>
+ <para>
+ After the new group is created, it can be edited for additional options.
+ The "Edit Group" page allows for specifying other groups that should be included
+ in this group and which groups should be permitted to add and delete
+ users from this group. For more details, see <xref linkend="edit-groups"/>.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ </section>
+
+ <section id="edit-groups">
+ <title>Editing Groups and Assigning Group Permissions</title>
+
+ <para>
+ To access the "Edit Groups" page, select the
+ <quote>Administration</quote> link in the page footer,
+ and then select the <quote>Groups</quote> link from the Administration page.
+ A table of all the existing groups is displayed. Click on a group name
+ you wish to edit or control permissions for.
+ </para>
+
+ <para>
+ The "Edit Groups" page contains the same five fields present when
+ creating a new group. Below that are two additional sections, "Group
+ Permissions," and "Mass Remove". The "Mass Remove" option simply removes
+ all users from the group who match the regular expression entered. The
+ "Group Permissions" section requires further explanation.
+ </para>
+
+ <para>
+ The "Group Permissions" section on the "Edit Groups" page contains four sets
+ of permissions that control the relationship of this group to other
+ groups. If the 'usevisibilitygroups' parameter is in use (see
+ <xref linkend="parameters"/>) two additional sets of permissions are displayed.
+ Each set consists of two select boxes. On the left, a select box
+ with a list of all existing groups. On the right, a select box listing
+ all groups currently selected for this permission setting (this box will
+ be empty for new groups). The way these controls allow groups to relate
+ to one another is called <emphasis>inheritance</emphasis>.
+ Each of the six permissions is described below.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That Are a Member of This Group</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ Members of any groups selected here will automatically have
+ membership in this group. In other words, members of any selected
+ group will inherit membership in this group.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That This Group Is a Member Of</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ Members of this group will inherit membership to any group
+ selected here. For example, suppose the group being edited is
+ an Admin group. If there are two products (Product1 and Product2)
+ and each product has its
+ own group (Group1 and Group2), and the Admin group
+ should have access to both products,
+ simply select both Group1 and Group2 here.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That Can Grant Membership in This Group</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ The members of any group selected here will be able add users
+ to this group, even if they themselves are not in this group.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That This Group Can Grant Membership In</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ Members of this group can add users to any group selected here,
+ even if they themselves are not in the selected groups.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That Can See This Group</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ Members of any selected group can see the users in this group.
+ This setting is only visible if the 'usevisibilitygroups' parameter
+ is enabled on the Bugzilla Configuration page. See
+ <xref linkend="parameters"/> for information on configuring Bugzilla.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+
+ <term>
+ <emphasis>Groups That This Group Can See</emphasis>
+ </term>
+
+ <listitem>
+ <para>
+ Members of this group can see members in any of the selected groups.
+ This setting is only visible if the 'usevisibilitygroups' parameter
+ is enabled on the the Bugzilla Configuration page. See
+ <xref linkend="parameters"/> for information on configuring Bugzilla.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="users-and-groups">
+ <title>Assigning Users to Groups</title>
+
+ <para>
+ A User can become a member of a group in several ways:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ The user can be explicitly placed in the group by editing
+ the user's profile. This can be done by accessing the "Users" page
+ from the "Administration" page. Use the search form to find the user
+ you want to edit group membership for, and click on their email
+ address in the search results to edit their profile. The profile
+ page lists all the groups, and indicates if the user is a member of
+ the group either directly or indirectly. More information on indirect
+ group membership is below. For more details on User administration,
+ see <xref linkend="useradmin"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The group can include another group of which the user is
+ a member. This is indicated by square brackets around the checkbox
+ next to the group name in the user's profile.
+ See <xref linkend="edit-groups"/> for details on group inheritance.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The user's email address can match the regular expression
+ that has been specified to automatically grant membership to
+ the group. This is indicated by "*" around the check box by the
+ group name in the user's profile.
+ See <xref linkend="create-groups"/> for details on
+ the regular expression option when creating groups.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ </section>
+
+ <section>
+ <title>Assigning Group Controls to Products</title>
+
+ <para>
+ The primary functionality of groups is derived from the relationship of
+ groups to products. The concepts around segregating access to bugs with
+ product group controls can be confusing. For details and examples on this
+ topic, see <xref linkend="product-group-controls" />.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="sanitycheck">
+ <title>Checking and Maintaining Database Integrity</title>
+
+ <para>
+ Over time it is possible for the Bugzilla database to become corrupt
+ or to have anomalies.
+ This could happen through normal usage of Bugzilla, manual database
+ administration outside of the Bugzilla user interface, or from some
+ other unexpected event. Bugzilla includes a "Sanity Check" script that
+ can perform several basic database checks, and repair certain problems or
+ inconsistencies.
+ </para>
+ <para>
+ To run the "Sanity Check" script, log in as an Administrator and click the
+ "Sanity Check" link in the admin page. Any problems that are found will be
+ displayed in red letters. If the script is capable of fixing a problem,
+ it will present a link to initiate the fix. If the script can not
+ fix the problem it will require manual database administration or recovery.
+ </para>
+ <para>
+ The "Sanity Check" script can also be run from the command line via the perl
+ script <filename>sanitycheck.pl</filename>. The script can also be run as
+ a <command>cron</command> job. Results will be delivered by email.
+ </para>
+ <para>
+ The "Sanity Check" script should be run on a regular basis as a matter of
+ best practice.
+ </para>
+ <warning>
+ <para>
+ The "Sanity Check" script is no substitute for a competent database
+ administrator. It is only designed to check and repair basic database
+ problems.
+ </para>
+ </warning>
+
+ </section>
+
+ <section id="upgrading">
+ <title>Upgrading to New Releases</title>
+
+ <para>
+ Upgrading Bugzilla is something we all want to do from time to time,
+ be it to get new features or pick up the latest security fix. How easy
+ it is to update depends on a few factors:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If the new version is a revision or a new point release
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How many local changes (if any) have been made
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="upgrading-version-defns">
+ <title>Version Definitions</title>
+
+ <para>
+ Bugzilla displays the version you are using at the top of the home
+ page <filename>index.cgi</filename>. It looks something like
+ '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is
+ the Major Version. This does not change very often;
+ Bugzilla was 1.x.x when it was first created, and went to 2.x.x
+ when it was re-written in perl in Sept 1998. The major version
+ 3.x.x, released in early 2007, is pretty far from what the 2.x.x
+ series looked like, both about its UI and its code.
+ </para>
+
+ <para>
+ The second number in the version is called the 'minor number', and
+ a release that changes the minor number is called a 'point release'.
+ An even number in this position (2.18, 2.20, 2.22, 3.0, 3.2, etc.)
+ represents a stable version, while an odd number (2.19, 2.21, 2.23, etc.)
+ represents a development version. In the past, stable point releases
+ were feature-based, coming when certain enhancements had been
+ completed, or the Bugzilla development team felt that enough
+ progress had been made overall. As of version 2.18, however,
+ Bugzilla has moved to a time-based release schedule; current plans
+ are to create a stable point release every 6 months or so after
+ 2.18 is deployed.
+ </para>
+
+ <para>
+ The third number in the Bugzilla version represents a bugfix version.
+ Bugfix Revisions are released only to address security vulnerabilities
+ and, for a limited period, bug fixes. Once enough of these
+ bugfixes have accumulated (or a new security vulnerability is
+ identified and closed), a bugfix release is made. As an
+ example, 2.20.3 was a bugfix release, and improved on 2.20.2.
+ </para>
+
+ <note>
+ <para>
+ When reading version numbers, everything separated by a point ('.')
+ should be read as a single number. It is <emphasis>not</emphasis>
+ the same as decimal. 2.22 is newer than 2.8 because minor version
+ 22 is greater than minor version 8. The now unsupported release 2.16.11
+ was newer than 2.16.9 (because bugfix 11 is greater than bugfix 9. This is
+ confusing to some people who aren't used to dealing with software.
+ </para>
+ </note>
+ </section>
+
+ <section id="upgrading-notifications">
+ <title>Upgrading - Notifications</title>
+
+ <para>
+ Bugzilla 3.0 introduces the ability to automatically notify
+ administrators when new releases are available, based on the
+ <literal>upgrade_notification</literal> parameter, see
+ <xref linkend="parameters"/>. Administrators will see these
+ notifications when they access the <filename>index.cgi</filename>
+ page, i.e. generally when logging in. Bugzilla will check once per
+ day for new releases, unless the parameter is set to
+ <quote>disabled</quote>. If you are behind a proxy, you may have to set
+ the <literal>proxy_url</literal> parameter accordingly. If the proxy
+ requires authentication, use the
+ <literal>http://user:pass@proxy_url/</literal> syntax.
+ </para>
+ </section>
+
+ <section id="upgrading-methods">
+ <title>Upgrading - Methods and Procedure</title>
+ <para>
+ There are three different ways to upgrade your installation.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Using CVS (<xref linkend="upgrade-cvs"/>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Downloading a new tarball (<xref linkend="upgrade-tarball"/>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Applying the relevant patches (<xref linkend="upgrade-patches"/>)
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Each of these options has its own pros and cons; the one that's
+ right for you depends on how long it has been since you last
+ installed, the degree to which you have customized your installation,
+ and/or your network configuration. (Some discussion of the various
+ methods of updating compared with degree and methods of local
+ customization can be found in <xref linkend="template-method"/>.)
+ </para>
+
+ <para>
+ The larger the jump you are trying to make, the more difficult it
+ is going to be to upgrade if you have made local customizations.
+ Upgrading from 2.22 to 2.22.1 should be fairly painless even if
+ you are heavily customized, but going from 2.18 to 3.0 is going
+ to mean a fair bit of work re-writing your local changes to use
+ the new files, logic, templates, etc. If you have done no local
+ changes at all, however, then upgrading should be approximately
+ the same amount of work regardless of how long it has been since
+ your version was released.
+ </para>
+
+ <warning>
+ <para>
+ Upgrading is a one-way process. You should backup your database
+ and current Bugzilla directory before attempting the upgrade. If
+ you wish to revert to the old Bugzilla version for any reason, you
+ will have to restore from these backups.
+ </para>
+ </warning>
+
+ <para>
+ The examples in the following sections are written as though the
+ user were updating to version 2.22.1, but the procedures are the
+ same regardless of whether one is updating to a new point release
+ or simply trying to obtain a new bugfix release. Also, in the
+ examples the user's Bugzilla installation is found at
+ <filename>/var/www/html/bugzilla</filename>. If that is not the
+ same as the location of your Bugzilla installation, simply
+ substitute the proper paths where appropriate.
+ </para>
+
+ <section id="upgrade-cvs">
+ <title>Upgrading using CVS</title>
+
+ <para>
+ Every release of Bugzilla, whether it is a point release or a bugfix,
+ is tagged in CVS. Also, every tarball that has been distributed since
+ version 2.12 has been created in such a way that it can be used with
+ CVS once it is unpacked. Doing so, however, requires that you are able
+ to access cvs-mirror.mozilla.org on port 2401, which may not be an
+ option or a possibility for some users, especially those behind a
+ highly restrictive firewall.
+ </para>
+
+ <tip>
+ <para>
+ If you can, updating using CVS is probably the most painless
+ method, especially if you have a lot of local changes.
+ </para>
+ </tip>
+
+ <para>
+ The following shows the sequence of commands needed to update a
+ Bugzilla installation via CVS, and a typical series of results.
+ </para>
+
+ <programlisting>
+bash$ <command>cd /var/www/html/bugzilla</command>
+bash$ <command>cvs login</command>
+Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
+CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis>
+bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command>
+P checksetup.pl
+P collectstats.pl
+P docs/rel_notes.txt
+P template/en/default/list/quips.html.tmpl
+<emphasis>(etc.)</emphasis>
+ </programlisting>
+
+ <caution>
+ <para>
+ If a line in the output from <command>cvs update</command> begins
+ with a <computeroutput>C</computeroutput>, then that represents a
+ file with local changes that CVS was unable to properly merge. You
+ need to resolve these conflicts manually before Bugzilla (or at
+ least the portion using that file) will be usable.
+ </para>
+ </caution>
+ </section>
+
+ <section id="upgrade-tarball">
+ <title>Upgrading using the tarball</title>
+
+ <para>
+ If you are unable (or unwilling) to use CVS, another option that's
+ always available is to obtain the latest tarball from the <ulink
+ url="http://www.bugzilla.org/download/">Download Page</ulink> and
+ create a new Bugzilla installation from that.
+ </para>
+
+ <para>
+ This sequence of commands shows how to get the tarball from the
+ command-line; it is also possible to download it from the site
+ directly in a web browser. If you go that route, save the file
+ to the <filename class="directory">/var/www/html</filename>
+ directory (or its equivalent, if you use something else) and
+ omit the first three lines of the example.
+ </para>
+
+ <programlisting>
+bash$ <command>cd /var/www/html</command>
+bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command>
+<emphasis>(Output omitted)</emphasis>
+bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command>
+bugzilla-2.22.1/
+bugzilla-2.22.1/.cvsignore
+<emphasis>(Output truncated)</emphasis>
+bash$ <command>cd bugzilla-2.22.1</command>
+bash$ <command>cp ../bugzilla/localconfig* .</command>
+bash$ <command>cp -r ../bugzilla/data .</command>
+bash$ <command>cd ..</command>
+bash$ <command>mv bugzilla bugzilla.old</command>
+bash$ <command>mv bugzilla-2.22.1 bugzilla</command>
+ </programlisting>
+
+ <warning>
+ <para>
+ The <command>cp</command> commands both end with periods which
+ is a very important detail, it tells the shell that the destination
+ directory is the current working directory.
+ </para>
+ </warning>
+
+ <para>
+ This upgrade method will give you a clean install of Bugzilla with the
+ same version as the tarball. That's fine if you don't have any local
+ customizations that you want to maintain, but if you do then you will
+ need to reapply them by hand to the appropriate files.
+ </para>
+
+ <para>
+ It's worth noting that since 2.12, the Bugzilla tarballs come
+ CVS-ready, so if you decide at a later date that you'd rather use
+ CVS as an upgrade method, your code will already be set up for it.
+ </para>
+ </section>
+
+ <section id="upgrade-patches">
+ <title>Upgrading using patches</title>
+
+ <para>
+ If you are doing a bugfix upgrade -- that is, one where only the
+ last number of the revision changes, such as from 2.22 to 2.22.1
+ -- then you have the option of obtaining and applying a patch file
+ from the <ulink
+ url="http://www.bugzilla.org/download/">Download Page</ulink>.
+ This file is made available by the <ulink
+ url="http://www.bugzilla.org/developers/profiles.html">Bugzilla
+ Development Team</ulink>, and is a collection of all the bug fixes
+ and security patches that have been made since the last bugfix
+ release. If you are planning to upgrade via patches, it is safer
+ to grab this developer-made patch file than to read the patch
+ notes and apply all (or even just some of) the patches oneself,
+ as sometimes patches on bugs get changed before they get checked in.
+ </para>
+
+ <para>
+ As above, this example starts with obtaining the file via the
+ command line. If you have already downloaded it, you can omit the
+ first two commands.
+ </para>
+
+ <programlisting>
+bash$ <command>cd /var/www/html/bugzilla</command>
+bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command>
+<emphasis>(Output omitted)</emphasis>
+bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command>
+bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command>
+patching file checksetup.pl
+patching file collectstats.pl
+<emphasis>(etc.)</emphasis>
+ </programlisting>
+
+ <warning>
+ <para>
+ Be aware that upgrading from a patch file does not change the
+ entries in your <filename class="directory">CVS</filename> directory.
+ This could make it more difficult to upgrade using CVS
+ (<xref linkend="upgrade-cvs"/>) in the future.
+ </para>
+ </warning>
+
+ </section>
+ </section>
+
+ <section id="upgrading-completion">
+ <title>Completing Your Upgrade</title>
+
+ <para>
+ Regardless of which upgrade method you choose, you will need to
+ run <command>./checksetup.pl</command> before your Bugzilla
+ upgrade will be complete.
+ </para>
+
+ <programlisting>
+bash$ <command>cd bugzilla</command>
+bash$ <command>./checksetup.pl</command>
+ </programlisting>
+
+ <warning>
+ <para>
+ The period at the beginning of the command
+ <command>./checksetup.pl</command> is important and can not
+ be omitted.
+ </para>
+ </warning>
+
+ <para>
+ If you have done a lot of local modifications, it wouldn't hurt
+ to run the Bugzilla Testing suite. This is not a required step,
+ but it isn't going to hurt anything, and might help point out
+ some areas that could be improved. (More information on the
+ test suite can be had by following this link to the appropriate
+ section in the <ulink
+ url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers'
+ Guide</ulink>.)
+ </para>
+
+ </section>
+ </section>
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<section id="conventions">
+ <title>Document Conventions</title>
+
+ <indexterm zone="conventions">
+ <primary>conventions</primary>
+ </indexterm>
+
+ <para>This document uses the following conventions:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Descriptions</entry>
+
+ <entry>Appearance</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Caution</entry>
+
+ <entry>
+ <caution>
+ <para>Don't run with scissors!</para>
+ </caution>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Hint or Tip</entry>
+
+ <entry>
+ <tip>
+ <para>For best results... </para>
+ </tip>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Note</entry>
+
+ <entry>
+ <note>
+ <para>Dear John...</para>
+ </note>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Warning</entry>
+
+ <entry>
+ <warning>
+ <para>Read this or the cat gets it.</para>
+ </warning>
+ </entry>
+ </row>
+
+ <row>
+ <entry>File or directory name</entry>
+
+ <entry>
+ <filename>filename</filename>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Command to be typed</entry>
+
+ <entry>
+ <command>command</command>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Application name</entry>
+
+ <entry>
+ <application>application</application>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ Normal user's prompt under bash shell</entry>
+
+ <entry>bash$</entry>
+ </row>
+
+ <row>
+ <entry>
+ Root user's prompt under bash shell</entry>
+
+ <entry>bash#</entry>
+ </row>
+
+ <row>
+ <entry>
+ Normal user's prompt under tcsh shell</entry>
+
+ <entry>tcsh$</entry>
+ </row>
+
+ <row>
+ <entry>Environment variables</entry>
+
+ <entry>
+ <envar>VARIABLE</envar>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Term found in the glossary</entry>
+
+ <entry>
+ <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Code example</entry>
+
+ <entry>
+ <programlisting><sgmltag class="starttag">para</sgmltag>
+Beginning and end of paragraph
+<sgmltag class="endtag">para</sgmltag></programlisting>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This documentation is maintained in DocBook 4.1.2 XML format.
+ Changes are best submitted as plain text or XML diffs, attached
+ to a bug filed in the &bzg-bugs; component.
+ </para>
+
+</section>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<chapter id="customization">
+ <title>Customizing Bugzilla</title>
+
+ <section id="cust-skins">
+ <title>Custom Skins</title>
+
+ <para>
+ Bugzilla allows you to have multiple skins. These are custom CSS and possibly
+ also custom images for Bugzilla. To create a new custom skin, you have two
+ choices:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Make a single CSS file, and put it in the
+ <filename>skins/contrib</filename> directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Make a directory that contains all the same CSS file
+ names as <filename>skins/standard/</filename>, and put
+ your directory in <filename>skins/contrib/</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ After you put the file or the directory there, make sure to run checksetup.pl
+ so that it can reset the file permissions correctly.
+ </para>
+ <para>
+ After you have installed the new skin, it will show up as an option in the
+ user's General Preferences. If you would like to force a particular skin on all
+ users, just select it in the Default Preferences and then uncheck "Enabled" on
+ the preference.
+ </para>
+ </section>
+
+ <section id="cust-templates">
+ <title>Template Customization</title>
+
+ <para>
+ Administrators can configure the look and feel of Bugzilla without
+ having to edit Perl files or face the nightmare of massive merge
+ conflicts when they upgrade to a newer version in the future.
+ </para>
+
+ <para>
+ Templatization also makes localized versions of Bugzilla possible,
+ for the first time. It's possible to have Bugzilla's UI language
+ determined by the user's browser. More information is available in
+ <xref linkend="template-http-accept"/>.
+ </para>
+
+ <section id="template-directory">
+ <title>Template Directory Structure</title>
+ <para>
+ The template directory structure starts with top level directory
+ named <filename>template</filename>, which contains a directory
+ for each installed localization. The next level defines the
+ language used in the templates. Bugzilla comes with English
+ templates, so the directory name is <filename>en</filename>,
+ and we will discuss <filename>template/en</filename> throughout
+ the documentation. Below <filename>template/en</filename> is the
+ <filename>default</filename> directory, which contains all the
+ standard templates shipped with Bugzilla.
+ </para>
+
+ <warning>
+ <para>
+ A directory <filename>data/templates</filename> also exists;
+ this is where Template Toolkit puts the compiled versions of
+ the templates from either the default or custom directories.
+ <emphasis>Do not</emphasis> directly edit the files in this
+ directory, or all your changes will be lost the next time
+ Template Toolkit recompiles the templates.
+ </para>
+ </warning>
+ </section>
+
+ <section id="template-method">
+ <title>Choosing a Customization Method</title>
+ <para>
+ If you want to edit Bugzilla's templates, the first decision
+ you must make is how you want to go about doing so. There are two
+ choices, and which you use depends mainly on the scope of your
+ modifications, and the method you plan to use to upgrade Bugzilla.
+ </para>
+
+ <para>
+ The first method of making customizations is to directly edit the
+ templates found in <filename>template/en/default</filename>.
+ This is probably the best way to go about it if you are going to
+ be upgrading Bugzilla through CVS, because if you then execute
+ a <command>cvs update</command>, any changes you have made will
+ be merged automagically with the updated versions.
+ </para>
+
+ <note>
+ <para>
+ If you use this method, and CVS conflicts occur during an
+ update, the conflicted templates (and possibly other parts
+ of your installation) will not work until they are resolved.
+ </para>
+ </note>
+
+ <para>
+ The second method is to copy the templates to be modified
+ into a mirrored directory structure under
+ <filename>template/en/custom</filename>. Templates in this
+ directory structure automatically override any identically-named
+ and identically-located templates in the
+ <filename>default</filename> directory.
+ </para>
+
+ <note>
+ <para>
+ The <filename>custom</filename> directory does not exist
+ at first and must be created if you want to use it.
+ </para>
+ </note>
+
+ <para>
+ The second method of customization should be used if you
+ use the overwriting method of upgrade, because otherwise
+ your changes will be lost. This method may also be better if
+ you are using the CVS method of upgrading and are going to make major
+ changes, because it is guaranteed that the contents of this directory
+ will not be touched during an upgrade, and you can then decide whether
+ to continue using your own templates, or make the effort to merge your
+ changes into the new versions by hand.
+ </para>
+
+ <para>
+ Using this method, your installation may break if incompatible
+ changes are made to the template interface. Such changes should
+ be documented in the release notes, provided you are using a
+ stable release of Bugzilla. If you use using unstable code, you will
+ need to deal with this one yourself, although if possible the changes
+ will be mentioned before they occur in the deprecations section of the
+ previous stable release's release notes.
+ </para>
+
+ <note>
+ <para>
+ Regardless of which method you choose, it is recommended that
+ you run <command>./checksetup.pl</command> after creating or
+ editing any templates in the <filename>template/en/default</filename>
+ directory, and after editing any templates in the
+ <filename>custom</filename> directory.
+ </para>
+ </note>
+
+ <warning>
+ <para>
+ It is <emphasis>required</emphasis> that you run
+ <command>./checksetup.pl</command> after creating a new
+ template in the <filename>custom</filename> directory. Failure
+ to do so will raise an incomprehensible error message.
+ </para>
+ </warning>
+ </section>
+
+ <section id="template-edit">
+ <title>How To Edit Templates</title>
+
+ <note>
+ <para>
+ If you are making template changes that you intend on submitting back
+ for inclusion in standard Bugzilla, you should read the relevant
+ sections of the
+ <ulink url="http://www.bugzilla.org/docs/developer.html">Developers'
+ Guide</ulink>.
+ </para>
+ </note>
+
+ <para>
+ The syntax of the Template Toolkit language is beyond the scope of
+ this guide. It's reasonably easy to pick up by looking at the current
+ templates; or, you can read the manual, available on the
+ <ulink url="http://www.template-toolkit.org">Template Toolkit home
+ page</ulink>.
+ </para>
+
+ <para>
+ One thing you should take particular care about is the need
+ to properly HTML filter data that has been passed into the template.
+ This means that if the data can possibly contain special HTML characters
+ such as <, and the data was not intended to be HTML, they need to be
+ converted to entity form, i.e. &lt;. You use the 'html' filter in the
+ Template Toolkit to do this. If you forget, you may open up
+ your installation to cross-site scripting attacks.
+ </para>
+
+ <para>
+ Also note that Bugzilla adds a few filters of its own, that are not
+ in standard Template Toolkit. In particular, the 'url_quote' filter
+ can convert characters that are illegal or have special meaning in URLs,
+ such as &, to the encoded form, i.e. %26. This actually encodes most
+ characters (but not the common ones such as letters and numbers and so
+ on), including the HTML-special characters, so there's never a need to
+ HTML filter afterwards.
+ </para>
+
+ <para>
+ Editing templates is a good way of doing a <quote>poor man's custom
+ fields</quote>.
+ For example, if you don't use the Status Whiteboard, but want to have
+ a free-form text entry box for <quote>Build Identifier</quote>,
+ then you can just
+ edit the templates to change the field labels. It's still be called
+ status_whiteboard internally, but your users don't need to know that.
+ </para>
+
+ </section>
+
+
+ <section id="template-formats">
+ <title>Template Formats and Types</title>
+
+ <para>
+ Some CGI's have the ability to use more than one template. For example,
+ <filename>buglist.cgi</filename> can output itself as RDF, or as two
+ formats of HTML (complex and simple). The mechanism that provides this
+ feature is extensible.
+ </para>
+
+ <para>
+ Bugzilla can support different types of output, which again can have
+ multiple formats. In order to request a certain type, you can append
+ the &ctype=<contenttype> (such as rdf or html) to the
+ <filename><cginame>.cgi</filename> URL. If you would like to
+ retrieve a certain format, you can use the &format=<format>
+ (such as simple or complex) in the URL.
+ </para>
+
+ <para>
+ To see if a CGI supports multiple output formats and types, grep the
+ CGI for <quote>get_format</quote>. If it's not present, adding
+ multiple format/type support isn't too hard - see how it's done in
+ other CGIs, e.g. config.cgi.
+ </para>
+
+ <para>
+ To make a new format template for a CGI which supports this,
+ open a current template for
+ that CGI and take note of the INTERFACE comment (if present.) This
+ comment defines what variables are passed into this template. If
+ there isn't one, I'm afraid you'll have to read the template and
+ the code to find out what information you get.
+ </para>
+
+ <para>
+ Write your template in whatever markup or text style is appropriate.
+ </para>
+
+ <para>
+ You now need to decide what content type you want your template
+ served as. The content types are defined in the
+ <filename>Bugzilla/Constants.pm</filename> file in the
+ <filename>contenttypes</filename>
+ constant. If your content type is not there, add it. Remember
+ the three- or four-letter tag assigned to your content type.
+ This tag will be part of the template filename.
+ </para>
+
+ <note>
+ <para>
+ After adding or changing a content type, it's suitable to edit
+ <filename>Bugzilla/Constants.pm</filename> in order to reflect
+ the changes. Also, the file should be kept up to date after an
+ upgrade if content types have been customized in the past.
+ </para>
+ </note>
+
+ <para>
+ Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>.
+ Try out the template by calling the CGI as
+ <filename><cginame>.cgi?format=<formatname>&ctype=<type></filename> .
+ </para>
+ </section>
+
+
+ <section id="template-specific">
+ <title>Particular Templates</title>
+
+ <para>
+ There are a few templates you may be particularly interested in
+ customizing for your installation.
+ </para>
+
+ <para>
+ <command>index.html.tmpl</command>:
+ This is the Bugzilla front page.
+ </para>
+
+ <para>
+ <command>global/header.html.tmpl</command>:
+ This defines the header that goes on all Bugzilla pages.
+ The header includes the banner, which is what appears to users
+ and is probably what you want to edit instead. However the
+ header also includes the HTML HEAD section, so you could for
+ example add a stylesheet or META tag by editing the header.
+ </para>
+
+ <para>
+ <command>global/banner.html.tmpl</command>:
+ This contains the <quote>banner</quote>, the part of the header
+ that appears
+ at the top of all Bugzilla pages. The default banner is reasonably
+ barren, so you'll probably want to customize this to give your
+ installation a distinctive look and feel. It is recommended you
+ preserve the Bugzilla version number in some form so the version
+ you are running can be determined, and users know what docs to read.
+ </para>
+
+ <para>
+ <command>global/footer.html.tmpl</command>:
+ This defines the footer that goes on all Bugzilla pages. Editing
+ this is another way to quickly get a distinctive look and feel for
+ your Bugzilla installation.
+ </para>
+
+ <para>
+ <command>global/variables.none.tmpl</command>:
+ This defines a list of terms that may be changed in order to
+ <quote>brand</quote> the Bugzilla instance In this way, terms
+ like <quote>bugs</quote> can be replaced with <quote>issues</quote>
+ across the whole Bugzilla installation. The name
+ <quote>Bugzilla</quote> and other words can be customized as well.
+ </para>
+
+ <para>
+ <command>list/table.html.tmpl</command>:
+ This template controls the appearance of the bug lists created
+ by Bugzilla. Editing this template allows per-column control of
+ the width and title of a column, the maximum display length of
+ each entry, and the wrap behaviour of long entries.
+ For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
+ default; this behaviour is also controlled by this template, and
+ that value can be modified here.
+ </para>
+
+ <para>
+ <command>bug/create/user-message.html.tmpl</command>:
+ This is a message that appears near the top of the bug reporting page.
+ By modifying this, you can tell your users how they should report
+ bugs.
+ </para>
+
+ <para>
+ <command>bug/process/midair.html.tmpl</command>:
+ This is the page used if two people submit simultaneous changes to the
+ same bug. The second person to submit their changes will get this page
+ to tell them what the first person did, and ask if they wish to
+ overwrite those changes or go back and revisit the bug. The default
+ title and header on this page read "Mid-air collision detected!" If
+ you work in the aviation industry, or other environment where this
+ might be found offensive (yes, we have true stories of this happening)
+ you'll want to change this to something more appropriate for your
+ environment.
+ </para>
+
+ <para>
+ <command>bug/create/create.html.tmpl</command> and
+ <command>bug/create/comment.txt.tmpl</command>:
+ You may not wish to go to the effort of creating custom fields in
+ Bugzilla, yet you want to make sure that each bug report contains
+ a number of pieces of important information for which there is not
+ a special field. The bug entry system has been designed in an
+ extensible fashion to enable you to add arbitrary HTML widgets,
+ such as drop-down lists or textboxes, to the bug entry page
+ and have their values appear formatted in the initial comment.
+ A hidden field that indicates the format should be added inside
+ the form in order to make the template functional. Its value should
+ be the suffix of the template filename. For example, if the file
+ is called <filename>create-cust.html.tmpl</filename>, then
+ <programlisting><input type="hidden" name="format" value="cust"></programlisting>
+ should be used inside the form.
+ </para>
+
+ <para>
+ An example of this is the mozilla.org
+ <ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&format=guided">guided
+ bug submission form</ulink>. The code for this comes with the Bugzilla
+ distribution as an example for you to copy. It can be found in the
+ files
+ <filename>create-guided.html.tmpl</filename> and
+ <filename>comment-guided.html.tmpl</filename>.
+ </para>
+
+ <para>
+ So to use this feature, create a custom template for
+ <filename>enter_bug.cgi</filename>. The default template, on which you
+ could base it, is
+ <filename>custom/bug/create/create.html.tmpl</filename>.
+ Call it <filename>create-<formatname>.html.tmpl</filename>, and
+ in it, add widgets for each piece of information you'd like
+ collected - such as a build number, or set of steps to reproduce.
+ </para>
+
+ <para>
+ Then, create a template like
+ <filename>custom/bug/create/comment.txt.tmpl</filename>, and call it
+ <filename>comment-<formatname>.txt.tmpl</filename>. This
+ template should reference the form fields you have created using
+ the syntax <filename>[% form.<fieldname> %]</filename>. When a
+ bug report is
+ submitted, the initial comment attached to the bug report will be
+ formatted according to the layout of this template.
+ </para>
+
+ <para>
+ For example, if your custom enter_bug template had a field
+ <programlisting><input type="text" name="buildid" size="30"></programlisting>
+ and then your comment.txt.tmpl had
+ <programlisting>BuildID: [% form.buildid %]</programlisting>
+ then something like
+ <programlisting>BuildID: 20020303</programlisting>
+ would appear in the initial comment.
+ </para>
+ </section>
+
+
+ <section id="template-http-accept">
+ <title>Configuring Bugzilla to Detect the User's Language</title>
+
+ <para>Bugzilla honours the user's Accept: HTTP header. You can install
+ templates in other languages, and Bugzilla will pick the most appropriate
+ according to a priority order defined by you. Many
+ language templates can be obtained from <ulink
+ url="http://www.bugzilla.org/download.html#localizations"/>. Instructions
+ for submitting new languages are also available from that location.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="cust-hooks">
+ <title>The Bugzilla Extension Mechanism</title>
+
+ <warning>
+ <para>
+ Custom extensions require Template Toolkit version 2.12 or
+ above, or the application of a patch. See <ulink
+ url="http://bugzilla.mozilla.org/show_bug.cgi?id=239112">bug
+ 239112</ulink> for details.
+ </para>
+ </warning>
+
+ <para>
+ Extensions are a way for extensions to Bugzilla to insert code
+ into the standard Bugzilla templates and source files
+ without modifying these files themselves. The extension mechanism
+ defines a consistent API for extending the standard templates and source files
+ in a way that cleanly separates standard code from extension code.
+ Hooks reduce merge conflicts and make it easier to write extensions that work
+ across multiple versions of Bugzilla, making upgrading a Bugzilla installation
+ with installed extensions easier. Furthermore, they make it easy to install
+ and remove extensions as each extension is nothing more than a
+ simple directory structure.
+ </para>
+
+ <para>
+ There are two main types of hooks: code hooks and template hooks. Code
+ hooks allow extensions to invoke code at specific points in various
+ source files, while template hooks allow extensions to add elements to
+ the Bugzilla user interface.
+ </para>
+
+ <para>
+ A hook is just a named place in a standard source or template file
+ where extension source code or template files for that hook get processed.
+ Each extension has a corresponding directory in the Bugzilla directory
+ tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>). Hooking
+ an extension source file or template to a hook is as simple as putting
+ the extension file into extension's template or code directory.
+ When Bugzilla processes the source file or template and reaches the hook,
+ it will process all extension files in the hook's directory.
+ The hooks themselves can be added into any source file or standard template
+ upon request by extension authors.
+ </para>
+
+ <para>
+ To use hooks to extend Bugzilla, first make sure there is
+ a hook at the appropriate place within the source file or template you
+ want to extend. The exact appearance of a hook depends on if the hook
+ is a code hook or a template hook.
+ </para>
+
+ <para>
+ Code hooks appear in Bugzilla source files as a single method call
+ in the format <literal role="code">Bugzilla::Hook->process("<varname>name</varname>");</literal>.
+ For instance, <filename>enter_bug.cgi</filename> may invoke the hook
+ "<varname>enter_bug-entrydefaultvars</varname>". Thus, a source file at
+ <filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename>
+ will be automatically invoked when the code hook is reached.
+ </para>
+
+ <para>
+ Template hooks appear in the standard Bugzilla templates as a
+ single directive in the format
+ <literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>,
+ where <varname>name</varname> is the unique name of the hook.
+ </para>
+
+ <para>
+ If you aren't sure what you want to extend or just want to browse the
+ available hooks, either use your favorite multi-file search
+ tool (e.g. <command>grep</command>) to search the standard templates
+ for occurrences of <methodname>Hook.process</methodname> or the source
+ files for occurrences of <methodname>Bugzilla::Hook::process</methodname>.
+ </para>
+
+ <para>
+ If there is no hook at the appropriate place within the Bugzilla
+ source file or template you want to extend,
+ <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface">file
+ a bug requesting one</ulink>, specifying:
+ </para>
+
+ <simplelist>
+ <member>the source or template file for which you are
+ requesting a hook;</member>
+ <member>
+ where in the file you would like the hook to be placed
+ (line number/position for latest version of the file in CVS
+ or description of location);
+ </member>
+ <member>the purpose of the hook;</member>
+ <member>a link to information about your extension, if any.</member>
+ </simplelist>
+
+ <para>
+ The Bugzilla reviewers will promptly review each hook request,
+ name the hook, add it to the template or source file, and check
+ the new version of the template into CVS.
+ </para>
+
+ <para>
+ You may optionally attach a patch to the bug which implements the hook
+ and check it in yourself after receiving approval from a Bugzilla
+ reviewer. The developers may suggest changes to the location of the
+ hook based on their analysis of your needs or so the hook can satisfy
+ the needs of multiple extensions, but the process of getting hooks
+ approved and checked in is not as stringent as the process for general
+ changes to Bugzilla, and any extension, whether released or still in
+ development, can have hooks added to meet their needs.
+ </para>
+
+ <para>
+ After making sure the hook you need exists (or getting it added if not),
+ add your extension to the directory within the Bugzilla
+ extensions tree corresponding to the hook.
+ </para>
+
+ <para>
+ That's it! Now, when the source file or template containing the hook
+ is processed, your extension file will be processed at the point
+ where the hook appears.
+ </para>
+
+ <para>
+ For example, let's say you have an extension named Projman that adds
+ project management capabilities to Bugzilla. Projman has an
+ administration interface <filename>edit-projects.cgi</filename>,
+ and you want to add a link to it into the navigation bar at the bottom
+ of every Bugzilla page for those users who are authorized
+ to administer projects.
+ </para>
+
+ <para>
+ The navigation bar is generated by the template file
+ <filename>useful-links.html.tmpl</filename>, which is located in
+ the <filename>global/</filename> subdirectory on the standard Bugzilla
+ template path
+ <filename>BUGZILLA_ROOT/template/en/default/</filename>.
+ Looking in <filename>useful-links.html.tmpl</filename>, you find
+ the following hook at the end of the list of standard Bugzilla
+ administration links:
+ </para>
+
+ <programlisting><![CDATA[...
+ [% ', <a href="editkeywords.cgi">keywords</a>'
+ IF user.groups.editkeywords %]
+ [% Hook.process("edit") %]
+...]]></programlisting>
+
+ <para>
+ The corresponding extension file for this hook is
+ <filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl</filename>.
+ You then create that template file and add the following constant:
+ </para>
+
+ <programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting>
+
+ <para>
+ Voila! The link now appears after the other administration links in the
+ navigation bar for users in the <literal>projman_admins</literal> group.
+ </para>
+
+ <para>
+ Now, let us say your extension adds a custom "project_manager" field
+ to enter_bug.cgi. You want to modify the CGI script to set the default
+ project manager to be productname@company.com. Looking at
+ <filename>enter_bug.cgi</filename>, you see the enter_bug-entrydefaultvars
+ hook near the bottom of the file before the default form values are set.
+ The corresponding extension source file for this hook is located at
+ <filename>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</filename>.
+ You then create that file and add the following:
+ </para>
+
+ <programlisting>$default{'project_manager'} = $product.'@company.com';</programlisting>
+
+ <para>
+ This code will be invoked whenever enter_bug.cgi is executed.
+ Assuming that the rest of the customization was completed (e.g. the
+ custom field was added to the enter_bug template and the required hooks
+ were used in process_bug.cgi), the new field will now have this
+ default value.
+ </para>
+
+ <para>
+ Notes:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If your extension includes entirely new templates in addition to
+ extensions of standard templates, it should store those new
+ templates in its
+ <filename>BUGZILLA_ROOT/extensions/template/en/</filename>
+ directory. Extension template directories, like the
+ <filename>default/</filename> and <filename>custom/</filename>
+ directories, are part of the template search path, so putting templates
+ there enables them to be found by the template processor.
+ </para>
+
+ <para>
+ The template processor looks for templates first in the
+ <filename>custom/</filename> directory (i.e. templates added by the
+ specific installation), then in the <filename>extensions/</filename>
+ directory (i.e. templates added by extensions), and finally in the
+ <filename>default/</filename> directory (i.e. the standard Bugzilla
+ templates). Thus, installation-specific templates override both
+ default and extension templates.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you are looking to customize Bugzilla, you can also take advantage
+ of template hooks. To do so, create a directory in
+ <filename>BUGZILLA_ROOT/template/en/custom/hook/</filename>
+ that corresponds to the hook you wish to use, then place your
+ customization templates into those directories. For example,
+ if you wanted to use the hook "end" in
+ <filename>global/useful-links.html.tmpl</filename>, you would
+ create the directory <filename>BUGZILLA_ROOT/template/en/custom/hook/
+ global/useful-links.html.tmpl/end/</filename> and add your customization
+ template to this directory.
+ </para>
+
+ <para>
+ Obviously this method of customizing Bugzilla only lets you add code
+ to the standard source files and templates; you cannot change the
+ existing code. Nevertheless, for those customizations that only add
+ code, this method can reduce conflicts when merging changes,
+ making upgrading your customized Bugzilla installation easier.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="cust-change-permissions">
+ <title>Customizing Who Can Change What</title>
+
+ <warning>
+ <para>
+ This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications as outlined here,
+ you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions, and you upgrade.
+ </para>
+ </warning>
+
+ <para>
+ Companies often have rules about which employees, or classes of employees,
+ are allowed to change certain things in the bug system. For example,
+ only the bug's designated QA Contact may be allowed to VERIFY the bug.
+ Bugzilla has been
+ designed to make it easy for you to write your own custom rules to define
+ who is allowed to make what sorts of value transition.
+ </para>
+
+ <para>
+ By default, assignees, QA owners and users
+ with <emphasis>editbugs</emphasis> privileges can edit all fields of bugs,
+ except group restrictions (unless they are members of the groups they
+ are trying to change). Bug reporters also have the ability to edit some
+ fields, but in a more restrictive manner. Other users, without
+ <emphasis>editbugs</emphasis> privileges, can not edit
+ bugs, except to comment and add themselves to the CC list.
+ </para>
+
+ <para>
+ For maximum flexibility, customizing this means editing Bugzilla's Perl
+ code. This gives the administrator complete control over exactly who is
+ allowed to do what. The relevant method is called
+ <filename>check_can_change_field()</filename>,
+ and is found in <filename>Bug.pm</filename> in your
+ Bugzilla/ directory. If you open that file and search for
+ <quote>sub check_can_change_field</quote>, you'll find it.
+ </para>
+
+ <para>
+ This function has been carefully commented to allow you to see exactly
+ how it works, and give you an idea of how to make changes to it.
+ Certain marked sections should not be changed - these are
+ the <quote>plumbing</quote> which makes the rest of the function work.
+ In between those sections, you'll find snippets of code like:
+ <programlisting> # Allow the assignee to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }</programlisting>
+ It's fairly obvious what this piece of code does.
+ </para>
+
+ <para>
+ So, how does one go about changing this function? Well, simple changes
+ can be made just by removing pieces - for example, if you wanted to
+ prevent any user adding a comment to a bug, just remove the lines marked
+ <quote>Allow anyone to change comments.</quote> If you don't want the
+ Reporter to have any special rights on bugs they have filed, just
+ remove the entire section that deals with the Reporter.
+ </para>
+
+ <para>
+ More complex customizations are not much harder. Basically, you add
+ a check in the right place in the function, i.e. after all the variables
+ you are using have been set up. So, don't look at $ownerid before
+ $ownerid has been obtained from the database. You can either add a
+ positive check, which returns 1 (allow) if certain conditions are true,
+ or a negative check, which returns 0 (deny.) E.g.:
+ <programlisting> if ($field eq "qacontact") {
+ if (Bugzilla->user->groups("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }</programlisting>
+ This says that only users in the group "quality_assurance" can change
+ the QA Contact field of a bug.
+ </para>
+
+ <para>
+ Getting more weird:
+ <programlisting><![CDATA[ if (($field eq "priority") &&
+ (Bugzilla->user->email =~ /.*\@example\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }]]></programlisting>
+ This says that if the user is trying to change the priority field,
+ and their email address is @example.com, they can only do so if the
+ old value of the field was "P1". Not very useful, but illustrative.
+ </para>
+
+ <warning>
+ <para>
+ If you are modifying <filename>process_bug.cgi</filename> in any
+ way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
+ Doing so could compromise security, or cause your installation to
+ stop working entirely.
+ </para>
+ </warning>
+
+ <para>
+ For a list of possible field names, look at the bugs table in the
+ database. If you need help writing custom rules for your organization,
+ ask in the newsgroup.
+ </para>
+ </section>
+
+ <!-- Integrating Bugzilla with Third-Party Tools -->
+ &integration;
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<appendix id="gfdl">
+ <title>GNU Free Documentation License</title>
+
+<!-- - GNU Project - Free Software Foundation (FSF) -->
+<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
+<!-- section>
+ <title>GNU Free Documentation License</title -->
+ <para>Version 1.1, March 2000</para>
+
+ <blockquote>
+ <para>Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place,
+ Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and
+ distribute verbatim copies of this license document, but changing it is
+ not allowed.</para>
+ </blockquote>
+
+ <section label="0" id="gfdl-0">
+ <title>Preamble</title>
+
+ <para>The purpose of this License is to make a manual, textbook, or other
+ written document "free" in the sense of freedom: to assure everyone the
+ effective freedom to copy and redistribute it, with or without modifying
+ it, either commercially or noncommercially. Secondarily, this License
+ preserves for the author and publisher a way to get credit for their
+ work, while not being considered responsible for modifications made by
+ others.</para>
+
+ <para>This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense. It
+ complements the GNU General Public License, which is a copyleft license
+ designed for free software.</para>
+
+ <para>We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a free
+ program should come with manuals providing the same freedoms that the
+ software does. But this License is not limited to software manuals; it
+ can be used for any textual work, regardless of subject matter or whether
+ it is published as a printed book. We recommend this License principally
+ for works whose purpose is instruction or reference.</para>
+ </section>
+
+ <section label="1" id="gfdl-1">
+ <title>Applicability and Definition</title>
+
+ <para>This License applies to any manual or other work that contains a
+ notice placed by the copyright holder saying it can be distributed under
+ the terms of this License. The "Document", below, refers to any such
+ manual or work. Any member of the public is a licensee, and is addressed
+ as "you".</para>
+
+ <para>A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.</para>
+
+ <para>A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall subject
+ (or to related matters) and contains nothing that could fall directly
+ within that overall subject. (For example, if the Document is in part a
+ textbook of mathematics, a Secondary Section may not explain any
+ mathematics.) The relationship could be a matter of historical connection
+ with the subject or with related matters, or of legal, commercial,
+ philosophical, ethical or political position regarding them.</para>
+
+ <para>The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in the
+ notice that says that the Document is released under this License.</para>
+
+ <para>The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
+ that the Document is released under this License.</para>
+
+ <para>A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the general
+ public, whose contents can be viewed and edited directly and
+ straightforwardly with generic text editors or (for images composed of
+ pixels) generic paint programs or (for drawings) some widely available
+ drawing editor, and that is suitable for input to text formatters or for
+ automatic translation to a variety of formats suitable for input to text
+ formatters. A copy made in an otherwise Transparent file format whose
+ markup has been designed to thwart or discourage subsequent modification
+ by readers is not Transparent. A copy that is not "Transparent" is called
+ "Opaque".</para>
+
+ <para>Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format, SGML or
+ XML using a publicly available DTD, and standard-conforming simple HTML
+ designed for human modification. Opaque formats include PostScript, PDF,
+ proprietary formats that can be read and edited only by proprietary word
+ processors, SGML or XML for which the DTD and/or processing tools are not
+ generally available, and the machine-generated HTML produced by some word
+ processors for output purposes only.</para>
+
+ <para>The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the material
+ this License requires to appear in the title page. For works in formats
+ which do not have any title page as such, "Title Page" means the text
+ near the most prominent appearance of the work's title, preceding the
+ beginning of the body of the text.</para>
+ </section>
+
+ <section label="2" id="gfdl-2">
+ <title>Verbatim Copying</title>
+
+ <para>You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License applies to
+ the Document are reproduced in all copies, and that you add no other
+ conditions whatsoever to those of this License. You may not use technical
+ measures to obstruct or control the reading or further copying of the
+ copies you make or distribute. However, you may accept compensation in
+ exchange for copies. If you distribute a large enough number of copies
+ you must also follow the conditions in section 3.</para>
+
+ <para>You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.</para>
+ </section>
+
+ <section label="3" id="gfdl-3">
+ <title>Copying in Quantity</title>
+
+ <para>If you publish printed copies of the Document numbering more than
+ 100, and the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all these
+ Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
+ on the back cover. Both covers must also clearly and legibly identify you
+ as the publisher of these copies. The front cover must present the full
+ title with all words of the title equally prominent and visible. You may
+ add other material on the covers in addition. Copying with changes
+ limited to the covers, as long as they preserve the title of the Document
+ and satisfy these conditions, can be treated as verbatim copying in other
+ respects.</para>
+
+ <para>If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit reasonably)
+ on the actual cover, and continue the rest onto adjacent pages.</para>
+
+ <para>If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a machine-readable
+ Transparent copy along with each Opaque copy, or state in or with each
+ Opaque copy a publicly-accessible computer-network location containing a
+ complete Transparent copy of the Document, free of added material, which
+ the general network-using public has access to download anonymously at no
+ charge using public-standard network protocols. If you use the latter
+ option, you must take reasonably prudent steps, when you begin
+ distribution of Opaque copies in quantity, to ensure that this
+ Transparent copy will remain thus accessible at the stated location until
+ at least one year after the last time you distribute an Opaque copy
+ (directly or through your agents or retailers) of that edition to the
+ public.</para>
+
+ <para>It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of copies, to
+ give them a chance to provide you with an updated version of the
+ Document.</para>
+ </section>
+
+ <section label="4" id="gfdl-4">
+ <title>Modifications</title>
+
+ <para>You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you release
+ the Modified Version under precisely this License, with the Modified
+ Version filling the role of the Document, thus licensing distribution and
+ modification of the Modified Version to whoever possesses a copy of it.
+ In addition, you must do these things in the Modified Version:</para>
+
+ <orderedlist numeration="upperalpha">
+ <listitem>
+ <para>Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the History
+ section of the Document). You may use the same title as a previous
+ version if the original publisher of that version gives
+ permission.</para>
+ </listitem>
+
+ <listitem>
+ <para>List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in the
+ Modified Version, together with at least five of the principal
+ authors of the Document (all of its principal authors, if it has less
+ than five).</para>
+ </listitem>
+
+ <listitem>
+ <para>State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.</para>
+ </listitem>
+
+ <listitem>
+ <para>Preserve all the copyright notices of the Document.</para>
+ </listitem>
+
+ <listitem>
+ <para>Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.</para>
+ </listitem>
+
+ <listitem>
+ <para>Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified Version under
+ the terms of this License, in the form shown in the Addendum
+ below.</para>
+ </listitem>
+
+ <listitem>
+ <para>Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's license
+ notice.</para>
+ </listitem>
+
+ <listitem>
+ <para>Include an unaltered copy of this License.</para>
+ </listitem>
+
+ <listitem>
+ <para>Preserve the section entitled "History", and its title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page. If
+ there is no section entitled "History" in the Document, create one
+ stating the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the Modified
+ Version as stated in the previous sentence.</para>
+ </listitem>
+
+ <listitem>
+ <para>Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and likewise
+ the network locations given in the Document for previous versions it
+ was based on. These may be placed in the "History" section. You may
+ omit a network location for a work that was published at least four
+ years before the Document itself, or if the original publisher of the
+ version it refers to gives permission.</para>
+ </listitem>
+
+ <listitem>
+ <para>In any section entitled "Acknowledgements" or "Dedications",
+ preserve the section's title, and preserve in the section all the
+ substance and tone of each of the contributor acknowledgements and/or
+ dedications given therein.</para>
+ </listitem>
+
+ <listitem>
+ <para>Preserve all the Invariant Sections of the Document, unaltered
+ in their text and in their titles. Section numbers or the equivalent
+ are not considered part of the section titles.</para>
+ </listitem>
+
+ <listitem>
+ <para>Delete any section entitled "Endorsements". Such a section may
+ not be included in the Modified Version.</para>
+ </listitem>
+
+ <listitem>
+ <para>Do not retitle any existing section as "Endorsements" or to
+ conflict in title with any Invariant Section.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no material
+ copied from the Document, you may at your option designate some or all of
+ these sections as invariant. To do this, add their titles to the list of
+ Invariant Sections in the Modified Version's license notice. These titles
+ must be distinct from any other section titles.</para>
+
+ <para>You may add a section entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various parties--for
+ example, statements of peer review or that the text has been approved by
+ an organization as the authoritative definition of a standard.</para>
+
+ <para>You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end of the
+ list of Cover Texts in the Modified Version. Only one passage of
+ Front-Cover Text and one of Back-Cover Text may be added by (or through
+ arrangements made by) any one entity. If the Document already includes a
+ cover text for the same cover, previously added by you or by arrangement
+ made by the same entity you are acting on behalf of, you may not add
+ another; but you may replace the old one, on explicit permission from the
+ previous publisher that added the old one.</para>
+
+ <para>The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to assert
+ or imply endorsement of any Modified Version.</para>
+ </section>
+
+ <section label="5" id="gfdl-5">
+ <title>Combining Documents</title>
+
+ <para>You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for modified
+ versions, provided that you include in the combination all of the
+ Invariant Sections of all of the original documents, unmodified, and list
+ them all as Invariant Sections of your combined work in its license
+ notice.</para>
+
+ <para>The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single copy.
+ If there are multiple Invariant Sections with the same name but different
+ contents, make the title of each such section unique by adding at the end
+ of it, in parentheses, the name of the original author or publisher of
+ that section if known, or else a unique number. Make the same adjustment
+ to the section titles in the list of Invariant Sections in the license
+ notice of the combined work.</para>
+
+ <para>In the combination, you must combine any sections entitled
+ "History" in the various original documents, forming one section entitled
+ "History"; likewise combine any sections entitled "Acknowledgements", and
+ any sections entitled "Dedications". You must delete all sections
+ entitled "Endorsements."</para>
+ </section>
+
+ <section label="6" id="gfdl-6">
+ <title>Collections of Documents</title>
+
+ <para>You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual copies
+ of this License in the various documents with a single copy that is
+ included in the collection, provided that you follow the rules of this
+ License for verbatim copying of each of the documents in all other
+ respects.</para>
+
+ <para>You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert a copy
+ of this License into the extracted document, and follow this License in
+ all other respects regarding verbatim copying of that document.</para>
+ </section>
+
+ <section label="7" id="gfdl-7">
+ <title>Aggregation with Independent Works</title>
+
+ <para>A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of a
+ storage or distribution medium, does not as a whole count as a Modified
+ Version of the Document, provided no compilation copyright is claimed for
+ the compilation. Such a compilation is called an "aggregate", and this
+ License does not apply to the other self-contained works thus compiled
+ with the Document, on account of their being thus compiled, if they are
+ not themselves derivative works of the Document.</para>
+
+ <para>If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one quarter of
+ the entire aggregate, the Document's Cover Texts may be placed on covers
+ that surround only the Document within the aggregate. Otherwise they must
+ appear on covers around the whole aggregate.</para>
+ </section>
+
+ <section label="8" id="gfdl-8">
+ <title>Translation</title>
+
+ <para>Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section 4.
+ Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include translations
+ of some or all Invariant Sections in addition to the original versions of
+ these Invariant Sections. You may include a translation of this License
+ provided that you also include the original English version of this
+ License. In case of a disagreement between the translation and the
+ original English version of this License, the original English version
+ will prevail.</para>
+ </section>
+
+ <section label="9" id="gfdl-9">
+ <title>Termination</title>
+
+ <para>You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided for under this License. Any other attempt to
+ copy, modify, sublicense or distribute the Document is void, and will
+ automatically terminate your rights under this License. However, parties
+ who have received copies, or rights, from you under this License will not
+ have their licenses terminated so long as such parties remain in full
+ compliance.</para>
+ </section>
+
+ <section label="10" id="gfdl-10">
+ <title>Future Revisions of this License</title>
+
+ <para>The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new versions
+ will be similar in spirit to the present version, but may differ in
+ detail to address new problems or concerns. See
+ <ulink url="http://www.gnu.org/copyleft/"/>.</para>
+
+ <para>Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered version of
+ this License "or any later version" applies to it, you have the option of
+ following the terms and conditions either of that specified version or of
+ any later version that has been published (not as a draft) by the Free
+ Software Foundation. If the Document does not specify a version number of
+ this License, you may choose any version ever published (not as a draft)
+ by the Free Software Foundation.</para>
+ </section>
+
+ <section label="" id="gfdl-howto">
+ <title>How to use this License for your documents</title>
+
+ <para>To use this License in a document you have written, include a copy
+ of the License in the document and put the following copyright and
+ license notices just after the title page:</para>
+
+ <blockquote>
+ <para>Copyright (c) YEAR YOUR NAME. Permission is granted to copy,
+ distribute and/or modify this document under the terms of the GNU Free
+ Documentation License, Version 1.1 or any later version published by
+ the Free Software Foundation; with the Invariant Sections being LIST
+ THEIR TITLES, with the Front-Cover Texts being LIST, and with the
+ Back-Cover Texts being LIST. A copy of the license is included in the
+ section entitled "GNU Free Documentation License".</para>
+ </blockquote>
+
+ <para>If you have no Invariant Sections, write "with no Invariant
+ Sections" instead of saying which ones are invariant. If you have no
+ Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover
+ Texts being LIST"; likewise for Back-Cover Texts.</para>
+
+ <para>If your document contains nontrivial examples of program code, we
+ recommend releasing these examples in parallel under your choice of free
+ software license, such as the GNU General Public License, to permit their
+ use in free software.</para>
+ </section>
+</appendix>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
+<glossary id="glossary">
+ <glossdiv>
+ <title>0-9, high ascii</title>
+
+ <glossentry id="gloss-htaccess">
+ <glossterm>.htaccess</glossterm>
+
+ <glossdef>
+ <para>Apache web server, and other NCSA-compliant web servers,
+ observe the convention of using files in directories called
+ <filename>.htaccess</filename>
+
+ to restrict access to certain files. In Bugzilla, they are used
+ to keep secret files which would otherwise
+ compromise your installation - e.g. the
+ <filename>localconfig</filename>
+ file contains the password to your database.
+ curious.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-a">
+ <title>A</title>
+
+ <glossentry id="gloss-apache">
+ <glossterm>Apache</glossterm>
+
+ <glossdef>
+ <para>In this context, Apache is the web server most commonly used
+ for serving up Bugzilla
+ pages. Contrary to popular belief, the apache web server has nothing
+ to do with the ancient and noble Native American tribe, but instead
+ derived its name from the fact that it was
+ <quote>a patchy</quote>
+ version of the original
+ <acronym>NCSA</acronym>
+ world-wide-web server.</para>
+
+ <variablelist>
+ <title>Useful Directives when configuring Bugzilla</title>
+
+ <varlistentry>
+ <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#addhandler">AddHandler</ulink></computeroutput></term>
+ <listitem>
+ <para>Tell Apache that it's OK to run CGI scripts.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#allowoverride">AllowOverride</ulink></computeroutput></term>
+ <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#options">Options</ulink></computeroutput></term>
+ <listitem>
+ <para>These directives are used to tell Apache many things about
+ the directory they apply to. For Bugzilla's purposes, we need
+ them to allow script execution and <filename>.htaccess</filename>
+ overrides.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/mod_dir.html#directoryindex">DirectoryIndex</ulink></computeroutput></term>
+ <listitem>
+ <para>Used to tell Apache what files are indexes. If you can
+ not add <filename>index.cgi</filename> to the list of valid files,
+ you'll need to set <computeroutput>$index_html</computeroutput> to
+ 1 in <filename>localconfig</filename> so
+ <command>./checksetup.pl</command> will create an
+ <filename>index.html</filename> that redirects to
+ <filename>index.cgi</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink></computeroutput></term>
+ <listitem>
+ <para>Used when running Apache on windows so the shebang line
+ doesn't have to be changed in every Bugzilla script.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For more information about how to configure Apache for Bugzilla,
+ see <xref linkend="http-apache"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-b">
+ <title>B</title>
+
+ <glossentry>
+ <glossterm>Bug</glossterm>
+
+ <glossdef>
+ <para>A
+ <quote>bug</quote>
+
+ in Bugzilla refers to an issue entered into the database which has an
+ associated number, assignments, comments, etc. Some also refer to a
+ <quote>tickets</quote>
+ or
+ <quote>issues</quote>;
+ in the context of Bugzilla, they are synonymous.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Bug Number</glossterm>
+
+ <glossdef>
+ <para>Each Bugzilla bug is assigned a number that uniquely identifies
+ that bug. The bug associated with a bug number can be pulled up via a
+ query, or easily from the very front page by typing the number in the
+ "Find" box.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-bugzilla">
+ <glossterm>Bugzilla</glossterm>
+
+ <glossdef>
+ <para>Bugzilla is the world-leading free software bug tracking system.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-c">
+ <title>C</title>
+
+ <glossentry id="gloss-cgi">
+ <glossterm>Common Gateway Interface</glossterm>
+ <acronym>CGI</acronym>
+ <glossdef>
+ <para><acronym>CGI</acronym> is an acronym for Common Gateway Interface. This is
+ a standard for interfacing an external application with a web server. Bugzilla
+ is an example of a <acronym>CGI</acronym> application.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-component">
+ <glossterm>Component</glossterm>
+
+ <glossdef>
+ <para>A Component is a subsection of a Product. It should be a narrow
+ category, tailored to your organization. All Products must contain at
+ least one Component (and, as a matter of fact, creating a Product
+ with no Components will create an error in Bugzilla).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-cpan">
+ <glossterm>Comprehensive Perl Archive Network</glossterm>
+ <acronym>CPAN</acronym>
+
+ <!-- TODO: Rewrite def for CPAN -->
+ <glossdef>
+ <para>
+ <acronym>CPAN</acronym>
+
+ stands for the
+ <quote>Comprehensive Perl Archive Network</quote>.
+ CPAN maintains a large number of extremely useful
+ <glossterm>Perl</glossterm>
+ modules - encapsulated chunks of code for performing a
+ particular task.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-contrib">
+ <glossterm><filename class="directory">contrib</filename></glossterm>
+
+ <glossdef>
+ <para>The <filename class="directory">contrib</filename> directory is
+ a location to put scripts that have been contributed to Bugzilla but
+ are not a part of the official distribution. These scripts are written
+ by third parties and may be in languages other than perl. For those
+ that are in perl, there may be additional modules or other requirements
+ than those of the official distribution.
+ <note>
+ <para>Scripts in the <filename class="directory">contrib</filename>
+ directory are not officially supported by the Bugzilla team and may
+ break in between versions.
+ </para>
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-d">
+ <title>D</title>
+
+ <glossentry id="gloss-daemon">
+ <glossterm>daemon</glossterm>
+
+ <glossdef>
+ <para>A daemon is a computer program which runs in the background. In
+ general, most daemons are started at boot time via System V init
+ scripts, or through RC scripts on BSD-based systems.
+ <glossterm>mysqld</glossterm>,
+ the MySQL server, and
+ <glossterm>apache</glossterm>,
+ a web server, are generally run as daemons.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-dos">
+ <glossterm>DOS Attack</glossterm>
+
+ <glossdef>
+ <para>A DOS, or Denial of Service attack, is when a user attempts to
+ deny access to a web server by repeatedly accessing a page or sending
+ malformed requests to a webserver. A D-DOS, or
+ Distributed Denial of Service attack, is when these requests come
+ from multiple sources at the same time. Unfortunately, these are much
+ more difficult to defend against.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ </glossdiv>
+
+ <glossdiv id="gloss-g">
+ <title>G</title>
+
+ <glossentry id="gloss-groups">
+ <glossterm>Groups</glossterm>
+
+ <glossdef>
+ <para>The word
+ <quote>Groups</quote>
+
+ has a very special meaning to Bugzilla. Bugzilla's main security
+ mechanism comes by placing users in groups, and assigning those
+ groups certain privileges to view bugs in particular
+ <glossterm>Products</glossterm>
+ in the
+ <glossterm>Bugzilla</glossterm>
+ database.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-j">
+ <title>J</title>
+
+ <glossentry id="gloss-javascript">
+ <glossterm>JavaScript</glossterm>
+ <glossdef>
+ <para>JavaScript is cool, we should talk about it.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-m">
+ <title>M</title>
+
+ <glossentry id="gloss-mta">
+ <glossterm>Message Transport Agent</glossterm>
+ <acronym>MTA</acronym>
+
+ <glossdef>
+ <para>A Message Transport Agent is used to control the flow of email on a system.
+ The <ulink url="http://search.cpan.org/dist/Email-Send/lib/Email/Send.pm">Email::Send</ulink>
+ Perl module, which Bugzilla uses to send email, can be configured to
+ use many different underlying implementations for actually sending the
+ mail using the <option>mail_delivery_method</option> parameter.
+ Implementations other than <literal>sendmail</literal> require that the
+ <option>sendmailnow</option> param be set to <literal>on</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-mysql">
+ <glossterm>MySQL</glossterm>
+
+ <glossdef>
+ <para>MySQL is currently the required
+ <glossterm linkend="gloss-rdbms">RDBMS</glossterm> for Bugzilla. MySQL
+ can be downloaded from <ulink url="http://www.mysql.com"/>. While you
+ should familiarize yourself with all of the documentation, some high
+ points are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><ulink url="http://www.mysql.com/doc/en/Backup.html">Backup</ulink></term>
+ <listitem>
+ <para>Methods for backing up your Bugzilla database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://www.mysql.com/doc/en/Option_files.html">Option Files</ulink></term>
+ <listitem>
+ <para>Information about how to configure MySQL using
+ <filename>my.cnf</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://www.mysql.com/doc/en/Privilege_system.html">Privilege System</ulink></term>
+ <listitem>
+ <para>Much more detailed information about the suggestions in
+ <xref linkend="security-mysql"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-p">
+ <title>P</title>
+
+ <glossentry id="gloss-ppm">
+ <glossterm>Perl Package Manager</glossterm>
+ <acronym>PPM</acronym>
+
+ <glossdef>
+ <para><ulink url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/"/>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm id="gloss-product">Product</glossterm>
+
+ <glossdef>
+ <para>A Product is a broad category of types of bugs, normally
+ representing a single piece of software or entity. In general,
+ there are several Components to a Product. A Product may define a
+ group (used for security) for all bugs entered into
+ its Components.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Perl</glossterm>
+
+ <glossdef>
+ <para>First written by Larry Wall, Perl is a remarkable program
+ language. It has the benefits of the flexibility of an interpreted
+ scripting language (such as shell script), combined with the speed
+ and power of a compiled language, such as C.
+ <glossterm>Bugzilla</glossterm>
+
+ is maintained in Perl.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-q">
+ <title>Q</title>
+
+ <glossentry>
+ <glossterm>QA</glossterm>
+
+ <glossdef>
+ <para>
+ <quote>QA</quote>,
+ <quote>Q/A</quote>, and
+ <quote>Q.A.</quote>
+ are short for
+ <quote>Quality Assurance</quote>.
+ In most large software development organizations, there is a team
+ devoted to ensuring the product meets minimum standards before
+ shipping. This team will also generally want to track the progress of
+ bugs over their life cycle, thus the need for the
+ <quote>QA Contact</quote>
+
+ field in a bug.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-r">
+ <title>R</title>
+
+ <glossentry id="gloss-rdbms">
+ <glossterm>Relational DataBase Management System</glossterm>
+ <acronym>RDBMS</acronym>
+
+ <glossdef>
+ <para>A relational database management system is a database system
+ that stores information in tables that are related to each other.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-regexp">
+ <glossterm>Regular Expression</glossterm>
+ <acronym>regexp</acronym>
+
+ <glossdef>
+ <para>A regular expression is an expression used for pattern matching.
+ <ulink url="http://perldoc.com/perl5.6/pod/perlre.html#Regular-Expressions">Documentation</ulink>
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-s">
+ <title>S</title>
+
+ <glossentry id="gloss-service">
+ <glossterm>Service</glossterm>
+
+ <glossdef>
+ <para>In Windows NT environment, a boot-time background application
+ is referred to as a service. These are generally managed through the
+ control panel while logged in as an account with
+ <quote>Administrator</quote> level capabilities. For more
+ information, consult your Windows manual or the MSKB.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>
+ <acronym>SGML</acronym>
+ </glossterm>
+
+ <glossdef>
+ <para>
+ <acronym>SGML</acronym>
+
+ stands for
+ <quote>Standard Generalized Markup Language</quote>.
+ Created in the 1980's to provide an extensible means to maintain
+ documentation based upon content instead of presentation,
+ <acronym>SGML</acronym>
+
+ has withstood the test of time as a robust, powerful language.
+ <glossterm>
+ <acronym>XML</acronym>
+ </glossterm>
+
+ is the
+ <quote>baby brother</quote>
+
+ of SGML; any valid
+ <acronym>XML</acronym>
+
+ document it, by definition, a valid
+ <acronym>SGML</acronym>
+
+ document. The document you are reading is written and maintained in
+ <acronym>SGML</acronym>,
+ and is also valid
+ <acronym>XML</acronym>
+
+ if you modify the Document Type Definition.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-t">
+ <title>T</title>
+
+ <glossentry id="gloss-target-milestone" xreflabel="Target Milestone">
+ <glossterm>Target Milestone</glossterm>
+
+ <glossdef>
+ <para>Target Milestones are Product goals. They are configurable on a
+ per-Product basis. Most software development houses have a concept of
+
+ <quote>milestones</quote>
+
+ where the people funding a project expect certain functionality on
+ certain dates. Bugzilla facilitates meeting these milestones by
+ giving you the ability to declare by which milestone a bug will be
+ fixed, or an enhancement will be implemented.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="gloss-tcl">
+ <glossterm>Tool Command Language</glossterm>
+ <acronym>TCL</acronym>
+ <glossdef>
+ <para>TCL is an open source scripting language available for Windows,
+ Macintosh, and Unix based systems. Bugzilla 1.0 was written in TCL but
+ never released. The first release of Bugzilla was 2.0, which was when
+ it was ported to perl.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+
+ <glossdiv id="gloss-z">
+ <title>Z</title>
+
+ <glossentry id="gloss-zarro">
+ <glossterm>Zarro Boogs Found</glossterm>
+
+ <glossdef>
+ <para>This is just a goofy way of saying that there were no bugs
+ found matching your query. When asked to explain this message,
+ Terry had the following to say:
+ </para>
+
+ <blockquote>
+ <attribution>Terry Weissman</attribution>
+ <para>I've been asked to explain this ... way back when, when
+ Netscape released version 4.0 of its browser, we had a release
+ party. Naturally, there had been a big push to try and fix every
+ known bug before the release. Naturally, that hadn't actually
+ happened. (This is not unique to Netscape or to 4.0; the same thing
+ has happened with every software project I've ever seen.) Anyway,
+ at the release party, T-shirts were handed out that said something
+ like "Netscape 4.0: Zarro Boogs". Just like the software, the
+ T-shirt had no known bugs. Uh-huh.
+ </para>
+
+ <para>So, when you query for a list of bugs, and it gets no results,
+ you can think of this as a friendly reminder. Of *course* there are
+ bugs matching your query, they just aren't in the bugsystem yet...
+ </para>
+ </blockquote>
+
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+</glossary>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
--- /dev/null
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!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>
+
+ <section id="installation">
+ <title>Installation</title>
+
+ <note>
+ <para>If you just want to <emphasis>use</emphasis> Bugzilla,
+ you do not need to install it. None of this chapter is relevant to
+ you. Ask your Bugzilla administrator for the URL to access it from
+ your web browser.
+ </para>
+ </note>
+
+ <para>The Bugzilla server software is usually installed on Linux or
+ Solaris.
+ If you are installing on another OS, check <xref linkend="os-specific"/>
+ before you start your installation to see if there are any special
+ instructions.
+ </para>
+
+ <para>
+ As an alternative to following these instructions, you may wish to
+ try Arne Schirmacher's unofficial and unsupported
+ <ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla
+ Installer</ulink>, which installs Bugzilla and all its prerequisites
+ on Linux or Solaris systems.
+ </para>
+
+ <para>This guide assumes that you have administrative access to the
+ Bugzilla machine. It not possible to
+ install and run Bugzilla itself without administrative access except
+ in the very unlikely event that every single prerequisite is
+ already installed.
+ </para>
+
+ <warning>
+ <para>The installation process may make your machine insecure for
+ short periods of time. Make sure there is a firewall between you
+ and the Internet.
+ </para>
+ </warning>
+
+ <para>
+ You are strongly recommended to make a backup of your system
+ before installing Bugzilla (and at regular intervals thereafter :-).
+ </para>
+
+ <para>In outline, the installation proceeds as follows:
+ </para>
+
+ <procedure>
+ <step>
+ <para><link linkend="install-perl">Install Perl</link>
+ (&min-perl-ver; or above)
+ </para>
+ </step>
+ <step>
+ <para><link linkend="install-database">Install a Database Engine</link>
+ </para>
+ </step>
+ <step>
+ <para><link linkend="install-webserver">Install a Webserver</link>
+ </para>
+ </step>
+ <step>
+ <para><link linkend="install-bzfiles">Install Bugzilla</link>
+ </para>
+ </step>
+ <step>
+ <para><link linkend="install-perlmodules">Install Perl modules</link>
+ </para>
+ </step>
+ <step>
+ <para>
+ <link linkend="install-MTA">Install a Mail Transfer Agent</link>
+ (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version)
+ </para>
+ </step>
+ <step>
+ <para>Configure all of the above.
+ </para>
+ </step>
+ </procedure>
+
+ <section id="install-perl">
+ <title>Perl</title>
+
+ <para>Installed Version Test: <filename>perl -v</filename></para>
+
+ <para>Any machine that doesn't have Perl on it is a sad machine indeed.
+ If you don't have it and your OS doesn't provide official packages,
+ visit <ulink url="http://www.perl.com"/>.
+ Although Bugzilla runs with Perl &min-perl-ver;,
+ it's a good idea to be using the latest stable version.
+ </para>
+ </section>
+
+ <section id="install-database">
+ <title>Database Engine</title>
+
+ <para>From Bugzilla 2.20, support is included for using both the MySQL and
+ PostgreSQL database servers. You only require one of these systems to make
+ use of Bugzilla.</para>
+
+ <section id="install-mysql">
+ <title>MySQL</title>
+ <para>Installed Version Test: <filename>mysql -V</filename></para>
+
+ <para>
+ If you don't have it and your OS doesn't provide official packages,
+ visit <ulink url="http://www.mysql.com"/>. You need MySQL version
+ &min-mysql-ver; or higher.
+ </para>
+
+ <note>
+ <para> Many of the binary
+ versions of MySQL store their data files in
+ <filename class="directory">/var</filename>.
+ On some Unix systems, this is part of a smaller root partition,
+ and may not have room for your bug database. To change the data
+ directory, you have to build MySQL from source yourself, and
+ set it as an option to <filename>configure</filename>.</para>
+ </note>
+
+ <para>If you install from something other than a packaging/installation
+ system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
+ (Windows Executable), or .msi (Microsoft Installer), make sure the MySQL
+ server is started when the machine boots.
+ </para>
+ </section>
+
+ <section id="install-pg">
+ <title>PostgreSQL</title>
+ <para>Installed Version Test: <filename>psql -V</filename></para>
+
+ <para>
+ If you don't have it and your OS doesn't provide official packages,
+ visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL
+ version &min-pg-ver; or higher.
+ </para>
+
+ <para>If you install from something other than a packaging/installation
+ system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
+ (Windows Executable), or .msi (Microsoft Installer), make sure the
+ PostgreSQL server is started when the machine boots.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="install-webserver">
+ <title>Web Server</title>
+
+ <para>Installed Version Test: view the default welcome page at
+ http://<your-machine>/</para>
+
+ <para>You have freedom of choice here, pretty much any web server that
+ is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
+ scripts will work.
+ However, we strongly recommend using the Apache web server
+ (either 1.3.x or 2.x), and
+ the installation instructions usually assume you are
+ using it. If you have got Bugzilla working using another web server,
+ please share your experiences with us by filing a bug in &bzg-bugs;.
+ </para>
+
+ <para>
+ If you don't have Apache and your OS doesn't provide official packages,
+ visit <ulink url="http://httpd.apache.org/"/>.
+ </para>
+
+ </section>
+
+ <section id="install-bzfiles">
+ <title>Bugzilla</title>
+
+ <para>
+ Download a Bugzilla tarball (or check it out from CVS) and place
+ it in a suitable directory, accessible by the default web server user
+ (probably <quote>apache</quote> or <quote>www</quote>).
+ Good locations are either directly in the web server's document directories or
+ in <filename>/usr/local</filename> with a symbolic link to the web server's
+ document directories or an alias in the web server's configuration.
+ </para>
+
+ <caution>
+ <para>The default Bugzilla distribution is NOT designed to be placed
+ in a <filename class="directory">cgi-bin</filename> directory. This
+ includes any directory which is configured using the
+ <option>ScriptAlias</option> directive of Apache.
+ </para>
+ </caution>
+
+ <para>Once all the files are in a web accessible directory, make that
+ directory writable by your web server's user. This is a temporary step
+ until you run the
+ <filename>checksetup.pl</filename>
+ script, which locks down your installation.</para>
+ </section>
+
+ <section id="install-perlmodules">
+ <title>Perl Modules</title>
+
+ <para>Bugzilla's installation process is based
+ on a script called <filename>checksetup.pl</filename>.
+ The first thing it checks is whether you have appropriate
+ versions of all the required
+ Perl modules. The aim of this section is to pass this check.
+ When it passes, proceed to <xref linkend="configuration"/>.
+ </para>
+
+ <para>
+ At this point, you need to <filename>su</filename> to root. You should
+ remain as root until the end of the install. To check you have the
+ required modules, run:
+ </para>
+
+ <screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen>
+
+ <para>
+ <filename>checksetup.pl</filename> will print out a list of the
+ required and optional Perl modules, together with the versions
+ (if any) installed on your machine.
+ The list of required modules is reasonably long; however, you
+ may already have several of them installed.
+ </para>
+
+ <para>
+ There is a meta-module called Bundle::Bugzilla,
+ which installs all the other
+ modules with a single command. You should use this if you are running
+ Perl 5.6.1 or above.
+ </para>
+
+ <para>
+ The preferred way of installing Perl modules is via CPAN on Unix,
+ or PPM on Windows (see <xref linkend="win32-perl-modules"/>). These
+ instructions assume you are using CPAN; if for some reason you need
+ to install the Perl modules manually, see
+ <xref linkend="install-perlmodules-manual"/>.
+ </para>
+
+ <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'</screen>
+
+ <para>
+ If you using Bundle::Bugzilla, invoke the magic CPAN command on it.
+ Otherwise, you need to work down the
+ list of modules that <filename>checksetup.pl</filename> says are
+ required, in the order given, invoking the command on each.
+ </para>
+
+ <tip>
+ <para>Many people complain that Perl modules will not install for
+ them. Most times, the error messages complain that they are missing a
+ file in
+ <quote>@INC</quote>.
+ Virtually every time, this error is due to permissions being set too
+ restrictively for you to compile Perl modules or not having the
+ necessary Perl development libraries installed on your system.
+ Consult your local UNIX systems administrator for help solving these
+ permissions issues; if you
+ <emphasis>are</emphasis>
+ the local UNIX sysadmin, please consult the newsgroup/mailing list
+ for further assistance or hire someone to help you out.</para>
+ </tip>
+
+ <note>
+ <para>If you are using a package-based system, and attempting to install the
+ Perl modules from CPAN, you may need to install the "development" packages for
+ MySQL and GD before attempting to install the related Perl modules. The names of
+ these packages will vary depending on the specific distribution you are using,
+ but are often called <filename><packagename>-devel</filename>.</para>
+ </note>
+
+ <para>
+ Here is a complete list of modules and their minimum versions.
+ Some modules have special installation notes, which follow.
+ </para>
+
+ <para>Required Perl modules:
+ <orderedlist>
+
+ <listitem>
+ <para>
+ CGI &min-cgi-ver; or CGI &min-mp-cgi-ver; if using mod_perl
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Date::Format (&min-date-format-ver;)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ DBI (&min-dbi-ver;)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-dbd-mysql">DBD::mysql</link>
+ (&min-dbd-mysql-ver;) if using MySQL
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ File::Spec (&min-file-spec-ver;)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-template">Template</link>
+ (&min-template-ver;)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Email::Send (&min-email-send-ver;)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Email::MIME::Modifier (&min-email-mime-modifier-ver;)
+ </para>
+ </listitem>
+ </orderedlist>
+
+ Optional Perl modules:
+ <orderedlist>
+ <listitem>
+ <para>
+ <link linkend="install-modules-gd">GD</link>
+ (&min-gd-ver;) for bug charting
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Template::Plugin::GD::Image
+ (&min-gd-ver;) for Graphical Reports
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-chart-base">Chart::Base</link>
+ (&min-chart-base-ver;) for bug charting
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-gd-graph">GD::Graph</link>
+ (&min-gd-graph-ver;) for bug charting
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-gd-text">GD::Text</link>
+ (&min-gd-text-ver;) for bug charting
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-xml-twig">XML::Twig</link>
+ (&min-xml-twig-ver;) for bug import/export
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ MIME::Parser (&min-mime-parser-ver;) for bug import/export
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LWP::UserAgent
+ (&min-lwp-useragent-ver;) for Automatic Update Notifications
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-patchreader">PatchReader</link>
+ (&min-patchreader-ver;) for pretty HTML view of patches
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Image::Magick (&min-image-magick-ver;) for converting BMP image attachments to PNG
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Net::LDAP
+ (&min-net-ldap-ver;) for LDAP Authentication
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Authen::Radius
+ (&min-authen-radius-ver;) for RADIUS Authentication
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="install-modules-soap-lite">SOAP::Lite</link>
+ (&min-soap-lite-ver;) for the web service interface
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ HTML::Parser
+ (&min-html-parser-ver;) for More HTML in Product/Group Descriptions
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ HTML::Scrubber
+ (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Email::MIME::Attachment::Stripper
+ (&min-email-mime-attachment-stripper-ver;) for Inbound Email
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Email::Reply
+ (&min-email-reply-ver;) for Inbound Email
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ mod_perl2
+ (&min-mod_perl2-ver;) for mod_perl
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ CGI
+ (&min-cgi-ver;) for mod_perl
+ </para>
+ </listitem>
+
+ </orderedlist>
+ </para>
+
+ <section id="install-modules-dbd-mysql">
+ <title>DBD::mysql</title>
+
+ <para>The installation process will ask you a few questions about the
+ desired compilation target and your MySQL installation. For most of the
+ questions the provided default will be adequate, but when asked if your
+ desired target is the MySQL or mSQL packages, you should
+ select the MySQL-related ones. Later you will be asked if you wish to
+ provide backwards compatibility with the older MySQL packages; you
+ should answer YES to this question. The default is NO.</para>
+
+ <para>A host of 'localhost' should be fine. A testing user of 'test',
+ with a null password, should have sufficient access to run
+ tests on the 'test' database which MySQL creates upon installation.
+ </para>
+ </section>
+
+ <section id="install-modules-template">
+ <title>Template Toolkit (&min-template-ver;)</title>
+
+ <para>When you install Template Toolkit, you'll get asked various
+ questions about features to enable. The defaults are fine, except
+ that it is recommended you use the high speed XS Stash of the Template
+ Toolkit, in order to achieve best performance.
+ </para>
+ </section>
+
+ <section id="install-modules-gd">
+ <title>GD (&min-gd-ver;)</title>
+
+ <para>The GD module is only required if you want graphical reports.
+ </para>
+
+ <note>
+ <para>The Perl GD module requires some other libraries that may or
+ may not be installed on your system, including
+ <classname>libpng</classname>
+ and
+ <classname>libgd</classname>.
+ The full requirements are listed in the Perl GD module README.
+ If compiling GD fails, it's probably because you're
+ missing a required library.</para>
+ </note>
+
+ <tip>
+ <para>The version of the GD module you need is very closely tied
+ to the <classname>libgd</classname> version installed on your system.
+ If you have a version 1.x of <classname>libgd</classname> the 2.x
+ versions of the GD module won't work for you.
+ </para>
+ </tip>
+ </section>
+
+ <section id="install-modules-chart-base">
+ <title>Chart::Base (&min-chart-base-ver;)</title>
+
+ <para>The Chart::Base module is only required if you want graphical
+ reports.
+ Note that earlier versions that 0.99c used GIFs, which are no longer
+ supported by the latest versions of GD.</para>
+ </section>
+
+ <section id="install-modules-gd-graph">
+ <title>GD::Graph (&min-gd-graph-ver;)</title>
+
+ <para>The GD::Graph module is only required if you want graphical
+ reports.
+ </para>
+ </section>
+
+ <section id="install-modules-gd-text">
+ <title>GD::Text (&min-gd-text-ver;)</title>
+
+ <para>The GD::Text module is only required if you want graphical
+ reports.
+ </para>
+ </section>
+
+ <section id="install-modules-xml-twig">
+ <title>XML::Twig (&min-xml-twig-ver;)</title>
+
+ <para>The XML::Twig module is only required if you want to import
+ XML bugs using the <filename>importxml.pl</filename>
+ script. This is required to use Bugzilla's "move bugs" feature;
+ you may also want to use it for migrating from another bug database.
+ </para>
+ </section>
+
+ <section id="install-modules-soap-lite">
+ <title>SOAP::Lite (&min-soap-lite-ver;)</title>
+ <para>Installing SOAP::Lite enables your Bugzilla installation to be
+ accessible at a standardized Web Service interface (SOAP/XML-RPC)
+ by third-party applications via HTTP(S).
+ </para>
+ </section>
+
+ <section id="install-modules-patchreader">
+ <title>PatchReader (&min-patchreader-ver;)</title>
+
+ <para>The PatchReader module is only required if you want to use
+ Patch Viewer, a
+ Bugzilla feature to show code patches in your web browser in a more
+ readable form.
+ </para>
+ </section>
+ </section>
+ <section id="install-MTA">
+ <title>Mail Transfer Agent (MTA)</title>
+
+ <para>
+ Bugzilla is dependent on the availability of an e-mail system for its
+ user authentication and for other tasks.
+ </para>
+
+ <note>
+ <para>
+ This is not entirely true. It is possible to completely disable
+ email sending, or to have Bugzilla store email messages in a
+ file instead of sending them. However, this is mainly intended
+ for testing, as disabling or diverting email on a production
+ machine would mean that users could miss important events (such
+ as bug changes or the creation of new accounts).
+ </para>
+
+ <para>
+ For more information, see the <quote>mail_delivery_method</quote> parameter
+ in <xref linkend="parameters" />.
+ </para>
+ </note>
+
+ <para>
+ On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
+ suffice. Sendmail, Postfix, qmail and Exim are examples of common
+ MTAs. Sendmail is the original Unix MTA, but the others are easier to
+ configure, and therefore many people replace Sendmail with Postfix or
+ Exim. They are drop-in replacements, so Bugzilla will not
+ distinguish between them.
+ </para>
+
+ <para>
+ If you are using Sendmail, version 8.7 or higher is required.
+ If you are using a Sendmail-compatible MTA, it must be congruent with
+ at least version 8.7 of Sendmail.
+ </para>
+
+ <para>
+ Consult the manual for the specific MTA you choose for detailed
+ installation instructions. Each of these programs will have their own
+ configuration files where you must configure certain parameters to
+ ensure that the mail is delivered properly. They are implemented
+ as services, and you should ensure that the MTA is in the auto-start
+ list of services for the machine.
+ </para>
+
+ <para>
+ If a simple mail sent with the command-line 'mail' program
+ succeeds, then Bugzilla should also be fine.
+ </para>
+
+ </section>
+ <section id="using-mod_perl-with-bugzilla">
+ <title>Installing Bugzilla on mod_perl</title>
+ <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on
+ Apache. <literal>mod_perl</literal> has some additional requirements to that of running
+ Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para>
+
+ <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be
+ obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires
+ version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para>
+
+ <para>Bugzilla also requires a more up-to-date version of the CGI
+ perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver;
+ </para>
+ </section>
+ </section>
+
+ <section id="configuration">
+ <title>Configuration</title>
+
+ <warning>
+ <para>
+ Poorly-configured MySQL and Bugzilla installations have
+ given attackers full access to systems in the past. Please take the
+ security parts of these guidelines seriously, even for Bugzilla
+ machines hidden away behind your firewall. Be certain to read
+ <xref linkend="security"/> for some important security tips.
+ </para>
+ </warning>
+
+ <section id="localconfig">
+ <title>localconfig</title>
+
+ <para>
+ You should now run <filename>checksetup.pl</filename> again, this time
+ without the <literal>--check-modules</literal> switch.
+ </para>
+ <screen><prompt>bash#</prompt> ./checksetup.pl</screen>
+ <para>
+ This time, <filename>checksetup.pl</filename> should tell you that all
+ the correct modules are installed and will display a message about, and
+ write out a file called, <filename>localconfig</filename>. This file
+ contains the default settings for a number of Bugzilla parameters.
+ </para>
+
+ <para>
+ Load this file in your editor. The only value you
+ <emphasis>need</emphasis> to change is $db_pass, the password for
+ the user you will create for your database. Pick a strong
+ password (for simplicity, it should not contain single quote
+ characters) and put it here.
+ </para>
+
+ <para>
+ You may need to change the value of
+ <emphasis>webservergroup</emphasis> if your web server does not
+ run in the "apache" group. On Debian, for example, Apache runs in
+ the "www-data" group. If you are going to run Bugzilla on a
+ machine where you do not have root access (such as on a shared web
+ hosting account), you will need to leave
+ <emphasis>webservergroup</emphasis> empty, ignoring the warnings
+ that <filename>checksetup.pl</filename> will subsequently display
+ every time it is run.
+ </para>
+
+ <caution>
+ <para>
+ If you are using suexec, you should use your own primary group
+ for <emphasis>webservergroup</emphasis> rather than leaving it
+ empty, and see the additional directions in the suexec section
+ <xref linkend="suexec" />.
+ </para>
+ </caution>
+
+ <para>
+ The other options in the <filename>localconfig</filename> file
+ are documented by their accompanying comments. If you have a slightly
+ non-standard MySQL setup, you may wish to change one or more of
+ the other "$db_*" parameters.
+ </para>
+
+ <para>
+ You may also wish to change the names of
+ the priorities, severities, operating systems and platforms for your
+ installation. However, you can always change these after installation
+ has finished; if you then re-run <filename>checksetup.pl</filename>,
+ the changes will get picked up.
+ </para>
+ </section>
+
+ <section id="database-engine">
+ <title>Database Server</title>
+ <para>
+ This section deals with configuring your database server for use
+ with Bugzilla. Currently, MySQL (<xref linkend="mysql"/>) and
+ PostgreSQL (<xref linkend="postgresql"/>) are available.
+ </para>
+
+ <section id="database-schema">
+ <title>Bugzilla Database Schema</title>
+
+ <para>
+ The Bugzilla database schema is available at
+ <ulink url="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">Ravenbrook</ulink>.
+ This very valuable tool can generate a written description of
+ the Bugzilla database schema for any version of Bugzilla. It
+ can also generate a diff between two versions to help someone
+ see what has changed.
+ </para>
+ </section>
+
+ <section id="mysql">
+ <title>MySQL</title>
+
+ <caution>
+ <para>
+ MySQL's default configuration is very insecure.
+ <xref linkend="security-mysql"/> has some good information for
+ improving your installation's security.
+ </para>
+ </caution>
+
+ <section id="install-setupdatabase">
+ <title>Allow large attachments</title>
+
+ <para>
+ By default, MySQL will only accept packets up to 64Kb in size.
+ If you want to have attachments larger than this, you will need
+ to modify your <filename>/etc/my.cnf</filename> as below.
+ </para>
+
+ <screen> [mysqld]
+ # Allow packets up to 1M
+ max_allowed_packet=1M</screen>
+
+ <para>
+ There is also a parameter in Bugzilla called 'maxattachmentsize'
+ (default = 1000 Kb) that controls the maximum allowable attachment
+ size. Attachments larger than <emphasis>either</emphasis> the
+ 'max_allowed_packet' or 'maxattachmentsize' value will not be
+ accepted by Bugzilla.
+ </para>
+
+ <note>
+ <para>
+ This does not affect Big Files, attachments that are stored directly
+ on disk instead of in the database. Their maximum size is
+ controlled using the 'maxlocalattachment' parameter.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Allow small words in full-text indexes</title>
+
+ <para>By default, words must be at least four characters in length
+ in order to be indexed by MySQL's full-text indexes. This causes
+ a lot of Bugzilla specific words to be missed, including "cc",
+ "ftp" and "uri".</para>
+
+ <para>MySQL can be configured to index those words by setting the
+ ft_min_word_len param to the minimum size of the words to index.
+ This can be done by modifying the <filename>/etc/my.cnf</filename>
+ according to the example below:</para>
+
+ <screen> [mysqld]
+ # Allow small words in full-text indexes
+ ft_min_word_len=2</screen>
+
+ <para>Rebuilding the indexes can be done based on documentation found at
+ <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
+ </para>
+ </section>
+
+ <section id="install-setupdatabase-adduser">
+ <title>Add a user to MySQL</title>
+
+ <para>
+ You need to add a new MySQL user for Bugzilla to use.
+ (It's not safe to have Bugzilla use the MySQL root account.)
+ The following instructions assume the defaults in
+ <filename>localconfig</filename>; if you changed those,
+ you need to modify the SQL command appropriately. You will
+ need the <replaceable>$db_pass</replaceable> password you
+ set in <filename>localconfig</filename> in
+ <xref linkend="localconfig"/>.
+ </para>
+
+ <para>
+ We use an SQL <command>GRANT</command> command to create
+ a <quote>bugs</quote> user. This also restricts the
+ <quote>bugs</quote>user to operations within a database
+ called <quote>bugs</quote>, and only allows the account
+ to connect from <quote>localhost</quote>. Modify it to
+ reflect your setup if you will be connecting from another
+ machine or as a different user.
+ </para>
+
+ <para>
+ Run the <filename>mysql</filename> command-line client and enter:
+ </para>
+
+ <screen> <prompt>mysql></prompt> GRANT SELECT, INSERT,
+ UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
+ CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
+ TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
+ <prompt>mysql></prompt> FLUSH PRIVILEGES;</screen>
+
+ </section>
+
+ <section>
+ <title>Permit attachments table to grow beyond 4GB</title>
+
+ <para>
+ By default, MySQL will limit the size of a table to 4GB.
+ This limit is present even if the underlying filesystem
+ has no such limit. To set a higher limit, follow these
+ instructions.
+ </para>
+
+ <para>
+ After you have completed the rest of the installation (or at least the
+ database setup parts), you should run the <filename>MySQL</filename>
+ command-line client and enter the following, replacing <literal>$bugs_db</literal>
+ with your Bugzilla database name (<emphasis>bugs</emphasis> by default):
+ </para>
+
+ <screen>
+ <prompt>mysql></prompt> use <replaceable>$bugs_db</replaceable>
+ <prompt>mysql></prompt> ALTER TABLE attachments
+ AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
+ </screen>
+
+ <para>
+ The above command will change the limit to 20GB. Mysql will have
+ to make a temporary copy of your entire table to do this. Ideally,
+ you should do this when your attachments table is still small.
+ </para>
+
+ <note>
+ <para>
+ This does not affect Big Files, attachments that are stored directly
+ on disk instead of in the database.
+ </para>
+ </note>
+ </section>
+ </section>
+
+ <section id="postgresql">
+ <title>PostgreSQL</title>
+ <section>
+ <title>Add a User to PostgreSQL</title>
+
+ <para>You need to add a new user to PostgreSQL for the Bugzilla
+ application to use when accessing the database. The following instructions
+ assume the defaults in <filename>localconfig</filename>; if you
+ changed those, you need to modify the commands appropriately. You will
+ need the <replaceable>$db_pass</replaceable> password you
+ set in <filename>localconfig</filename> in
+ <xref linkend="localconfig"/>.</para>
+
+ <para>On most systems, to create the user in PostgreSQL, you will need to
+ login as the root user, and then</para>
+
+ <screen> <prompt>bash#</prompt> su - postgres</screen>
+
+ <para>As the postgres user, you then need to create a new user: </para>
+
+ <screen> <prompt>bash$</prompt> createuser -U postgres -dAP bugs</screen>
+
+ <para>When asked for a password, provide the password which will be set as
+ <replaceable>$db_pass</replaceable> in <filename>localconfig</filename>.
+ The created user will have the ability to create databases and will not be
+ able to create new users.</para>
+ </section>
+
+ <section>
+ <title>Configure PostgreSQL</title>
+
+ <para>Now, you will need to edit <filename>pg_hba.conf</filename> which is
+ usually located in <filename>/var/lib/pgsql/data/</filename>. In this file,
+ you will need to add a new line to it as follows:</para>
+
+ <para>
+ <computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput>
+ </para>
+
+ <para>This means that for TCP/IP (host) connections, allow connections from
+ '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use
+ password authentication (md5) for that user.</para>
+
+ <para>Now, you will need to restart PostgreSQL, but you will need to fully
+ stop and start the server rather than just restarting due to the possibility
+ of a change to <filename>postgresql.conf</filename>. After the server has
+ restarted, you will need to edit <filename>localconfig</filename>, finding
+ the <literal>$db_driver</literal> variable and setting it to
+ <literal>Pg</literal> and changing the password in <literal>$db_pass</literal>
+ to the one you picked previously, while setting up the account.</para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>checksetup.pl</title>
+
+ <para>
+ Next, rerun <filename>checksetup.pl</filename>. It reconfirms
+ that all the modules are present, and notices the altered
+ localconfig file, which it assumes you have edited to your
+ satisfaction. It compiles the UI templates,
+ connects to the database using the 'bugs'
+ user you created and the password you defined, and creates the
+ 'bugs' database and the tables therein.
+ </para>
+
+ <para>
+ After that, it asks for details of an administrator account. Bugzilla
+ can have multiple administrators - you can create more later - but
+ it needs one to start off with.
+ Enter the email address of an administrator, his or her full name,
+ and a suitable Bugzilla password.
+ </para>
+
+ <para>
+ <filename>checksetup.pl</filename> will then finish. You may rerun
+ <filename>checksetup.pl</filename> at any time if you wish.
+ </para>
+ </section>
+
+
+ <section id="http">
+ <title>Web server</title>
+ <para>
+ Configure your web server according to the instructions in the
+ appropriate section. (If it makes a difference in your choice,
+ the Bugzilla Team recommends Apache.) To check whether your web server
+ is correctly configured, try to access <filename>testagent.cgi</filename>
+ from your web server. If "OK" is displayed, then your configuration
+ is successful. Regardless of which web server
+ you are using, however, ensure that sensitive information is
+ not remotely available by properly applying the access controls in
+ <xref linkend="security-webserver-access"/>. You can run
+ <filename>testserver.pl</filename> to check if your web server serves
+ Bugzilla files as expected.
+ </para>
+
+ <section id="http-apache">
+ <title>Bugzilla using Apache</title>
+ <para>You have two options for running Bugzilla under Apache -
+ <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and
+ <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla
+ 2.23)
+ </para>
+ <section id="http-apache-mod_cgi">
+ <title>Apache <productname>httpd</productname> with mod_cgi</title>
+
+ <para>
+ To configure your Apache web server to work with Bugzilla while using
+ mod_cgi, do the following:
+ </para>
+
+ <procedure>
+ <step>
+ <para>
+ Load <filename>httpd.conf</filename> in your editor.
+ In Fedora and Red Hat Linux, this file is found in
+ <filename class="directory">/etc/httpd/conf</filename>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Apache uses <computeroutput><Directory></computeroutput>
+ directives to permit fine-grained permission setting. Add the
+ following lines to a directive that applies to the location
+ of your Bugzilla installation. (If such a section does not
+ exist, you'll want to add one.) In this example, Bugzilla has
+ been installed at
+ <filename class="directory">/var/www/html/bugzilla</filename>.
+ </para>
+
+ <programlisting>
+ <Directory /var/www/html/bugzilla>
+ AddHandler cgi-script .cgi
+ Options +Indexes +ExecCGI
+ DirectoryIndex index.cgi
+ AllowOverride Limit
+ </Directory>
+ </programlisting>
+
+ <para>
+ These instructions: allow apache to run .cgi files found
+ within the bugzilla directory; instructs the server to look
+ for a file called <filename>index.cgi</filename> if someone
+ only types the directory name into the browser; and allows
+ Bugzilla's <filename>.htaccess</filename> files to override
+ global permissions.
+ </para>
+
+ <note>
+ <para>
+ It is possible to make these changes globally, or to the
+ directive controlling Bugzilla's parent directory (e.g.
+ <computeroutput><Directory /var/www/html/></computeroutput>).
+ Such changes would also apply to the Bugzilla directory...
+ but they would also apply to many other places where they
+ may or may not be appropriate. In most cases, including
+ this one, it is better to be as restrictive as possible
+ when granting extra access.
+ </para>
+ </note>
+ </step>
+
+ <step>
+ <para>
+ <filename>checksetup.pl</filename> can set tighter permissions
+ on Bugzilla's files and directories if it knows what group the
+ web server runs as. Find the <computeroutput>Group</computeroutput>
+ line in <filename>httpd.conf</filename>, place the value found
+ there in the <replaceable>$webservergroup</replaceable> variable
+ in <filename>localconfig</filename>, then rerun
+ <filename>checksetup.pl</filename>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Optional: If Bugzilla does not actually reside in the webspace
+ directory, but instead has been symbolically linked there, you
+ will need to add the following to the
+ <computeroutput>Options</computeroutput> line of the Bugzilla
+ <computeroutput><Directory></computeroutput> directive
+ (the same one as in the step above):
+ </para>
+
+ <programlisting>
+ +FollowSymLinks
+ </programlisting>
+
+ <para>
+ Without this directive, Apache will not follow symbolic links
+ to places outside its own directory structure, and you will be
+ unable to run Bugzilla.
+ </para>
+ </step>
+ </procedure>
+ </section>
+ <section id="http-apache-mod_perl">
+ <title>Apache <productname>httpd</productname> with mod_perl</title>
+
+ <para>Some configuration is required to make Bugzilla work with Apache
+ and mod_perl</para>
+
+ <procedure>
+ <step>
+ <para>
+ Load <filename>httpd.conf</filename> in your editor.
+ In Fedora and Red Hat Linux, this file is found in
+ <filename class="directory">/etc/httpd/conf</filename>.
+ </para>
+ </step>
+
+ <step>
+ <para>Add the following information to your httpd.conf file, substituting
+ where appropriate with your own local paths.</para>
+
+ <note>
+ <para>This should be used instead of the <Directory> block
+ shown above. This should also be above any other <literal>mod_perl</literal>
+ directives within the <filename>httpd.conf</filename> and must be specified
+ in the order as below.</para>
+ </note>
+ <warning>
+ <para>You should also ensure that you have disabled <literal>KeepAlive</literal>
+ support in your Apache install when utilizing Bugzilla under mod_perl</para>
+ </warning>
+
+ <programlisting>
+ PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
+ PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
+ </programlisting>
+ </step>
+
+ <step>
+ <para>
+ <filename>checksetup.pl</filename> can set tighter permissions
+ on Bugzilla's files and directories if it knows what group the
+ web server runs as. Find the <computeroutput>Group</computeroutput>
+ line in <filename>httpd.conf</filename>, place the value found
+ there in the <replaceable>$webservergroup</replaceable> variable
+ in <filename>localconfig</filename>, then rerun
+ <filename>checksetup.pl</filename>.
+ </para>
+ </step>
+ </procedure>
+
+ <para>On restarting Apache, Bugzilla should now be running within the
+ mod_perl environment. Please ensure you have run checksetup.pl to set
+ permissions before you restart Apache.</para>
+
+ <note>
+ <para>Please bear the following points in mind when looking at using
+ Bugzilla under mod_perl:
+ <itemizedlist>
+ <listitem>
+ <para>
+ mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
+ looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM.
+ The more RAM you can get, the better. mod_perl is basically trading RAM for
+ speed. At least 2GB total system RAM is recommended for running Bugzilla under
+ mod_perl.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Under mod_perl, you have to restart Apache if you make any manual change to
+ any Bugzilla file. You can't just reload--you have to actually
+ <emphasis>restart</emphasis> the server (as in make sure it stops and starts
+ again). You <emphasis>can</emphasis> change localconfig and the params file
+ manually, if you want, because those are re-read every time you load a page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You must run in Apache's Prefork MPM (this is the default). The Worker MPM
+ may not work--we haven't tested Bugzilla's mod_perl support under threads.
+ (And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Bugzilla generally expects to be the only mod_perl application running on
+ your entire server. It may or may not work if there are other applications also
+ running under mod_perl. It does try its best to play nice with other mod_perl
+ applications, but it still may have conflicts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It is recommended that you have one Bugzilla instance running under mod_perl
+ on your server. Bugzilla has not been tested with more than one instance running.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </note>
+ </section>
+ </section>
+
+ <section id="http-iis">
+ <title>Microsoft <productname>Internet Information Services</productname></title>
+
+ <para>
+ If you are running Bugzilla on Windows and choose to use
+ Microsoft's <productname>Internet Information Services</productname>
+ or <productname>Personal Web Server</productname> you will need
+ to perform a number of other configuration steps as explained below.
+ You may also want to refer to the following Microsoft Knowledge
+ Base articles:
+ <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink>
+ <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0,
+ 5.0, and 5.1</quote> (for <productname>Internet Information
+ Services</productname>) and
+ <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink>
+ <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
+ Server on Windows 95/98</quote> (for <productname>Personal Web
+ Server</productname>).
+ </para>
+
+ <para>
+ You will need to create a virtual directory for the Bugzilla
+ install. Put the Bugzilla files in a directory that is named
+ something <emphasis>other</emphasis> than what you want your
+ end-users accessing. That is, if you want your users to access
+ your Bugzilla installation through
+ <quote>http://<yourdomainname>/Bugzilla</quote>, then do
+ <emphasis>not</emphasis> put your Bugzilla files in a directory
+ named <quote>Bugzilla</quote>. Instead, place them in a different
+ location, and then use the IIS Administration tool to create a
+ Virtual Directory named "Bugzilla" that acts as an alias for the
+ actual location of the files. When creating that virtual directory,
+ make sure you add the <quote>Execute (such as ISAPI applications or
+ CGI)</quote> access permission.
+ </para>
+
+ <para>
+ You will also need to tell IIS how to handle Bugzilla's
+ .cgi files. Using the IIS Administration tool again, open up
+ the properties for the new virtual directory and select the
+ Configuration option to access the Script Mappings. Create an
+ entry mapping .cgi to:
+ </para>
+
+ <programlisting>
+<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s
+ </programlisting>
+
+ <para>
+ For example:
+ </para>
+
+ <programlisting>
+c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
+ </programlisting>
+
+ <note>
+ <para>
+ The ActiveState install may have already created an entry for
+ .pl files that is limited to <quote>GET,HEAD,POST</quote>. If
+ so, this mapping should be <emphasis>removed</emphasis> as
+ Bugzilla's .pl files are not designed to be run via a web server.
+ </para>
+ </note>
+
+ <para>
+ IIS will also need to know that the index.cgi should be treated
+ as a default document. On the Documents tab page of the virtual
+ directory properties, you need to add index.cgi as a default
+ document type. If you wish, you may remove the other default
+ document types for this particular virtual directory, since Bugzilla
+ doesn't use any of them.
+ </para>
+
+ <para>
+ Also, and this can't be stressed enough, make sure that files
+ such as <filename>localconfig</filename> and your
+ <filename class="directory">data</filename> directory are
+ secured as described in <xref linkend="security-webserver-access"/>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="install-config-bugzilla">
+ <title>Bugzilla</title>
+
+ <para>
+ Your Bugzilla should now be working. Access
+ <filename>http://<your-bugzilla-server>/</filename> -
+ you should see the Bugzilla
+ front page. If not, consult the Troubleshooting section,
+ <xref linkend="troubleshooting"/>.
+ </para>
+
+ <note>
+ <para>
+ The URL above may be incorrect if you installed Bugzilla into a
+ subdirectory or used a symbolic link from your web site root to
+ the Bugzilla directory.
+ </para>
+ </note>
+
+ <para>
+ Log in with the administrator account you defined in the last
+ <filename>checksetup.pl</filename> run. You should go through
+ the parameters on the Edit Parameters page
+ (see link in the footer) and see if there are any you wish to
+ change.
+ They key parameters are documented in <xref linkend="parameters"/>;
+ you should certainly alter
+ <command>maintainer</command> and <command>urlbase</command>;
+ you may also want to alter
+ <command>cookiepath</command> or <command>requirelogin</command>.
+ </para>
+
+ <para>
+ This would also be a good time to revisit the
+ <filename>localconfig</filename> file and make sure that the
+ names of the priorities, severities, platforms and operating systems
+ are those you wish to use when you start creating bugs. Remember
+ to rerun <filename>checksetup.pl</filename> if you change it.
+ </para>
+
+ <para>
+ Bugzilla has several optional features which require extra
+ configuration. You can read about those in
+ <xref linkend="extraconfig"/>.
+ </para>
+ </section>
+ </section>
+
+ <section id="extraconfig">
+ <title>Optional Additional Configuration</title>
+
+ <para>
+ Bugzilla has a number of optional features. This section describes how
+ to configure or enable them.
+ </para>
+
+ <section>
+ <title>Bug Graphs</title>
+
+ <para>If you have installed the necessary Perl modules you
+ can start collecting statistics for the nifty Bugzilla
+ graphs.</para>
+
+ <screen><prompt>bash#</prompt> <command>crontab -e</command></screen>
+
+ <para>
+ This should bring up the crontab file in your editor.
+ Add a cron entry like this to run
+ <filename>collectstats.pl</filename>
+ daily at 5 after midnight:
+ </para>
+
+ <programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting>
+
+ <para>
+ After two days have passed you'll be able to view bug graphs from
+ the Reports page.
+ </para>
+
+ <para>
+ When upgrading Bugzilla, this format may change.
+ To create new status data, (re)move old data and run the following
+ commands:
+ </para>
+
+ <screen>
+ <prompt>bash$</prompt>
+ <command>cd <your-bugzilla-directory></command>
+ <prompt>bash$</prompt>
+ <command>./collectstats.pl --regenerate</command>
+ </screen>
+
+ <note>
+ <para>
+ Windows does not have 'cron', but it does have the Task
+ Scheduler, which performs the same duties. There are also
+ third-party tools that can be used to implement cron, such as
+ <ulink url="http://www.nncron.ru/">nncron</ulink>.
+ </para>
+ </note>
+ </section>
+
+ <section id="installation-whining-cron">
+ <title>The Whining Cron</title>
+
+ <para>What good are
+ bugs if they're not annoying? To help make them more so you
+ can set up Bugzilla's automatic whining system to complain at engineers
+ which leave their bugs in the NEW or REOPENED state without triaging them.
+ </para>
+ <para>
+ This can be done by adding the following command as a daily
+ crontab entry, in the same manner as explained above for bug
+ graphs. This example runs it at 12.55am.
+ </para>
+
+ <programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting>
+
+ <note>
+ <para>
+ Windows does not have 'cron', but it does have the Task
+ Scheduler, which performs the same duties. There are also
+ third-party tools that can be used to implement cron, such as
+ <ulink url="http://www.nncron.ru/">nncron</ulink>.
+ </para>
+ </note>
+ </section>
+
+ <section id="installation-whining">
+ <title>Whining</title>
+
+ <para>
+ As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
+ them at regular intervals, by having Bugzilla execute saved searches
+ at certain times and emailing the results to the user. This is known
+ as "Whining". The process of configuring Whining is described
+ in <xref linkend="whining"/>, but for it to work a Perl script must be
+ executed at regular intervals.
+ </para>
+
+ <para>
+ This can be done by adding the following command as a daily
+ crontab entry, in the same manner as explained above for bug
+ graphs. This example runs it every 15 minutes.
+ </para>
+
+ <programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting>
+
+ <note>
+ <para>
+ Whines can be executed as often as every 15 minutes, so if you specify
+ longer intervals between executions of whine.pl, some users may not
+ be whined at as often as they would expect. Depending on the person,
+ this can either be a very Good Thing or a very Bad Thing.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ Windows does not have 'cron', but it does have the Task
+ Scheduler, which performs the same duties. There are also
+ third-party tools that can be used to implement cron, such as
+ <ulink url="http://www.nncron.ru/">nncron</ulink>.
+ </para>
+ </note>
+ </section>
+
+ <section id="apache-addtype">
+ <title>Serving Alternate Formats with the right MIME type</title>
+
+ <para>
+ Some Bugzilla pages have alternate formats, other than just plain
+ <acronym>HTML</acronym>. In particular, a few Bugzilla pages can
+ output their contents as either <acronym>XUL</acronym> (a special
+ Mozilla format, that looks like a program <acronym>GUI</acronym>)
+ or <acronym>RDF</acronym> (a type of structured <acronym>XML</acronym>
+ that can be read by various programs).
+ </para>
+ <para>
+ In order for your users to see these pages correctly, Apache must
+ send them with the right <acronym>MIME</acronym> type. To do this,
+ add the following lines to your Apache configuration, either in the
+ <computeroutput><VirtualHost></computeroutput> section for your
+ Bugzilla, or in the <computeroutput><Directory></computeroutput>
+ section for your Bugzilla:
+ </para>
+ <para>
+ <screen>AddType application/vnd.mozilla.xul+xml .xul
+AddType application/rdf+xml .rdf</screen>
+ </para>
+ </section>
+ </section>
+
+ <section id="multiple-bz-dbs">
+ <title>Multiple Bugzilla databases with a single installation</title>
+
+ <para>The previous instructions referred to a standard installation, with
+ one unique Bugzilla database. However, you may want to host several
+ distinct installations, without having several copies of the code. This is
+ possible by using the PROJECT environment variable. When accessed,
+ Bugzilla checks for the existence of this variable, and if present, uses
+ its value to check for an alternative configuration file named
+ <filename>localconfig.<PROJECT></filename> in the same location as
+ the default one (<filename>localconfig</filename>). It also checks for
+ customized templates in a directory named
+ <filename><PROJECT></filename> in the same location as the
+ default one (<filename>template/<langcode></filename>). By default
+ this is <filename>template/en/default</filename> so PROJECT's templates
+ would be located at <filename>template/en/PROJECT</filename>.</para>
+
+ <para>To set up an alternate installation, just export PROJECT=foo before
+ running <command>checksetup.pl</command> for the first time. It will
+ result in a file called <filename>localconfig.foo</filename> instead of
+ <filename>localconfig</filename>. Edit this file as described above, with
+ reference to a new database, and re-run <command>checksetup.pl</command>
+ to populate it. That's all.</para>
+
+ <para>Now you have to configure the web server to pass this environment
+ variable when accessed via an alternate URL, such as virtual host for
+ instance. The following is an example of how you could do it in Apache,
+ other Webservers may differ.
+<programlisting>
+<VirtualHost 212.85.153.228:80>
+ ServerName foo.bar.baz
+ SetEnv PROJECT foo
+ Alias /bugzilla /var/www/bugzilla
+</VirtualHost>
+</programlisting>
+ </para>
+
+ <para>Don't forget to also export this variable before accessing Bugzilla
+ by other means, such as cron tasks for instance.</para>
+ </section>
+
+ <section id="os-specific">
+ <title>OS-Specific Installation Notes</title>
+
+ <para>Many aspects of the Bugzilla installation can be affected by the
+ operating system you choose to install it on. Sometimes it can be made
+ easier and others more difficult. This section will attempt to help you
+ understand both the difficulties of running on specific operating systems
+ and the utilities available to make it easier.
+ </para>
+
+ <para>If you have anything to add or notes for an operating system not
+ covered, please file a bug in &bzg-bugs;.
+ </para>
+
+ <section id="os-win32">
+ <title>Microsoft Windows</title>
+ <para>
+ Making Bugzilla work on Windows is more difficult than making it
+ work on Unix. For that reason, we still recommend doing so on a Unix
+ based system such as GNU/Linux. That said, if you do want to get
+ Bugzilla running on Windows, you will need to make the following
+ adjustments. A detailed step-by-step
+ <ulink url="http://www.bugzilla.org/docs/win32install.html">
+ installation guide for Windows</ulink> is also available
+ if you need more help with your installation.
+ </para>
+
+ <section id="win32-perl">
+ <title>Win32 Perl</title>
+ <para>
+ Perl for Windows can be obtained from
+ <ulink url="http://www.activestate.com/">ActiveState</ulink>.
+ You should be able to find a compiled binary at <ulink
+ url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />.
+ The following instructions assume that you are using version
+ 5.8.1 of ActiveState.
+ </para>
+
+ <note>
+ <para>
+ These instructions are for 32-bit versions of Windows. If you are
+ using a 64-bit version of Windows, you will need to install 32-bit
+ Perl in order to install the 32-bit modules as described below.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="win32-perl-modules">
+ <title>Perl Modules on Win32</title>
+
+ <para>
+ Bugzilla on Windows requires the same perl modules found in
+ <xref linkend="install-perlmodules"/>. The main difference is that
+ windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead
+ of CPAN. ActiveState provides a GUI to manage Perl modules. We highly
+ recommend that you use it. If you prefer to use ppm from the
+ command-line, type:
+ </para>
+
+ <programlisting>
+C:\perl> <command>ppm install <module name></command>
+ </programlisting>
+
+ <para>
+ The best source for the Windows PPM modules needed for Bugzilla
+ is probably the theory58S website, which you can add to your list
+ of repositories as follows (for Perl 5.8.x):
+ </para>
+
+ <programlisting>
+<command>ppm repo add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command>
+ </programlisting>
+
+ <para>
+ If you are using Perl 5.10.x, you cannot use the same PPM modules as Perl
+ 5.8.x as they are incompatible. In this case, you should add the following
+ repository:
+ </para>
+ <programlisting>
+<command>ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/</command>
+ </programlisting>
+
+ <note>
+ <para>
+ In versions prior to 5.8.8 build 819 of PPM the command is
+ <programlisting>
+<command>ppm repository add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command>
+ </programlisting>
+ </para>
+ </note>
+ <note>
+ <para>
+ The PPM repository stores modules in 'packages' that may have
+ a slightly different name than the module. If retrieving these
+ modules from there, you will need to pay attention to the information
+ provided when you run <command>checksetup.pl</command> as it will
+ tell you what package you'll need to install.
+ </para>
+ </note>
+
+ <tip>
+ <para>
+ If you are behind a corporate firewall, you will need to let the
+ ActiveState PPM utility know how to get through it to access
+ the repositories by setting the HTTP_proxy system environmental
+ variable. For more information on setting that variable, see
+ the ActiveState documentation.
+ </para>
+ </tip>
+ </section>
+
+ <section id="win32-code-changes">
+ <title>Code changes required to run on Win32</title>
+
+ <para>
+ Bugzilla on Win32 is supported out of the box from version 2.20; this
+ means that no code changes are required to get Bugzilla running.
+ </para>
+
+ </section>
+
+ <section id="win32-http">
+ <title>Serving the web pages</title>
+
+ <para>
+ As is the case on Unix based systems, any web server should
+ be able to handle Bugzilla; however, the Bugzilla Team still
+ recommends Apache whenever asked. No matter what web server
+ you choose, be sure to pay attention to the security notes
+ in <xref linkend="security-webserver-access"/>. More
+ information on configuring specific web servers can be found
+ in <xref linkend="http"/>.
+ </para>
+
+ <note>
+ <para>
+ If using Apache on windows, you can set the <ulink
+ url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
+ directive in your Apache config to avoid having to modify
+ the first line of every script to contain your path to Perl
+ instead of <filename>/usr/bin/perl</filename>. When setting
+ <filename>ScriptInterpreterSource</filename>, do not forget
+ to specify the <command>-T</command> flag to enable the taint
+ mode. For example: <command>C:\Perl\bin\perl.exe -T</command>.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="win32-email">
+ <title>Sending Email</title>
+
+ <para>
+ To enable Bugzilla to send email on Windows, the server running the
+ Bugzilla code must be able to connect to, or act as, an SMTP server.
+ </para>
+
+ </section>
+ </section>
+
+ <section id="os-macosx">
+ <title><productname>Mac OS X</productname></title>
+
+ <para>Making Bugzilla work on Mac OS X requires the following
+ adjustments.</para>
+
+ <section id="macosx-sendmail">
+ <title>Sendmail</title>
+
+ <para>In Mac OS X 10.3 and later,
+ <ulink url="http://www.postfix.org/">Postfix</ulink>
+ is used as the built-in email server. Postfix provides an executable
+ that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can
+ find it.</para>
+
+ <para>As of version 2.20, Bugzilla will be able to find the fake
+ sendmail executable without any assistance. However, you will have
+ to turn on the sendmailnow parameter before you do anything that would
+ result in email being sent. For more information, see the description
+ of the sendmailnow parameter in <xref linkend="parameters"/>.</para>
+
+ </section>
+
+ <section id="macosx-libraries">
+ <title>Libraries & Perl Modules on Mac OS X</title>
+
+ <para>Apple does not include the GD library with Mac OS X. Bugzilla
+ needs this for bug graphs.</para>
+
+ <para>You can use DarwinPorts (<ulink url="http://darwinports.com/"/>)
+ or Fink (<ulink url="http://sourceforge.net/projects/fink/"/>), both
+ of which are similar in nature to the CPAN installer, but install
+ common unix programs.</para>
+
+ <para>Follow the instructions for setting up DarwinPorts or Fink.
+ Once you have one installed, you'll want to use it to install the
+ <filename>gd2</filename> package.
+ </para>
+
+ <para>Fink will prompt you for a number of dependencies, type 'y' and hit
+ enter to install all of the dependencies and then watch it work. You will
+ then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
+ install the GD Perl module.
+ </para>
+
+ <note>
+ <para>To prevent creating conflicts with the software that Apple
+ installs by default, Fink creates its own directory tree at
+ <filename class="directory">/sw</filename> where it installs most of
+ the software that it installs. This means your libraries and headers
+ will be at <filename class="directory">/sw/lib</filename> and
+ <filename class="directory">/sw/include</filename> instead of
+ <filename class="directory">/usr/lib</filename> and
+ <filename class="directory">/usr/include</filename>. When the
+ Perl module config script asks where your <filename>libgd</filename>
+ is, be sure to tell it
+ <filename class="directory">/sw/lib</filename>.
+ </para>
+ </note>
+
+ <para>Also available via DarwinPorts and Fink is
+ <filename>expat</filename>. After installing the expat package, you
+ will be able to install XML::Parser using CPAN. If you use fink, there
+ is one caveat. Unlike recent versions of
+ the GD module, XML::Parser doesn't prompt for the location of the
+ required libraries. When using CPAN, you will need to use the following
+ command sequence:
+ </para>
+
+ <screen>
+# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/>
+# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
+# make; make test; make install <co id="macosx-make"/>
+# exit <co id="macosx-exit"/>
+ </screen>
+ <calloutlist>
+ <callout arearefs="macosx-look macosx-exit">
+ <para>The look command will download the module and spawn a
+ new shell with the extracted files as the current working directory.
+ The exit command will return you to your original shell.
+ </para>
+ </callout>
+ <callout arearefs="macosx-make">
+ <para>You should watch the output from these make commands,
+ especially <quote>make test</quote> as errors may prevent
+ XML::Parser from functioning correctly with Bugzilla.
+ </para>
+ </callout>
+ </calloutlist>
+ </section>
+ </section>
+
+ <section id="os-linux">
+ <title>Linux Distributions</title>
+ <para>Many Linux distributions include Bugzilla and its
+ dependencies in their native package management systems.
+ Installing Bugzilla with root access on any Linux system
+ should be as simple as finding the Bugzilla package in the
+ package management application and installing it using the
+ normal command syntax. Several distributions also perform
+ the proper web server configuration automatically on installation.
+ </para>
+ <para>Please consult the documentation of your Linux
+ distribution for instructions on how to install packages,
+ or for specific instructions on installing Bugzilla with
+ native package management tools. There is also a
+ <ulink url="http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation">
+ Bugzilla Wiki Page</ulink> for distro-specific installation
+ notes.
+ </para>
+ </section>
+ </section>
+
+
+ <section id="nonroot">
+ <title>UNIX (non-root) Installation Notes</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>If you are running a *NIX OS as non-root, either due
+ to lack of access (web hosts, for example) or for security
+ reasons, this will detail how to install Bugzilla on such
+ a setup. It is recommended that you read through the
+ <xref linkend="installation" />
+ first to get an idea on the installation steps required.
+ (These notes will reference to steps in that guide.)</para>
+
+ </section>
+
+ <section>
+ <title>MySQL</title>
+
+ <para>You may have MySQL installed as root. If you're
+ setting up an account with a web host, a MySQL account
+ needs to be set up for you. From there, you can create
+ the bugs account, or use the account given to you.</para>
+
+ <warning>
+ <para>You may have problems trying to set up
+ <command>GRANT</command> permissions to the database.
+ If you're using a web host, chances are that you have a
+ separate database which is already locked down (or one big
+ database with limited/no access to the other areas), but you
+ may want to ask your system administrator what the security
+ settings are set to, and/or run the <command>GRANT</command>
+ command for you.</para>
+
+ <para>Also, you will probably not be able to change the MySQL
+ root user password (for obvious reasons), so skip that
+ step.</para>
+ </warning>
+
+ <section>
+ <title>Running MySQL as Non-Root</title>
+ <section>
+ <title>The Custom Configuration Method</title>
+ <para>Create a file .my.cnf in your
+ home directory (using /home/foo in this example)
+ as follows....</para>
+ <programlisting>
+[mysqld]
+datadir=/home/foo/mymysql
+socket=/home/foo/mymysql/thesock
+port=8081
+
+[mysql]
+socket=/home/foo/mymysql/thesock
+port=8081
+
+[mysql.server]
+user=mysql
+basedir=/var/lib
+
+[safe_mysqld]
+err-log=/home/foo/mymysql/the.log
+pid-file=/home/foo/mymysql/the.pid
+ </programlisting>
+ </section>
+ <section>
+ <title>The Custom Built Method</title>
+
+ <para>You can install MySQL as a not-root, if you really need to.
+ Build it with PREFIX set to <filename class="directory">/home/foo/mysql</filename>,
+ or use pre-installed executables, specifying that you want
+ to put all of the data files in <filename class="directory">/home/foo/mysql/data</filename>.
+ If there is another MySQL server running on the system that you
+ do not own, use the -P option to specify a TCP port that is not
+ in use.</para>
+ </section>
+
+ <section>
+ <title>Starting the Server</title>
+ <para>After your mysqld program is built and any .my.cnf file is
+ in place, you must initialize the databases (ONCE).</para>
+ <screen>
+ <prompt>bash$</prompt>
+ <command>mysql_install_db</command>
+ </screen>
+ <para>Then start the daemon with</para>
+ <screen>
+ <prompt>bash$</prompt>
+ <command>safe_mysql &</command>
+ </screen>
+ <para>After you start mysqld the first time, you then connect to
+ it as "root" and <command>GRANT</command> permissions to other
+ users. (Again, the MySQL root account has nothing to do with
+ the *NIX root account.)</para>
+
+ <note>
+ <para>You will need to start the daemons yourself. You can either
+ ask your system administrator to add them to system startup files, or
+ add a crontab entry that runs a script to check on these daemons
+ and restart them if needed.</para>
+ </note>
+
+ <warning>
+ <para>Do NOT run daemons or other services on a server without first
+ consulting your system administrator! Daemons use up system resources
+ and running one may be in violation of your terms of service for any
+ machine on which you are a user!</para>
+ </warning>
+ </section>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Perl</title>
+
+ <para>
+ On the extremely rare chance that you don't have Perl on
+ the machine, you will have to build the sources
+ yourself. The following commands should get your system
+ installed with your own personal version of Perl:
+ </para>
+
+ <screen>
+ <prompt>bash$</prompt>
+ <command>wget http://perl.com/CPAN/src/stable.tar.gz</command>
+ <prompt>bash$</prompt>
+ <command>tar zvxf stable.tar.gz</command>
+ <prompt>bash$</prompt>
+ <command>cd perl-5.8.1</command> (or whatever the version of Perl is called)
+ <prompt>bash$</prompt>
+ <command>sh Configure -de -Dprefix=/home/foo/perl</command>
+ <prompt>bash$</prompt>
+ <command>make && make test && make install</command>
+ </screen>
+
+ <para>
+ Once you have Perl installed into a directory (probably
+ in <filename class="directory">~/perl/bin</filename>), you will need to
+ install the Perl Modules, described below.
+ </para>
+ </section>
+
+ <section id="install-perlmodules-nonroot">
+ <title>Perl Modules</title>
+
+ <para>
+ Installing the Perl modules as a non-root user is accomplished by
+ running the <filename>install-module.pl</filename>
+ script. For more details on this script, see
+ <ulink url="api/install-module.html"><filename>install-module.pl</filename>
+ documentation</ulink>
+ </para>
+ </section>
+
+ <section>
+ <title>HTTP Server</title>
+
+ <para>Ideally, this also needs to be installed as root and
+ run under a special web server account. As long as
+ the web server will allow the running of *.cgi files outside of a
+ cgi-bin, and a way of denying web access to certain files (such as a
+ .htaccess file), you should be good in this department.</para>
+
+ <section>
+ <title>Running Apache as Non-Root</title>
+
+ <para>You can run Apache as a non-root user, but the port will need
+ to be set to one above 1024. If you type <command>httpd -V</command>,
+ you will get a list of the variables that your system copy of httpd
+ uses. One of those, namely HTTPD_ROOT, tells you where that
+ installation looks for its config information.</para>
+
+ <para>From there, you can copy the config files to your own home
+ directory to start editing. When you edit those and then use the -d
+ option to override the HTTPD_ROOT compiled into the web server, you
+ get control of your own customized web server.</para>
+
+ <note>
+ <para>You will need to start the daemons yourself. You can either
+ ask your system administrator to add them to system startup files, or
+ add a crontab entry that runs a script to check on these daemons
+ and restart them if needed.</para>
+ </note>
+
+ <warning>
+ <para>Do NOT run daemons or other services on a server without first
+ consulting your system administrator! Daemons use up system resources
+ and running one may be in violation of your terms of service for any
+ machine on which you are a user!</para>
+ </warning>
+ </section>
+ </section>
+
+ <section>
+ <title>Bugzilla</title>
+
+ <para>
+ When you run <command>./checksetup.pl</command> to create
+ the <filename>localconfig</filename> file, it will list the Perl
+ modules it finds. If one is missing, go back and double-check the
+ module installation from <xref linkend="install-perlmodules-nonroot"/>,
+ then delete the <filename>localconfig</filename> file and try again.
+ </para>
+
+ <warning>
+ <para>One option in <filename>localconfig</filename> you
+ might have problems with is the web server group. If you can't
+ successfully browse to the <filename>index.cgi</filename> (like
+ a Forbidden error), you may have to relax your permissions,
+ and blank out the web server group. Of course, this may pose
+ as a security risk. Having a properly jailed shell and/or
+ limited access to shell accounts may lessen the security risk,
+ but use at your own risk.</para>
+ </warning>
+
+ <section id="suexec">
+ <title>suexec or shared hosting</title>
+
+ <para>If you are running on a system that uses suexec (most shared
+ hosting environments do this), you will need to set the
+ <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename>
+ to match <emphasis>your</emphasis> primary group, rather than the one
+ the web server runs under. You will need to run the following
+ shell commands after running <command>./checksetup.pl</command>,
+ every time you run it (or modify <filename>checksetup.pl</filename>
+ to do them for you via the system() command).
+ <programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
+ for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
+ find . -name .htaccess -exec chmod o+r {} \;
+ chmod o+x . data data/webdot</programlisting>
+ Pay particular attention to the number of semicolons and dots.
+ They are all important. A future version of Bugzilla will
+ hopefully be able to do this for you out of the box.</para>
+ </section>
+ </section>
+ </section>
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
--- /dev/null
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
+<!-- Keep these tools listings in alphabetical order please. -MPB -->
+<section id="integration">
+ <title>Integrating Bugzilla with Third-Party Tools</title>
+
+ <section id="bonsai"
+ xreflabel="Bonsai, the Mozilla automated CVS management system">
+ <title>Bonsai</title>
+
+ <para>Bonsai is a web-based tool for managing
+ <xref linkend="cvs" />
+
+ . Using Bonsai, administrators can control open/closed status of trees,
+ query a fast relational database back-end for change, branch, and comment
+ information, and view changes made since the last time the tree was
+ closed. Bonsai
+ also integrates with
+ <xref linkend="tinderbox" />.
+ </para>
+ </section>
+
+ <section id="cvs" xreflabel="CVS, the Concurrent Versioning System">
+ <title>CVS</title>
+
+ <para>CVS integration is best accomplished, at this point, using the
+ Bugzilla Email Gateway.</para>
+
+ <para>Follow the instructions in this Guide for enabling Bugzilla e-mail
+ integration. Ensure that your check-in script sends an email to your
+ Bugzilla e-mail gateway with the subject of
+ <quote>[Bug XXXX]</quote>,
+ and you can have CVS check-in comments append to your Bugzilla bug. If
+ you want to have the bug be closed automatically, you'll have to modify
+ the <filename>contrib/bugzilla_email_append.pl</filename> script.
+ </para>
+
+ <para>There is also a CVSZilla project, based upon somewhat dated
+ Bugzilla code, to integrate CVS and Bugzilla through CVS' ability to
+ email. Check it out at: <ulink url="http://www.cvszilla.org/"/>.
+ </para>
+
+ <para>Another system capable of CVS integration with Bugzilla is
+ Scmbug. This system provides generic integration of Source code
+ Configuration Management with Bugtracking. Check it out at: <ulink
+ url="http://freshmeat.net/projects/scmbug/"/>.
+ </para>
+
+ </section>
+
+ <section id="scm"
+ xreflabel="Perforce SCM (Fast Software Configuration Management System, a powerful commercial alternative to CVS">
+
+ <title>Perforce SCM</title>
+
+ <para>You can find the project page for Bugzilla and Teamtrack Perforce
+ integration (p4dti) at:
+ <ulink url="http://www.ravenbrook.com/project/p4dti/"/>
+
+ .
+ <quote>p4dti</quote>
+
+ is now an officially supported product from Perforce, and you can find
+ the "Perforce Public Depot" p4dti page at
+ <ulink url="http://public.perforce.com/public/perforce/p4dti/index.html"/>
+
+ .</para>
+
+ <para>Integration of Perforce with Bugzilla, once patches are applied, is
+ seamless. Perforce replication information will appear below the comments
+ of each bug. Be certain you have a matching set of patches for the
+ Bugzilla version you are installing. p4dti is designed to support
+ multiple defect trackers, and maintains its own documentation for it.
+ Please consult the pages linked above for further information.</para>
+ </section>
+
+ <section id="svn"
+ xreflabel="Subversion, a compelling replacement for CVS">
+ <title>Subversion</title>
+ <para>Subversion is a free/open-source version control system,
+ designed to overcome various limitations of CVS. Integration of
+ Subversion with Bugzilla is possible using Scmbug, a system
+ providing generic integration of Source Code Configuration
+ Management with Bugtracking. Scmbug is available at <ulink
+ url="http://freshmeat.net/projects/scmbug/"/>.</para>
+ </section>
+
+ <section id="tinderbox"
+ xreflabel="Tinderbox, the Mozilla automated build management system">
+ <title>Tinderbox/Tinderbox2</title>
+
+ <para>Tinderbox is a continuous-build system which can integrate with
+ Bugzilla - see
+ <ulink url="http://www.mozilla.org/projects/tinderbox"/> for details
+ of Tinderbox, and
+ <ulink url="http://tinderbox.mozilla.org/showbuilds.cgi"/> to see it
+ in action.</para>
+ </section>
+</section>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<chapter id="introduction">
+ <title>Introduction</title>
+
+ <section id="what-is-bugzilla">
+ <title>What is Bugzilla?</title>
+
+ <para>
+ Bugzilla is a bug- or issue-tracking system. Bug-tracking
+ systems allow individual or groups of developers effectively to keep track
+ of outstanding problems with their products.
+ </para>
+
+ <para><emphasis>Do we need more here?</emphasis></para>
+
+ </section>
+
+ <section id="why-tracking">
+ <title>Why use a bug-tracking system?</title>
+
+ <para>Those who do not use a bug-tracking system tend to rely on
+ shared lists, email, spreadsheets and/or Post-It notes to monitor the
+ status of defects. This procedure
+ is usually error-prone and tends to cause those bugs judged least
+ significant by developers to be dropped or ignored.</para>
+
+ <para>Integrated defect-tracking systems make sure that nothing gets
+ swept under the carpet; they provide a method of creating, storing,
+ arranging and processing defect reports and enhancement requests.</para>
+
+ </section>
+
+ <section id="why-bugzilla">
+ <title>Why use Bugzilla?</title>
+
+ <para>Bugzilla is the leading open-source/free software bug tracking
+ system. It boasts many advanced features, including:
+ <itemizedlist>
+ <listitem>
+ <para>Powerful searching</para>
+ </listitem>
+
+ <listitem>
+ <para>User-configurable email notifications of bug changes</para>
+ </listitem>
+
+ <listitem>
+ <para>Full change history</para>
+ </listitem>
+
+ <listitem>
+ <para>Inter-bug dependency tracking and graphing</para>
+ </listitem>
+
+ <listitem>
+ <para>Excellent attachment management</para>
+ </listitem>
+
+ <listitem>
+ <para>Integrated, product-based, granular security schema</para>
+ </listitem>
+
+ <listitem>
+ <para>Fully security-audited, and runs under Perl's taint mode</para>
+ </listitem>
+
+ <listitem>
+ <para>A robust, stable RDBMS back-end</para>
+ </listitem>
+
+ <listitem>
+ <para>Completely customizable and/or localizable web user
+ interface</para>
+ </listitem>
+
+ <listitem>
+ <para>Additional XML, email and console interfaces</para>
+ </listitem>
+
+ <listitem>
+ <para>Extensive configurability</para>
+ </listitem>
+
+ <listitem>
+ <para>Smooth upgrade pathway between versions</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Bugzilla is very adaptable to various situations. Known uses
+ currently include IT support queues, Systems Administration deployment
+ management, chip design and development problem tracking (both
+ pre-and-post fabrication), and software and hardware bug tracking for
+ luminaries such as Redhat, NASA, Linux-Mandrake, and VA Systems.
+ Combined with systems such as
+ <ulink url="http://www.cvshome.org">CVS</ulink>,
+ <ulink url="http://www.mozilla.org/bonsai.html">Bonsai</ulink>, or
+ <ulink url="http://www.perforce.com">Perforce SCM</ulink>, Bugzilla
+ provides a powerful, easy-to-use configuration management solution.</para>
+ </section>
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
--- /dev/null
+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<appendix id="install-perlmodules-manual">
+ <title>Manual Installation of Perl Modules</title>
+
+ <section id="modules-manual-instructions">
+ <title>Instructions</title>
+ <para>
+ If you need to install Perl modules manually, here's how it's done.
+ Download the module using the link given in the next section, and then
+ apply this magic incantation, as root:
+ </para>
+
+ <para>
+ <screen><prompt>bash#</prompt> tar -xzvf <module>.tar.gz
+<prompt>bash#</prompt> cd <module>
+<prompt>bash#</prompt> perl Makefile.PL
+<prompt>bash#</prompt> make
+<prompt>bash#</prompt> make test
+<prompt>bash#</prompt> make install</screen>
+ </para>
+ <note>
+ <para>
+ In order to compile source code under Windows you will need to obtain
+ a 'make' utility. The <command>nmake</command> utility provided with
+ Microsoft Visual C++ may be used. As an alternative, there is a
+ utility called <command>dmake</command> available from CPAN which is
+ written entirely in Perl.
+ </para>
+ <para>
+ As described in <xref linkend="modules-manual-download" />, however, most
+ packages already exist and are available from ActiveState or theory58S.
+ We highly recommend that you install them using the ppm GUI available with
+ ActiveState and to add the theory58S repository to your list of repositories.
+ </para>
+ </note>
+ </section>
+
+ <section id="modules-manual-download">
+ <title>Download Locations</title>
+
+ <note>
+ <para>
+ Running Bugzilla on Windows requires the use of ActiveState
+ Perl 5.8.1 or higher. Many modules already exist in the core
+ distribution of ActiveState Perl. Additional modules can be downloaded
+ from <ulink url="http://theoryx5.uwinnipeg.ca/ppms/" /> if you use
+ Perl 5.8.x or from <ulink url="http://cpan.uwinnipeg.ca/PPMPackages/10xx/" />
+ if you use Perl 5.10.x.
+ </para>
+ </note>
+
+ <para>
+ CGI:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/>
+ Documentation: <ulink url="http://perldoc.perl.org/CGI.html"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Data-Dumper:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/Data-Dumper/Dumper.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Date::Format (part of TimeDate):
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ DBI:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/>
+ Documentation: <ulink url="http://dbi.perl.org/docs/"/>
+ </literallayout>
+ </para>
+
+ <para>
+ DBD::mysql:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ DBD::Pg:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-Pg/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/DBD-Pg/Pg.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ File::Spec:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
+ Documentation: <ulink url="http://perldoc.perl.org/File/Spec.html"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Template-Toolkit:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/>
+ Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/>
+ </literallayout>
+ </para>
+
+ <para>
+ GD:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/GD/GD.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Template::Plugin::GD:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-GD/" />
+ Documentation: <ulink url="http://www.template-toolkit.org/docs/aqua/Modules/index.html" />
+ </literallayout>
+ </para>
+
+ <para>
+ MIME::Parser (part of MIME-tools):
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
+ </literallayout>
+ </para>
+
+ </section>
+
+ <section id="modules-manual-optional">
+ <title>Optional Modules</title>
+
+ <para>
+ Chart::Base:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/Chart/Chart.pod"/>
+ </literallayout>
+ </para>
+
+ <para>
+ GD::Graph:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ GD::Text::Align (part of GD::Text::Util):
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/>
+ Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ XML::Twig:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Twig/"/>
+ Documentation: <ulink url="http://standards.ieee.org/resources/spasystem/twig/twig_stable.html"/>
+ </literallayout>
+ </para>
+
+ <para>
+ PatchReader:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/>
+ Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Image::Magick:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/dist/PerlMagick/"/>
+ Documentation: <ulink url="http://www.imagemagick.org/script/resources.php"/>
+ </literallayout>
+ </para>
+ </section>
+</appendix>
--- /dev/null
+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
+ <title>Contrib</title>
+
+ <para>
+ There are a number of unofficial Bugzilla add-ons in the
+ <filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
+ directory. This section documents them.
+ </para>
+
+ <section id="cmdline">
+ <title>Command-line Search Interface</title>
+
+ <para>
+ There are a suite of Unix utilities for searching Bugzilla from the
+ command line. They live in the
+ <filename class="directory">contrib/cmdline</filename> directory.
+ There are three files - <filename>query.conf</filename>,
+ <filename>buglist</filename> and <filename>bugs</filename>.
+ </para>
+
+ <warning>
+ <para>
+ These files pre-date the templatization work done as part of the
+ 2.16 release, and have not been updated.
+ </para>
+ </warning>
+
+ <para>
+ <filename>query.conf</filename> contains the mapping from
+ options to field names and comparison types. Quoted option names
+ are <quote>grepped</quote> for, so it should be easy to edit this
+ file. Comments (#) have no effect; you must make sure these lines
+ do not contain any quoted <quote>option</quote>.
+ </para>
+
+ <para>
+ <filename>buglist</filename> is a shell script that submits a
+ Bugzilla query and writes the resulting HTML page to stdout.
+ It supports both short options, (such as <quote>-Afoo</quote>
+ or <quote>-Rbar</quote>) and long options (such
+ as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>).
+ If the first character of an option is not <quote>-</quote>, it is
+ treated as if it were prefixed with <quote>--default=</quote>.
+ </para>
+
+ <para>
+ The column list is taken from the COLUMNLIST environment variable.
+ This is equivalent to the <quote>Change Columns</quote> option
+ that is available when you list bugs in buglist.cgi. If you have
+ already used Bugzilla, grep for COLUMNLIST in your cookies file
+ to see your current COLUMNLIST setting.
+ </para>
+
+ <para>
+ <filename>bugs</filename> is a simple shell script which calls
+ <filename>buglist</filename> and extracts the
+ bug numbers from the output. Adding the prefix
+ <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote>
+ turns the bug list into a working link if any bugs are found.
+ Counting bugs is easy. Pipe the results through
+ <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
+ </para>
+
+ <para>
+ Akkana Peck says she has good results piping
+ <filename>buglist</filename> output through
+ <command>w3m -T text/html -dump</command>
+ </para>
+
+ </section>
+
+ <section id="cmdline-bugmail">
+ <title>Command-line 'Send Unsent Bug-mail' tool</title>
+
+ <para>
+ Within the <filename class="directory">contrib</filename> directory
+ exists a utility with the descriptive (if compact) name
+ of <filename>sendunsentbugmail.pl</filename>. The purpose of this
+ script is, simply, to send out any bug-related mail that should
+ have been sent by now, but for one reason or another has not.
+ </para>
+
+ <para>
+ To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses
+ the same mechanism as the <filename>sanitycheck.cgi</filename> script;
+ it scans through the entire database looking for bugs with changes that
+ were made more than 30 minutes ago, but where there is no record of
+ anyone related to that bug having been sent mail. Having compiled a list,
+ it then uses the standard rules to determine who gets mail, and sends it
+ out.
+ </para>
+
+ <para>
+ As the script runs, it indicates the bug for which it is currently
+ sending mail; when it has finished, it gives a numerical count of how
+ many mails were sent and how many people were excluded. (Individual
+ user names are not recorded or displayed.) If the script produces
+ no output, that means no unsent mail was detected.
+ </para>
+
+ <para>
+ <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script
+ up into the main directory, ensure it has execute permission, and run it
+ from the command line (or from a cron job) with no parameters.
+ </para>
+ </section>
+
+</appendix>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+<appendix id="downloadlinks">
+ <title>Software Download Links</title>
+
+ <para>All of these sites are current as of April, 2001. Hopefully they'll
+ stay current for a while.</para>
+
+ <para>Apache Web Server:
+ <ulink url="http://www.apache.org/"/>
+
+ Optional web server for Bugzilla, but recommended because of broad user
+ base and support.</para>
+
+ <para>Bugzilla:
+ <ulink url="http://www.bugzilla.org/"/>
+ </para>
+
+ <para>MySQL:
+ <ulink url="http://www.mysql.com/"/>
+ </para>
+
+ <para>Perl:
+ <ulink url="http://www.perl.org/"/>
+ </para>
+
+ <para>CPAN:
+ <ulink url="http://www.cpan.org/"/>
+ </para>
+
+ <para>DBI Perl module:
+ <ulink url="http://www.cpan.org/modules/by-module/DBI/"/>
+ </para>
+
+ <para>MySQL related Perl modules:
+ <ulink url="http://www.cpan.org/modules/by-module/Mysql/"/>
+ </para>
+
+ <para>TimeDate Perl module collection:
+ <ulink url="http://www.cpan.org/modules/by-module/Date/"/>
+ </para>
+
+ <para>GD Perl module:
+ <ulink url="http://www.cpan.org/modules/by-module/GD/"/>
+
+ Alternately, you should be able to find the latest version of GD at
+ <ulink url="http://www.boutell.com/gd/"/>
+ </para>
+
+ <para>Chart::Base module:
+ <ulink url="http://www.cpan.org/modules/by-module/Chart/"/>
+ </para>
+
+ <para>(But remember, Bundle::Bugzilla will install all the modules for you.)
+ </para>
+</appendix>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
--- /dev/null
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<!-- $Id: security.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ -->
+
+<chapter id="security">
+<title>Bugzilla Security</title>
+
+ <para>While some of the items in this chapter are related to the operating
+ system Bugzilla is running on or some of the support software required to
+ run Bugzilla, it is all related to protecting your data. This is not
+ intended to be a comprehensive guide to securing Linux, Apache, MySQL, or
+ any other piece of software mentioned. There is no substitute for active
+ administration and monitoring of a machine. The key to good security is
+ actually right in the middle of the word: <emphasis>U R It</emphasis>.
+ </para>
+
+ <para>While programmers in general always strive to write secure code,
+ accidents can and do happen. The best approach to security is to always
+ assume that the program you are working with isn't 100% secure and restrict
+ its access to other parts of your machine as much as possible.
+ </para>
+
+ <section id="security-os">
+ <title>Operating System</title>
+
+ <section id="security-os-ports">
+ <title>TCP/IP Ports</title>
+
+ <!-- TODO: Get exact number of ports -->
+ <para>The TCP/IP standard defines more than 65,000 ports for sending
+ and receiving traffic. Of those, Bugzilla needs exactly one to operate
+ (different configurations and options may require up to 3). You should
+ audit your server and make sure that you aren't listening on any ports
+ you don't need to be. It's also highly recommended that the server
+ Bugzilla resides on, along with any other machines you administer, be
+ placed behind some kind of firewall.
+ </para>
+
+ </section>
+
+ <section id="security-os-accounts">
+ <title>System User Accounts</title>
+
+ <para>Many <glossterm linkend="gloss-daemon">daemons</glossterm>, such
+ as Apache's <filename>httpd</filename> or MySQL's
+ <filename>mysqld</filename>, run as either <quote>root</quote> or
+ <quote>nobody</quote>. This is even worse on Windows machines where the
+ majority of <glossterm linkend="gloss-service">services</glossterm>
+ run as <quote>SYSTEM</quote>. While running as <quote>root</quote> or
+ <quote>SYSTEM</quote> introduces obvious security concerns, the
+ problems introduced by running everything as <quote>nobody</quote> may
+ not be so obvious. Basically, if you run every daemon as
+ <quote>nobody</quote> and one of them gets compromised it can
+ compromise every other daemon running as <quote>nobody</quote> on your
+ machine. For this reason, it is recommended that you create a user
+ account for each daemon.
+ </para>
+
+ <note>
+ <para>You will need to set the <option>webservergroup</option> option
+ in <filename>localconfig</filename> to the group your web server runs
+ as. This will allow <filename>./checksetup.pl</filename> to set file
+ permissions on Unix systems so that nothing is world-writable.
+ </para>
+ </note>
+
+ </section>
+
+ <section id="security-os-chroot">
+ <title>The <filename>chroot</filename> Jail</title>
+
+ <para>
+ If your system supports it, you may wish to consider running
+ Bugzilla inside of a <filename>chroot</filename> jail. This option
+ provides unprecedented security by restricting anything running
+ inside the jail from accessing any information outside of it. If you
+ wish to use this option, please consult the documentation that came
+ with your system.
+ </para>
+
+ </section>
+
+ </section>
+
+
+
+ <section id="security-mysql">
+ <title>MySQL</title>
+
+ <section id="security-mysql-account">
+ <title>The MySQL System Account</title>
+
+ <para>As mentioned in <xref linkend="security-os-accounts"/>, the MySQL
+ daemon should run as a non-privileged, unique user. Be sure to consult
+ the MySQL documentation or the documentation that came with your system
+ for instructions.
+ </para>
+ </section>
+
+ <section id="security-mysql-root">
+ <title>The MySQL <quote>root</quote> and <quote>anonymous</quote> Users</title>
+
+ <para>By default, MySQL comes with a <quote>root</quote> user with a
+ blank password and an <quote>anonymous</quote> user, also with a blank
+ password. In order to protect your data, the <quote>root</quote> user
+ should be given a password and the anonymous user should be disabled.
+ </para>
+
+ <example id="security-mysql-account-root">
+ <title>Assigning the MySQL <quote>root</quote> User a Password</title>
+
+ <screen>
+<prompt>bash$</prompt> mysql mysql
+<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
+<prompt>mysql></prompt> FLUSH PRIVILEGES;
+ </screen>
+ </example>
+
+ <example id="security-mysql-account-anonymous">
+ <title>Disabling the MySQL <quote>anonymous</quote> User</title>
+ <screen>
+<prompt>bash$</prompt> mysql -u root -p mysql <co id="security-mysql-account-anonymous-mysql"/>
+<prompt>Enter Password:</prompt> <replaceable>new_password</replaceable>
+<prompt>mysql></prompt> DELETE FROM user WHERE user = '';
+<prompt>mysql></prompt> FLUSH PRIVILEGES;
+ </screen>
+ <calloutlist>
+ <callout arearefs="security-mysql-account-anonymous-mysql">
+ <para>This command assumes that you have already completed
+ <xref linkend="security-mysql-account-root"/>.
+ </para>
+ </callout>
+ </calloutlist>
+ </example>
+
+ </section>
+
+ <section id="security-mysql-network">
+ <title>Network Access</title>
+
+ <para>If MySQL and your web server both run on the same machine and you
+ have no other reason to access MySQL remotely, then you should disable
+ the network access. This, along with the suggestion in
+ <xref linkend="security-os-ports"/>, will help protect your system from
+ any remote vulnerabilities in MySQL.
+ </para>
+
+ <example id="security-mysql-network-ex">
+ <title>Disabling Networking in MySQL</title>
+
+ <para>Simply enter the following in <filename>/etc/my.cnf</filename>:
+ <screen>
+[mysqld]
+# Prevent network access to MySQL.
+skip-networking
+ </screen>
+ </para>
+ </example>
+
+ </section>
+
+
+<!-- For possible addition in the future: How to better control the bugs user
+ <section id="security-mysql-bugs">
+ <title>The bugs User</title>
+
+ </section>
+-->
+
+ </section>
+
+
+
+ <section id="security-webserver">
+ <title>Web server</title>
+
+ <section id="security-webserver-access">
+ <title>Disabling Remote Access to Bugzilla Configuration Files</title>
+
+ <para>
+ There are many files that are placed in the Bugzilla directory
+ area that should not be accessible from the web server. Because of the way
+ Bugzilla is currently layed out, the list of what should and should not
+ be accessible is rather complicated. A quick way is to run
+ <filename>testserver.pl</filename> to check if your web server serves
+ Bugzilla files as expected. If not, you may want to follow the few
+ steps below.
+ </para>
+
+ <tip>
+ <para>Bugzilla ships with the ability to create
+ <glossterm linkend="gloss-htaccess"><filename>.htaccess</filename></glossterm>
+ files that enforce these rules. Instructions for enabling these
+ directives in Apache can be found in <xref linkend="http-apache"/>
+ </para>
+ </tip>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>In the main Bugzilla directory, you should:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block:
+ <simplelist type="inline">
+ <member><filename>*.pl</filename></member>
+ <member><filename>*localconfig*</filename></member>
+ </simplelist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>In <filename class="directory">data</filename>:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ <listitem>
+ <para>But allow:
+ <simplelist type="inline">
+ <member><filename>duplicates.rdf</filename></member>
+ </simplelist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>In <filename class="directory">data/webdot</filename>:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>If you use a remote webdot server:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ <listitem>
+ <para>But allow
+ <simplelist type="inline">
+ <member><filename>*.dot</filename></member>
+ </simplelist>
+ only for the remote webdot server</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Otherwise, if you use a local GraphViz:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ <listitem>
+ <para>But allow:
+ <simplelist type="inline">
+ <member><filename>*.png</filename></member>
+ <member><filename>*.gif</filename></member>
+ <member><filename>*.jpg</filename></member>
+ <member><filename>*.map</filename></member>
+ </simplelist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>And if you don't use any dot:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>In <filename class="directory">Bugzilla</filename>:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>In <filename class="directory">template</filename>:</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>Block everything</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>Be sure to test that data that should not be accessed remotely is
+ properly blocked. Of particular interest is the localconfig file which
+ contains your database password. Also, be aware that many editors
+ create temporary and backup files in the working directory and that
+ those should also not be accessible. For more information, see
+ <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug 186383</ulink>
+ or
+ <ulink url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>.
+ To test, simply run <filename>testserver.pl</filename>, as said above.
+ </para>
+
+ <tip>
+ <para>Be sure to check <xref linkend="http"/> for instructions
+ specific to the web server you use.
+ </para>
+ </tip>
+
+ </section>
+
+
+ </section>
+
+
+ <section id="security-bugzilla">
+ <title>Bugzilla</title>
+
+ <section id="security-bugzilla-charset">
+ <title>Prevent users injecting malicious Javascript</title>
+
+ <para>If you installed Bugzilla version 2.22 or later from scratch,
+ then the <emphasis>utf8</emphasis> parameter is switched on by default.
+ This makes Bugzilla explicitly set the character encoding, following
+ <ulink
+ url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">a
+ CERT advisory</ulink> recommending exactly this.
+ The following therefore does not apply to you; just keep
+ <emphasis>utf8</emphasis> turned on.
+ </para>
+
+ <para>If you've upgraded from an older version, then it may be possible
+ for a Bugzilla user to take advantage of character set encoding
+ ambiguities to inject HTML into Bugzilla comments.
+ This could include malicious scripts.
+ This is because due to internationalization concerns, we are unable to
+ turn the <emphasis>utf8</emphasis> parameter on by default for upgraded
+ installations.
+ Turning it on manually will prevent this problem.
+ </para>
+ </section>
+
+ </section>
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End: -->
+
--- /dev/null
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<!-- $Id: troubleshooting.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ -->
+
+<appendix id="troubleshooting">
+<title>Troubleshooting</title>
+
+ <para>This section gives solutions to common Bugzilla installation
+ problems. If none of the section headings seems to match your
+ problem, read the general advice.
+ </para>
+
+ <section id="general-advice">
+ <title>General Advice</title>
+ <para>If you can't get <filename>checksetup.pl</filename> to run to
+ completion, it normally explains what's wrong and how to fix it.
+ If you can't work it out, or if it's being uncommunicative, post
+ the errors in the
+ <ulink url="news://news.mozilla.org/mozilla.support.bugzilla">mozilla.support.bugzilla</ulink>
+ newsgroup.
+ </para>
+
+ <para>If you have made it all the way through
+ <xref linkend="installation"/> (Installation) and
+ <xref linkend="configuration"/> (Configuration) but accessing the Bugzilla
+ URL doesn't work, the first thing to do is to check your web server error
+ log. For Apache, this is often located at
+ <filename>/etc/logs/httpd/error_log</filename>. The error messages
+ you see may be self-explanatory enough to enable you to diagnose and
+ fix the problem. If not, see below for some commonly-encountered
+ errors. If that doesn't help, post the errors to the newsgroup.
+ </para>
+
+ <para>
+ Bugzilla can also log all user-based errors (and many code-based errors)
+ that occur, without polluting the web server's error log. To enable
+ Bugzilla error logging, create a file that Bugzilla can write to, named
+ <filename>errorlog</filename>, in the Bugzilla <filename>data</filename>
+ directory. Errors will be logged as they occur, and will include the type
+ of the error, the IP address and username (if available) of the user who
+ triggered the error, and the values of all environment variables; if a
+ form was being submitted, the data in the form will also be included.
+ To disable error logging, delete or rename the
+ <filename>errorlog</filename> file.
+ </para>
+ </section>
+
+ <section id="trbl-testserver">
+ <title>The Apache web server is not serving Bugzilla pages</title>
+ <para>After you have run <command>checksetup.pl</command> twice,
+ run <command>testserver.pl http://yoursite.yourdomain/yoururl</command>
+ to confirm that your web server is configured properly for
+ Bugzilla.
+ </para>
+ <programlisting>
+<prompt>bash$</prompt> ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
+TEST-OK Webserver is running under group id in $webservergroup.
+TEST-OK Got ant picture.
+TEST-OK Webserver is executing CGIs.
+TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
+</programlisting>
+ </section>
+
+ <section id="trbl-perlmodule">
+ <title>I installed a Perl module, but
+ <filename>checksetup.pl</filename> claims it's not installed!</title>
+
+ <para>This could be caused by one of two things:</para>
+ <orderedlist>
+ <listitem>
+ <para>You have two versions of Perl on your machine. You are installing
+ modules into one, and Bugzilla is using the other. Rerun the CPAN
+ commands (or manual compile) using the full path to Perl from the
+ top of <filename>checksetup.pl</filename>. This will make sure you
+ are installing the modules in the right place.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The permissions on your library directories are set incorrectly.
+ They must, at the very least, be readable by the web server user or
+ group. It is recommended that they be world readable.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="trbl-dbdSponge">
+ <title>DBD::Sponge::db prepare failed</title>
+
+ <para>The following error message may appear due to a bug in DBD::mysql
+ (over which the Bugzilla team have no control):
+ </para>
+
+<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
+ SV = NULL(0x0) at 0x20fc444
+ REFCNT = 1
+ FLAGS = (PADBUSY,PADMY)
+]]></programlisting>
+
+ <para>To fix this, go to
+ <filename><path-to-perl>/lib/DBD/sponge.pm</filename>
+ in your Perl installation and replace
+ </para>
+
+<programlisting><![CDATA[ my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAME'}) {
+ $numFields = @{$attribs->{NAME}};
+]]></programlisting>
+
+ <para>with</para>
+
+<programlisting><![CDATA[ my $numFields;
+ if ($attribs->{'NUM_OF_FIELDS'}) {
+ $numFields = $attribs->{'NUM_OF_FIELDS'};
+ } elsif ($attribs->{'NAMES'}) {
+ $numFields = @{$attribs->{NAMES}};
+]]></programlisting>
+
+ <para>(note the S added to NAME.)</para>
+ </section>
+
+ <section id="paranoid-security">
+ <title>cannot chdir(/var/spool/mqueue)</title>
+
+ <para>If you are installing Bugzilla on SuSE Linux, or some other
+ distributions with <quote>paranoid</quote> security options, it is
+ possible that the checksetup.pl script may fail with the error:
+<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied
+]]></programlisting>
+ </para>
+
+ <para>This is because your <filename>/var/spool/mqueue</filename>
+ directory has a mode of <computeroutput>drwx------</computeroutput>.
+ Type <command>chmod 755 <filename>/var/spool/mqueue</filename></command>
+ as root to fix this problem. This will allow any process running on your
+ machine the ability to <emphasis>read</emphasis> the
+ <filename>/var/spool/mqueue</filename> directory.
+ </para>
+ </section>
+
+ <section id="trbl-relogin-everyone">
+ <title>Everybody is constantly being forced to relogin</title>
+
+ <para>The most-likely cause is that the <quote>cookiepath</quote> parameter
+ is not set correctly in the Bugzilla configuration. You can change this (if
+ you're a Bugzilla administrator) from the editparams.cgi page via the web interface.
+ </para>
+
+ <para>The value of the cookiepath parameter should be the actual directory
+ containing your Bugzilla installation, <emphasis>as seen by the end-user's
+ web browser</emphasis>. Leading and trailing slashes are mandatory. You can
+ also set the cookiepath to any directory which is a parent of the Bugzilla
+ directory (such as '/', the root directory). But you can't put something
+ that isn't at least a partial match or it won't work. What you're actually
+ doing is restricting the end-user's browser to sending the cookies back only
+ to that directory.
+ </para>
+
+ <para>How do you know if you want your specific Bugzilla directory or the
+ whole site?
+ </para>
+
+ <para>If you have only one Bugzilla running on the server, and you don't
+ mind having other applications on the same server with it being able to see
+ the cookies (you might be doing this on purpose if you have other things on
+ your site that share authentication with Bugzilla), then you'll want to have
+ the cookiepath set to "/", or to a sufficiently-high enough directory that
+ all of the involved apps can see the cookies.
+ </para>
+
+ <example id="trbl-relogin-everyone-share">
+ <title>Examples of urlbase/cookiepath pairs for sharing login cookies</title>
+
+ <blockquote>
+ <literallayout>
+ urlbase is <ulink url="http://bugzilla.mozilla.org/"/>
+ cookiepath is /
+
+ urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/>
+ but you have http://tools.mysite.tld/someotherapp/ which shares
+ authentication with your Bugzilla
+ cookiepath is /
+ </literallayout>
+ </blockquote>
+ </example>
+
+ <para>On the other hand, if you have more than one Bugzilla running on the
+ server (some people do - we do on landfill) then you need to have the
+ cookiepath restricted enough so that the different Bugzillas don't
+ confuse their cookies with one another.
+ </para>
+
+
+ <example id="trbl-relogin-everyone-restrict">
+ <title>Examples of urlbase/cookiepath pairs to restrict the login cookie</title>
+ <blockquote>
+ <literallayout>
+ urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/>
+ cookiepath is /bugzilla-tip/
+
+ urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/>
+ cookiepath is /bugzilla-2.16-branch/
+ </literallayout>
+ </blockquote>
+ </example>
+
+ <para>If you had cookiepath set to <quote>/</quote> at any point in the
+ past and need to set it to something more restrictive
+ (i.e. <quote>/bugzilla/</quote>), you can safely do this without
+ requiring users to delete their Bugzilla-related cookies in their
+ browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5).
+ </para>
+ </section>
+
+ <section id="trbl-relogin-some">
+ <title>Some users are constantly being forced to relogin</title>
+
+ <para>First, make sure cookies are enabled in the user's browser.
+ </para>
+
+ <para>If that doesn't fix the problem, it may be that the user's ISP
+ implements a rotating proxy server. This causes the user's effective IP
+ address (the address which the Bugzilla server perceives him coming from)
+ to change periodically. Since Bugzilla cookies are tied to a specific IP
+ address, each time the effective address changes, the user will have to
+ log in again.
+ </para>
+
+ <para>If you are using 2.18 (or later), there is a
+ parameter called <quote>loginnetmask</quote>, which you can use to set
+ the number of bits of the user's IP address to require to be matched when
+ authenticating the cookies. If you set this to something less than 32,
+ then the user will be given a checkbox for <quote>Restrict this login to
+ my IP address</quote> on the login screen, which defaults to checked. If
+ they leave the box checked, Bugzilla will behave the same as it did
+ before, requiring an exact match on their IP address to remain logged in.
+ If they uncheck the box, then only the left side of their IP address (up
+ to the number of bits you specified in the parameter) has to match to
+ remain logged in.
+ </para>
+
+ </section>
+
+ <section id="trbl-index">
+ <title><filename>index.cgi</filename> doesn't show up unless specified in the URL</title>
+ <para>
+ You probably need to set up your web server in such a way that it
+ will serve the index.cgi page as an index page.
+ </para>
+ <para>
+ If you are using Apache, you can do this by adding
+ <filename>index.cgi</filename> to the end of the
+ <computeroutput>DirectoryIndex</computeroutput> line
+ as mentioned in <xref linkend="http-apache"/>.
+ </para>
+
+ </section>
+
+ <section id="trbl-passwd-encryption">
+ <title>
+ checksetup.pl reports "Client does not support authentication protocol
+ requested by server..."
+ </title>
+
+ <para>
+ This error is occurring because you are using the new password
+ encryption that comes with MySQL 4.1, while your
+ <filename>DBD::mysql</filename> module was compiled against an
+ older version of MySQL. If you recompile <filename>DBD::mysql</filename>
+ against the current MySQL libraries (or just obtain a newer version
+ of this module) then the error may go away.
+ </para>
+
+ <para>
+ If that does not fix the problem, or if you cannot recompile the
+ existing module (e.g. you're running Windows) and/or don't want to
+ replace it (e.g. you want to keep using a packaged version), then a
+ workaround is available from the MySQL docs:
+ <ulink url="http://dev.mysql.com/doc/mysql/en/Old_client.html"/>
+ </para>
+
+ </section>
+
+</appendix>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End: -->
+
+
--- /dev/null
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
+
+<chapter id="using">
+ <title>Using Bugzilla</title>
+
+ <section id="using-intro">
+ <title>Introduction</title>
+ <para>This section contains information for end-users of Bugzilla. There
+ is a Bugzilla test installation, called
+ <ulink url="http://landfill.bugzilla.org/">Landfill</ulink>, which you are
+ welcome to play with (if it's up). However, not all of the Bugzilla
+ installations there will necessarily have all Bugzilla features enabled,
+ and different installations run different versions, so some things may not
+ quite work as this document describes.</para>
+
+ <para>
+ Frequently Asked Questions (FAQ) are available and answered on
+ <ulink url="http://wiki.mozilla.org/Bugzilla:FAQ">wiki.mozilla.org</ulink>.
+ They may cover some questions you have which are left unanswered.
+ </para>
+ </section>
+
+ <section id="myaccount">
+ <title>Create a Bugzilla Account</title>
+
+ <para>If you want to use Bugzilla, first you need to create an account.
+ Consult with the administrator responsible for your installation of
+ Bugzilla for the URL you should use to access it. If you're
+ test-driving Bugzilla, use this URL:
+ <ulink url="&landfillbase;"/>.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ On the home page <filename>index.cgi</filename>, click the
+ <quote>Open a new Bugzilla account</quote> link, or the
+ <quote>New Account</quote> link available in the footer of pages.
+ Now enter your email address, then click the <quote>Send</quote>
+ button.
+ </para>
+
+ <note>
+ <para>
+ If none of these links is available, this means that the
+ administrator of the installation has disabled self-registration.
+ This means that only an administrator can create accounts
+ for other users. One reason could be that this installation is
+ private.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ Also, if only some users are allowed to create an account on
+ the installation, you may see these links but your registration
+ may fail if your email address doesn't match the ones accepted
+ by the installation. This is another way to restrict who can
+ access and edit bugs in this installation.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ Within moments, and if your registration is accepted, you should
+ receive an email to the address you provided, which contains your
+ login name (generally the same as the email address), and two URLs
+ with a token (a random string generated by the installation) to
+ confirm, respectively cancel, your registration. This is a way to
+ prevent users from abusing the generation of user accounts, for
+ instance by entering inexistent email addresses, or email addresses
+ which do not belong to them.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default, you have 3 days to confirm your registration. Past this
+ timeframe, the token is invalidated and the registration is
+ automatically canceled. You can also cancel this registration sooner
+ by using the appropriate URL in the email you got.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you confirm your registration, Bugzilla will ask you your real name
+ (optional, but recommended) and your password, which must be between
+ 3 and 16 characters long.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Now all you need to do is to click the <quote>Log In</quote>
+ link in the footer at the bottom of the page in your browser,
+ enter your email address and password you just chose into the
+ login form, and click the <quote>Log in</quote> button.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ You are now logged in. Bugzilla uses cookies to remember you are
+ logged in so, unless you have cookies disabled or your IP address changes,
+ you should not have to log in again during your session.
+ </para>
+ </section>
+
+ <section id="bug_page">
+ <title>Anatomy of a Bug</title>
+
+ <para>The core of Bugzilla is the screen which displays a particular
+ bug. It's a good place to explain some Bugzilla concepts.
+ <ulink
+ url="&landfillbase;show_bug.cgi?id=1">
+ Bug 1 on Landfill</ulink>
+
+ is a good example. Note that the labels for most fields are hyperlinks;
+ clicking them will take you to context-sensitive help on that
+ particular field. Fields marked * may not be present on every
+ installation of Bugzilla.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ <emphasis>Product and Component</emphasis>:
+ Bugs are divided up by Product and Component, with a Product
+ having one or more Components in it. For example,
+ bugzilla.mozilla.org's "Bugzilla" Product is composed of several
+ Components:
+ <simplelist>
+ <member>
+ <emphasis>Administration:</emphasis>
+ Administration of a Bugzilla installation.</member>
+
+ <member>
+ <emphasis>Bugzilla-General:</emphasis>
+ Anything that doesn't fit in the other components, or spans
+ multiple components.</member>
+
+ <member>
+ <emphasis>Creating/Changing Bugs:</emphasis>
+ Creating, changing, and viewing bugs.</member>
+
+ <member>
+ <emphasis>Documentation:</emphasis>
+ The Bugzilla documentation, including The Bugzilla Guide.</member>
+
+ <member>
+ <emphasis>Email:</emphasis>
+ Anything to do with email sent by Bugzilla.</member>
+
+ <member>
+ <emphasis>Installation:</emphasis>
+ The installation process of Bugzilla.</member>
+
+ <member>
+ <emphasis>Query/Buglist:</emphasis>
+ Anything to do with searching for bugs and viewing the
+ buglists.</member>
+
+ <member>
+ <emphasis>Reporting/Charting:</emphasis>
+ Getting reports from Bugzilla.</member>
+
+ <member>
+ <emphasis>User Accounts:</emphasis>
+ Anything about managing a user account from the user's perspective.
+ Saved queries, creating accounts, changing passwords, logging in,
+ etc.</member>
+
+ <member>
+ <emphasis>User Interface:</emphasis>
+ General issues having to do with the user interface cosmetics (not
+ functionality) including cosmetic issues, HTML templates,
+ etc.</member>
+ </simplelist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Status and Resolution:</emphasis>
+
+ These define exactly what state the bug is in - from not even
+ being confirmed as a bug, through to being fixed and the fix
+ confirmed by Quality Assurance. The different possible values for
+ Status and Resolution on your installation should be documented in the
+ context-sensitive help for those items.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Assigned To:</emphasis>
+ The person responsible for fixing the bug.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*QA Contact:</emphasis>
+ The person responsible for quality assurance on this bug.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*URL:</emphasis>
+ A URL associated with the bug, if any.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Summary:</emphasis>
+ A one-sentence summary of the problem.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Status Whiteboard:</emphasis>
+ (a.k.a. Whiteboard) A free-form text area for adding short notes
+ and tags to a bug.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Keywords:</emphasis>
+ The administrator can define keywords which you can use to tag and
+ categorise bugs - e.g. The Mozilla Project has keywords like crash
+ and regression.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Platform and OS:</emphasis>
+ These indicate the computing environment where the bug was
+ found.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Version:</emphasis>
+ The "Version" field is usually used for versions of a product which
+ have been released, and is set to indicate which versions of a
+ Component have the particular problem the bug report is
+ about.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Priority:</emphasis>
+ The bug assignee uses this field to prioritize his or her bugs.
+ It's a good idea not to change this on other people's bugs.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Severity:</emphasis>
+ This indicates how severe the problem is - from blocker
+ ("application unusable") to trivial ("minor cosmetic issue"). You
+ can also use this field to indicate whether a bug is an enhancement
+ request.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Target:</emphasis>
+ (a.k.a. Target Milestone) A future version by which the bug is to
+ be fixed. e.g. The Bugzilla Project's milestones for future
+ Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not
+ restricted to numbers, thought - you can use any text strings, such
+ as dates.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Reporter:</emphasis>
+ The person who filed the bug.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>CC list:</emphasis>
+ A list of people who get mail when the bug changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Time Tracking:</emphasis>
+ This form can be used for time tracking.
+ To use this feature, you have to be blessed group membership
+ specified by the <quote>timetrackinggroup</quote> parameter.
+ <simplelist>
+ <member>
+ <emphasis>Orig. Est.:</emphasis>
+ This field shows the original estimated time.</member>
+
+ <member>
+ <emphasis>Current Est.:</emphasis>
+ This field shows the current estimated time.
+ This number is calculated from <quote>Hours Worked</quote>
+ and <quote>Hours Left</quote>.</member>
+
+ <member>
+ <emphasis>Hours Worked:</emphasis>
+ This field shows the number of hours worked.</member>
+
+ <member>
+ <emphasis>Hours Left:</emphasis>
+ This field shows the <quote>Current Est.</quote> -
+ <quote>Hours Worked</quote>.
+ This value + <quote>Hours Worked</quote> will become the
+ new Current Est.</member>
+
+ <member>
+ <emphasis>%Complete:</emphasis>
+ This field shows what percentage of the task is complete.</member>
+
+ <member>
+ <emphasis>Gain:</emphasis>
+ This field shows the number of hours that the bug is ahead of the
+ <quote>Orig. Est.</quote>.</member>
+
+ <member>
+ <emphasis>Deadline:</emphasis>
+ This field shows the deadline for this bug.</member>
+ </simplelist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Attachments:</emphasis>
+ You can attach files (e.g. testcases or patches) to bugs. If there
+ are any attachments, they are listed in this section. Attachments are
+ normally stored in the Bugzilla database, unless they are marked as
+ Big Files, which are stored directly on disk.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Dependencies:</emphasis>
+ If this bug cannot be fixed unless other bugs are fixed (depends
+ on), or this bug stops other bugs being fixed (blocks), their
+ numbers are recorded here.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>*Votes:</emphasis>
+ Whether this bug has any votes.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Additional Comments:</emphasis>
+ You can add your two cents to the bug discussion here, if you have
+ something worthwhile to say.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="lifecycle">
+ <title>Life Cycle of a Bug</title>
+
+ <para>
+ The life cycle, also known as work flow, of a bug is currently hardcoded
+ into Bugzilla. <xref linkend="lifecycle-image"/> contains a graphical
+ representation of this life cycle. If you wish to customize this image for
+ your site, the <ulink url="../images/bzLifecycle.xml">diagram file</ulink>
+ is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink>
+ native XML format.
+ </para>
+
+ <figure id="lifecycle-image">
+ <title>Lifecycle of a Bugzilla Bug</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../images/bzLifecycle.png" scale="66" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section id="query">
+ <title>Searching for Bugs</title>
+
+ <para>The Bugzilla Search page is the interface where you can find
+ any bug report, comment, or patch currently in the Bugzilla system. You
+ can play with it here:
+ <ulink url="&landfillbase;query.cgi"/>.</para>
+
+ <para>The Search page has controls for selecting different possible
+ values for all of the fields in a bug, as described above. For some
+ fields, multiple values can be selected. In those cases, Bugzilla
+ returns bugs where the content of the field matches any one of the selected
+ values. If none is selected, then the field can take any value.</para>
+
+ <para>
+ After a search is run, you can save it as a Saved Search, which
+ will appear in the page footer. If you are in the group defined
+ by the "querysharegroup" parameter, you may share your queries
+ with other users, see <xref linkend="savedsearches"/> for more details.
+ </para>
+
+ <section id="boolean">
+ <title>Boolean Charts</title>
+ <para>
+ Highly advanced querying is done using Boolean Charts.
+ </para>
+ <para>
+ The boolean charts further restrict the set of results
+ returned by a query. It is possible to search for bugs
+ based on elaborate combinations of criteria.
+ </para>
+ <para>
+ The simplest boolean searches have only one term. These searches
+ permit the selected left <emphasis>field</emphasis>
+ to be compared using a
+ selectable <emphasis>operator</emphasis> to a
+ specified <emphasis>value.</emphasis>
+ Using the "And," "Or," and "Add Another Boolean Chart" buttons,
+ additional terms can be included in the query, further
+ altering the list of bugs returned by the query.
+ </para>
+ <para>
+ There are three fields in each row of a boolean search.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Field:</emphasis>
+ the items being searched
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Operator:</emphasis>
+ the comparison operator
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Value:</emphasis>
+ the value to which the field is being compared
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="pronouns">
+ <title>Pronoun Substitution</title>
+ <para>
+ Sometimes, a query needs to compare a user-related field
+ (such as ReportedBy) with a role-specific user (such as the
+ user running the query or the user to whom each bug is assigned).
+ When the operator is either "equals" or "notequals", the value
+ can be "%reporter%", "%assignee%", "%qacontact%", or "%user%".
+ The user pronoun
+ refers to the user who is executing the query or, in the case
+ of whining reports, the user who will be the recipient
+ of the report. The reporter, assignee, and qacontact
+ pronouns refer to the corresponding fields in the bug.
+ </para>
+ <para>
+ Boolean charts also let you type a group name in any user-related
+ field if the operator is either "equals", "notequals" or "anyexact".
+ This will let you query for any member belonging (or not) to the
+ specified group. The group name must be entered following the
+ "%group.foo%" syntax, where "foo" is the group name.
+ So if you are looking for bugs reported by any user being in the
+ "editbugs" group, then you can type "%group.editbugs%".
+ </para>
+ </section>
+ <section id="negation">
+ <title>Negation</title>
+ <para>
+ At first glance, negation seems redundant. Rather than
+ searching for
+ <blockquote>
+ <para>
+ NOT("summary" "contains the string" "foo"),
+ </para>
+ </blockquote>
+ one could search for
+ <blockquote>
+ <para>
+ ("summary" "does not contain the string" "foo").
+ </para>
+ </blockquote>
+ However, the search
+ <blockquote>
+ <para>
+ ("CC" "does not contain the string" "@mozilla.org")
+ </para>
+ </blockquote>
+ would find every bug where anyone on the CC list did not contain
+ "@mozilla.org" while
+ <blockquote>
+ <para>
+ NOT("CC" "contains the string" "@mozilla.org")
+ </para>
+ </blockquote>
+ would find every bug where there was nobody on the CC list who
+ did contain the string. Similarly, the use of negation also permits
+ complex expressions to be built using terms OR'd together and then
+ negated. Negation permits queries such as
+ <blockquote>
+ <para>
+ NOT(("product" "equals" "update") OR
+ ("component" "equals" "Documentation"))
+ </para>
+ </blockquote>
+ to find bugs that are neither
+ in the update product or in the documentation component or
+ <blockquote>
+ <para>
+ NOT(("commenter" "equals" "%assignee%") OR
+ ("component" "equals" "Documentation"))
+ </para>
+ </blockquote>
+ to find non-documentation
+ bugs on which the assignee has never commented.
+ </para>
+ </section>
+ <section id="multiplecharts">
+ <title>Multiple Charts</title>
+ <para>
+ The terms within a single row of a boolean chart are all
+ constraints on a single piece of data. If you are looking for
+ a bug that has two different people cc'd on it, then you need
+ to use two boolean charts. A search for
+ <blockquote>
+ <para>
+ ("cc" "contains the string" "foo@") AND
+ ("cc" "contains the string" "@mozilla.org")
+ </para>
+ </blockquote>
+ would return only bugs with "foo@mozilla.org" on the cc list.
+ If you wanted bugs where there is someone on the cc list
+ containing "foo@" and someone else containing "@mozilla.org",
+ then you would need two boolean charts.
+ <blockquote>
+ <para>
+ First chart: ("cc" "contains the string" "foo@")
+ </para>
+ <para>
+ Second chart: ("cc" "contains the string" "@mozilla.org")
+ </para>
+ </blockquote>
+ The bugs listed will be only the bugs where ALL the charts are true.
+ </para>
+ </section>
+ </section>
+
+ <section id="quicksearch">
+ <title>Quicksearch</title>
+
+ <para>
+ Quicksearch is a single-text-box query tool which uses
+ metacharacters to indicate what is to be searched. For example, typing
+ "<literal>foo|bar</literal>"
+ into Quicksearch would search for "foo" or "bar" in the
+ summary and status whiteboard of a bug; adding
+ "<literal>:BazProduct</literal>" would
+ search only in that product.
+ You can use it to find a bug by its number or its alias, too.
+ </para>
+
+ <para>
+ You'll find the Quicksearch box in Bugzilla's footer area.
+ On Bugzilla's front page, there is an additional
+ <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink>
+ link which details how to use it.
+ </para>
+ </section>
+ <section id="casesensitivity">
+ <title>Case Sensitivity in Searches</title>
+ <para>
+ Bugzilla queries are case-insensitive and accent-insensitive, when
+ used with either MySQL or Oracle databases. When using Bugzilla with
+ PostgreSQL, however, some queries are case-sensitive. This is due to
+ the way PostgreSQL handles case and accent sensitivity.
+ </para>
+ </section>
+ <section id="list">
+ <title>Bug Lists</title>
+
+ <para>If you run a search, a list of matching bugs will be returned.
+ </para>
+
+ <para>The format of the list is configurable. For example, it can be
+ sorted by clicking the column headings. Other useful features can be
+ accessed using the links at the bottom of the list:
+ <simplelist>
+ <member>
+ <emphasis>Long Format:</emphasis>
+
+ this gives you a large page with a non-editable summary of the fields
+ of each bug.</member>
+
+ <member>
+ <emphasis>XML:</emphasis>
+
+ get the buglist in the XML format.</member>
+
+ <member>
+ <emphasis>CSV:</emphasis>
+
+ get the buglist as comma-separated values, for import into e.g.
+ a spreadsheet.</member>
+
+ <member>
+ <emphasis>Feed:</emphasis>
+
+ get the buglist as an Atom feed. Copy this link into your
+ favorite feed reader. If you are using Firefox, you can also
+ save the list as a live bookmark by clicking the live bookmark
+ icon in the status bar. To limit the number of bugs in the feed,
+ add a limit=n parameter to the URL.</member>
+
+ <member>
+ <emphasis>iCalendar:</emphasis>
+
+ Get the buglist as an iCalendar file. Each bug is represented as a
+ to-do item in the imported calendar.</member>
+
+ <member>
+ <emphasis>Change Columns:</emphasis>
+
+ change the bug attributes which appear in the list.</member>
+
+ <member>
+ <emphasis>Change several bugs at once:</emphasis>
+
+ If your account is sufficiently empowered, and more than one bug
+ appear in the bug list, this link is displayed which lets you make
+ the same change to all the bugs in the list - for example, changing
+ their assignee.</member>
+
+ <member>
+ <emphasis>Send mail to bug assignees:</emphasis>
+
+ If more than one bug appear in the bug list and there are at least
+ two distinct bug assignees, this links is displayed which lets you
+ easily send a mail to the assignees of all bugs on the list.</member>
+
+ <member>
+ <emphasis>Edit Search:</emphasis>
+
+ If you didn't get exactly the results you were looking for, you can
+ return to the Query page through this link and make small revisions
+ to the query you just made so you get more accurate results.</member>
+
+ <member>
+ <emphasis>Remember Search As:</emphasis>
+
+ You can give a search a name and remember it; a link will appear
+ in your page footer giving you quick access to run it again later.
+ </member>
+ </simplelist>
+ </para>
+
+ <para>
+ If you would like to access the bug list from another program
+ it is often useful to have the list returned in something other
+ than HTML. By adding the ctype=type parameter into the bug list URL
+ you can specify several alternate formats. Besides the types described
+ above, the following formats are also supported: ECMAScript, also known
+ as JavaScript (ctype=js), and Resource Description Framework RDF/XML
+ (ctype=rdf).
+ </para>
+ </section>
+
+ <section id="individual-buglists">
+ <title>Adding/removing tags to/from bugs</title>
+ <para>
+ You can add and remove tags from individual bugs, which let you find and
+ manage them more easily. Creating a new tag automatically generates a saved
+ search - whose name is the name of the tag - which lists bugs with this tag.
+ This saved search will be displayed in the footer of pages by default, as
+ all other saved searches. The main difference between tags and normal saved
+ searches is that saved searches, as described in the previous section, are
+ stored in the form of a list of matching criteria, while the saved search
+ generated by tags is a list of bug numbers. Consequently, you can easily
+ edit this list by either adding or removing tags from bugs. To enable this
+ feature, you have to turn on the <quote>Enable tags for bugs</quote> user
+ preference, see <xref linkend="userpreferences" />. This feature is disabled
+ by default.
+ </para>
+
+ <para>
+ This feature is useful when you want to keep track of several bugs, but
+ for different reasons. Instead of adding yourself to the CC list of all
+ these bugs and mixing all these reasons, you can now store these bugs in
+ separate lists, e.g. <quote>Keep in mind</quote>, <quote>Interesting bugs</quote>,
+ or <quote>Triage</quote>. One big advantage of this way to manage bugs
+ is that you can easily add or remove bugs one by one, which is not
+ possible to do with saved searches without having to edit the search
+ criteria again.
+ </para>
+ </section>
+ </section>
+
+ <section id="bugreports">
+ <title>Filing Bugs</title>
+
+ <section id="fillingbugs">
+ <title>Reporting a New Bug</title>
+
+ <para>Years of bug writing experience has been distilled for your
+ reading pleasure into the
+ <ulink
+ url="&landfillbase;page.cgi?id=bug-writing.html">
+ Bug Writing Guidelines</ulink>.
+ While some of the advice is Mozilla-specific, the basic principles of
+ reporting Reproducible, Specific bugs, isolating the Product you are
+ using, the Version of the Product, the Component which failed, the
+ Hardware Platform, and Operating System you were using at the time of
+ the failure go a long way toward ensuring accurate, responsible fixes
+ for the bug that bit you.</para>
+
+ <para>The procedure for filing a bug is as follows:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Click the <quote>New</quote> link available in the footer
+ of pages, or the <quote>Enter a new bug report</quote> link
+ displayed on the home page of the Bugzilla installation.
+ </para>
+
+ <note>
+ <para>
+ If you want to file a test bug to see how Bugzilla works,
+ you can do it on one of our test installations on
+ <ulink url="&landfillbase;">Landfill</ulink>.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ You first have to select the product in which you found a bug.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You now see a form where you can specify the component (part of
+ the product which is affected by the bug you discovered; if you have
+ no idea, just select <quote>General</quote> if such a component exists),
+ the version of the program you were using, the Operating System and
+ platform your program is running on and the severity of the bug (if the
+ bug you found crashes the program, it's probably a major or a critical
+ bug; if it's a typo somewhere, that's something pretty minor; if it's
+ something you would like to see implemented, then that's an enhancement).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You now have to give a short but descriptive summary of the bug you found.
+ <quote>My program is crashing all the time</quote> is a very poor summary
+ and doesn't help developers at all. Try something more meaningful or
+ your bug will probably be ignored due to a lack of precision.
+ The next step is to give a very detailed list of steps to reproduce
+ the problem you encountered. Try to limit these steps to a minimum set
+ required to reproduce the problem. This will make the life of
+ developers easier, and the probability that they consider your bug in
+ a reasonable timeframe will be much higher.
+ </para>
+
+ <note>
+ <para>
+ Try to make sure that everything in the summary is also in the first
+ comment. Summaries are often updated and this will ensure your original
+ information is easily accessible.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ As you file the bug, you can also attach a document (testcase, patch,
+ or screenshot of the problem).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Depending on the Bugzilla installation you are using and the product in
+ which you are filing the bug, you can also request developers to consider
+ your bug in different ways (such as requesting review for the patch you
+ just attached, requesting your bug to block the next release of the
+ product, and many other product specific requests).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Now is a good time to read your bug report again. Remove all misspellings,
+ otherwise your bug may not be found by developers running queries for some
+ specific words, and so your bug would not get any attention.
+ Also make sure you didn't forget any important information developers
+ should know in order to reproduce the problem, and make sure your
+ description of the problem is explicit and clear enough.
+ When you think your bug report is ready to go, the last step is to
+ click the <quote>Commit</quote> button to add your report into the database.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ You do not need to put "any" or similar strings in the URL field.
+ If there is no specific URL associated with the bug, leave this
+ field blank.
+ </para>
+
+ <para>If you feel a bug you filed was incorrectly marked as a
+ DUPLICATE of another, please question it in your bug, not
+ the bug it was duped to. Feel free to CC the person who duped it
+ if they are not already CCed.
+ </para>
+ </section>
+
+ <section id="cloningbugs">
+ <title>Clone an Existing Bug</title>
+
+ <para>
+ Starting with version 2.20, Bugzilla has a feature that allows you
+ to clone an existing bug. The newly created bug will inherit
+ most settings from the old bug. This allows you to track more
+ easily similar concerns in a new bug. To use this, go to the bug
+ that you want to clone, then click the <quote>Clone This Bug</quote>
+ link on the bug page. This will take you to the <quote>Enter Bug</quote>
+ page that is filled with the values that the old bug has.
+ You can change those values and/or texts if needed.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="attachments">
+ <title>Attachments</title>
+
+ <para>
+ You should use attachments, rather than comments, for large chunks of ASCII
+ data, such as trace, debugging output files, or log files. That way, it
+ doesn't bloat the bug for everyone who wants to read it, and cause people to
+ receive fat, useless mails.
+ </para>
+
+ <para>You should make sure to trim screenshots. There's no need to show the
+ whole screen if you are pointing out a single-pixel problem.
+ </para>
+
+ <para>Bugzilla stores and uses a Content-Type for each attachment
+ (e.g. text/html). To download an attachment as a different
+ Content-Type (e.g. application/xhtml+xml), you can override this
+ using a 'content_type' parameter on the URL, e.g.
+ <filename>&content_type=text/plain</filename>.
+ </para>
+
+ <para>
+ If you have a really large attachment, something that does not need to
+ be recorded forever (as most attachments are), or something that is too
+ big for your database, you can mark your attachment as a
+ <quote>Big File</quote>, assuming the administrator of the installation
+ has enabled this feature. Big Files are stored directly on disk instead
+ of in the database. The maximum size of a <quote>Big File</quote> is
+ normally larger than the maximum size of a regular attachment. Independently
+ of the storage system used, an administrator can delete these attachments
+ at any time. Nevertheless, if these files are stored in the database, the
+ <quote>allow_attachment_deletion</quote> parameter (which is turned off
+ by default) must be enabled in order to delete them.
+ </para>
+
+ <para>
+ Also, if the administrator turned on the <quote>allow_attach_url</quote>
+ parameter, you can enter the URL pointing to the attachment instead of
+ uploading the attachment itself. For example, this is useful if you want to
+ point to an external application, a website or a very large file. Note that
+ there is no guarantee that the source file will always be available, nor
+ that its content will remain unchanged.
+ </para>
+
+ <section id="patchviewer">
+ <title>Patch Viewer</title>
+
+ <para>Viewing and reviewing patches in Bugzilla is often difficult due to
+ lack of context, improper format and the inherent readability issues that
+ raw patches present. Patch Viewer is an enhancement to Bugzilla designed
+ to fix that by offering increased context, linking to sections, and
+ integrating with Bonsai, LXR and CVS.</para>
+
+ <para>Patch viewer allows you to:</para>
+
+ <simplelist>
+ <member>View patches in color, with side-by-side view rather than trying
+ to interpret the contents of the patch.</member>
+ <member>See the difference between two patches.</member>
+ <member>Get more context in a patch.</member>
+ <member>Collapse and expand sections of a patch for easy
+ reading.</member>
+ <member>Link to a particular section of a patch for discussion or
+ review</member>
+ <member>Go to Bonsai or LXR to see more context, blame, and
+ cross-references for the part of the patch you are looking at</member>
+ <member>Create a rawtext unified format diff out of any patch, no
+ matter what format it came from</member>
+ </simplelist>
+
+ <section id="patchviewer_view">
+ <title>Viewing Patches in Patch Viewer</title>
+ <para>The main way to view a patch in patch viewer is to click on the
+ "Diff" link next to a patch in the Attachments list on a bug. You may
+ also do this within the edit window by clicking the "View Attachment As
+ Diff" button in the Edit Attachment screen.</para>
+ </section>
+
+ <section id="patchviewer_diff">
+ <title>Seeing the Difference Between Two Patches</title>
+ <para>To see the difference between two patches, you must first view the
+ newer patch in Patch Viewer. Then select the older patch from the
+ dropdown at the top of the page ("Differences between [dropdown] and
+ this patch") and click the "Diff" button. This will show you what
+ is new or changed in the newer patch.</para>
+ </section>
+
+ <section id="patchviewer_context">
+ <title>Getting More Context in a Patch</title>
+ <para>To get more context in a patch, you put a number in the textbox at
+ the top of Patch Viewer ("Patch / File / [textbox]") and hit enter.
+ This will give you that many lines of context before and after each
+ change. Alternatively, you can click on the "File" link there and it
+ will show each change in the full context of the file. This feature only
+ works against files that were diffed using "cvs diff".</para>
+ </section>
+
+ <section id="patchviewer_collapse">
+ <title>Collapsing and Expanding Sections of a Patch</title>
+ <para>To view only a certain set of files in a patch (for example, if a
+ patch is absolutely huge and you want to only review part of it at a
+ time), you can click the "(+)" and "(-)" links next to each file (to
+ expand it or collapse it). If you want to collapse all files or expand
+ all files, you can click the "Collapse All" and "Expand All" links at the
+ top of the page.</para>
+ </section>
+
+ <section id="patchviewer_link">
+ <title>Linking to a Section of a Patch</title>
+ <para>To link to a section of a patch (for example, if you want to be
+ able to give someone a URL to show them which part you are talking
+ about) you simply click the "Link Here" link on the section header. The
+ resulting URL can be copied and used in discussion.</para>
+ </section>
+
+ <section id="patchviewer_bonsai_lxr">
+ <title>Going to Bonsai and LXR</title>
+ <para>To go to Bonsai to get blame for the lines you are interested in,
+ you can click the "Lines XX-YY" link on the section header you are
+ interested in. This works even if the patch is against an old
+ version of the file, since Bonsai stores all versions of the file.</para>
+
+ <para>To go to LXR, you click on the filename on the file header
+ (unfortunately, since LXR only does the most recent version, line
+ numbers are likely to rot).</para>
+ </section>
+
+ <section id="patchviewer_unified_diff">
+ <title>Creating a Unified Diff</title>
+ <para>If the patch is not in a format that you like, you can turn it
+ into a unified diff format by clicking the "Raw Unified" link at the top
+ of the page.</para>
+ </section>
+ </section>
+ </section>
+
+ <section id="hintsandtips">
+ <title>Hints and Tips</title>
+
+ <para>This section distills some Bugzilla tips and best practices
+ that have been developed.</para>
+
+ <section>
+ <title>Autolinkification</title>
+ <para>Bugzilla comments are plain text - so typing <U> will
+ produce less-than, U, greater-than rather than underlined text.
+ However, Bugzilla will automatically make hyperlinks out of certain
+ sorts of text in comments. For example, the text
+ "http://www.bugzilla.org" will be turned into a link:
+ <ulink url="http://www.bugzilla.org"/>.
+ Other strings which get linkified in the obvious manner are:
+ <simplelist>
+ <member>bug 12345</member>
+ <member>comment 7</member>
+ <member>bug 23456, comment 53</member>
+ <member>attachment 4321</member>
+ <member>mailto:george@example.com</member>
+ <member>george@example.com</member>
+ <member>ftp://ftp.mozilla.org</member>
+ <member>Most other sorts of URL</member>
+ </simplelist>
+ </para>
+
+ <para>A corollary here is that if you type a bug number in a comment,
+ you should put the word "bug" before it, so it gets autolinkified
+ for the convenience of others.
+ </para>
+ </section>
+
+ <section id="commenting">
+ <title>Comments</title>
+
+ <para>If you are changing the fields on a bug, only comment if
+ either you have something pertinent to say, or Bugzilla requires it.
+ Otherwise, you may spam people unnecessarily with bug mail.
+ To take an example: a user can set up their account to filter out messages
+ where someone just adds themselves to the CC field of a bug
+ (which happens a lot.) If you come along, add yourself to the CC field,
+ and add a comment saying "Adding self to CC", then that person
+ gets a pointless piece of mail they would otherwise have avoided.
+ </para>
+
+ <para>
+ Don't use sigs in comments. Signing your name ("Bill") is acceptable,
+ if you do it out of habit, but full mail/news-style
+ four line ASCII art creations are not.
+ </para>
+ </section>
+
+ <section id="comment-wrapping">
+ <title>Server-Side Comment Wrapping</title>
+ <para>
+ Bugzilla stores comments unwrapped and wraps them at display time. This
+ ensures proper wrapping in all browsers. Lines beginning with the ">"
+ character are assumed to be quotes, and are not wrapped.
+ </para>
+ </section>
+
+ <section id="dependencytree">
+ <title>Dependency Tree</title>
+
+ <para>
+ On the <quote>Dependency tree</quote> page linked from each bug
+ page, you can see the dependency relationship from the bug as a
+ tree structure.
+ </para>
+
+ <para>
+ You can change how much depth to show, and you can hide resolved bugs
+ from this page. You can also collaps/expand dependencies for
+ each bug on the tree view, using the [-]/[+] buttons that appear
+ before its summary. This option is not available for terminal
+ bugs in the tree (that don't have further dependencies).
+ </para>
+ </section>
+ </section>
+
+ <section id="timetracking">
+ <title>Time Tracking Information</title>
+
+ <para>
+ Users who belong to the group specified by the <quote>timetrackinggroup</quote>
+ parameter have access to time-related fields. Developers can see
+ deadlines and estimated times to fix bugs, and can provide time spent
+ on these bugs.
+ </para>
+
+ <para>
+ At any time, a summary of the time spent by developers on bugs is
+ accessible either from bug lists when clicking the <quote>Time Summary</quote>
+ button or from individual bugs when clicking the <quote>Summarize time</quote>
+ link in the time tracking table. The <filename>summarize_time.cgi</filename>
+ page lets you view this information either per developer or per bug,
+ and can be split on a month basis to have greater details on how time
+ is spent by developers.
+ </para>
+
+ <para>
+ As soon as a bug is marked as RESOLVED, the remaining time expected
+ to fix the bug is set to zero. This lets QA people set it again for
+ their own usage, and it will be set to zero again when the bug will
+ be marked as CLOSED.
+ </para>
+ </section>
+
+ <section id="userpreferences">
+ <title>User Preferences</title>
+
+ <para>
+ Once logged in, you can customize various aspects of
+ Bugzilla via the "Preferences" link in the page footer.
+ The preferences are split into five tabs:</para>
+
+ <section id="generalpreferences" xreflabel="General Preferences">
+ <title>General Preferences</title>
+
+ <para>
+ This tab allows you to change several default settings of Bugzilla.
+ </para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Bugzilla's general appearance (skin) - select which skin to use.
+ Bugzilla supports adding custom skins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Quote the associated comment when you click on its reply link - sets
+ the behavior of the comment "Reply" link. Options include quoting the
+ full comment, just reference the comment number, or turn the link off.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Language used in email - select which language email will be sent in,
+ from the list of available languages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ After changing a bug - This controls what page is displayed after
+ changes to a bug are submitted. The options include to show the bug
+ just modified, to show the next bug in your list, or to do nothing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enable tags for bugs - turn bug tagging on or off.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Zoom textareas large when in use (requires JavaScript) - enable or
+ disable the automatic expanding of text areas when text is being
+ entered into them.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Field separator character for CSV files -
+ Select between a comma and semi-colon for exported CSV bug lists.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Automatically add me to the CC list of bugs I change - set default
+ behavior of CC list. Options include "Always", "Never", and "Only
+ if I have no role on them".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When viewing a bug, show comments in this order -
+ controls the order of comments. Options include "Oldest
+ to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the
+ bug description at the top".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Show a quip at the top of each bug list - controls
+ whether a quip will be shown on the Bug list page.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="emailpreferences">
+ <title>Email Preferences</title>
+
+ <para>
+ This tab allows you to enable or disable email notification on
+ specific events.
+ </para>
+
+ <para>
+ In general, users have almost complete control over how much (or
+ how little) email Bugzilla sends them. If you want to receive the
+ maximum amount of email possible, click the <quote>Enable All
+ Mail</quote> button. If you don't want to receive any email from
+ Bugzilla at all, click the <quote>Disable All Mail</quote> button.
+ </para>
+
+ <note>
+ <para>
+ A Bugzilla administrator can stop a user from receiving
+ bugmail by clicking the <quote>Bugmail Disabled</quote> checkbox
+ when editing the user account. This is a drastic step
+ best taken only for disabled accounts, as it overrides
+ the user's individual mail preferences.
+ </para>
+ </note>
+
+ <para>
+ There are two global options -- <quote>Email me when someone
+ asks me to set a flag</quote> and <quote>Email me when someone
+ sets a flag I asked for</quote>. These define how you want to
+ receive bugmail with regards to flags. Their use is quite
+ straightforward; enable the checkboxes if you want Bugzilla to
+ send you mail under either of the above conditions.
+ </para>
+
+ <para>
+ If you'd like to set your bugmail to something besides
+ 'Completely ON' and 'Completely OFF', the
+ <quote>Field/recipient specific options</quote> table
+ allows you to do just that. The rows of the table
+ define events that can happen to a bug -- things like
+ attachments being added, new comments being made, the
+ priority changing, etc. The columns in the table define
+ your relationship with the bug:
+ </para>
+
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ Reporter - Where you are the person who initially
+ reported the bug. Your name/account appears in the
+ <quote>Reporter:</quote> field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Assignee - Where you are the person who has been
+ designated as the one responsible for the bug. Your
+ name/account appears in the <quote>Assigned To:</quote>
+ field of the bug.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ QA Contact - You are one of the designated
+ QA Contacts for the bug. Your account appears in the
+ <quote>QA Contact:</quote> text-box of the bug.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ CC - You are on the list CC List for the bug.
+ Your account appears in the <quote>CC:</quote> text box
+ of the bug.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Voter - You have placed one or more votes for the bug.
+ Your account appears only if someone clicks on the
+ <quote>Show votes for this bug</quote> link on the bug.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>
+ Some columns may not be visible for your installation, depending
+ on your site's configuration.
+ </para>
+ </note>
+
+ <para>
+ To fine-tune your bugmail, decide the events for which you want
+ to receive bugmail; then decide if you want to receive it all
+ the time (enable the checkbox for every column), or only when
+ you have a certain relationship with a bug (enable the checkbox
+ only for those columns). For example: if you didn't want to
+ receive mail when someone added themselves to the CC list, you
+ could uncheck all the boxes in the <quote>CC Field Changes</quote>
+ line. As another example, if you never wanted to receive email
+ on bugs you reported unless the bug was resolved, you would
+ un-check all boxes in the <quote>Reporter</quote> column
+ except for the one on the <quote>The bug is resolved or
+ verified</quote> row.
+ </para>
+
+ <note>
+ <para>
+ Bugzilla adds the <quote>X-Bugzilla-Reason</quote> header to
+ all bugmail it sends, describing the recipient's relationship
+ (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug.
+ This header can be used to do further client-side filtering.
+ </para>
+ </note>
+
+ <para>
+ Bugzilla has a feature called <quote>Users Watching</quote>.
+ When you enter one or more comma-delineated user accounts (usually email
+ addresses) into the text entry box, you will receive a copy of all the
+ bugmail those users are sent (security settings permitting).
+ This powerful functionality enables seamless transitions as developers
+ change projects or users go on holiday.
+ </para>
+
+ <note>
+ <para>
+ The ability to watch other users may not be available in all
+ Bugzilla installations. If you don't see this feature, and feel
+ that you need it, speak to your administrator.
+ </para>
+ </note>
+
+ <para>
+ Each user listed in the <quote>Users watching you</quote> field
+ has you listed in their <quote>Users to watch</quote> list
+ and can get bugmail according to your relationship to the bug and
+ their <quote>Field/recipient specific options</quote> setting.
+ </para>
+
+ </section>
+
+ <section id="savedsearches" xreflabel="Saved Searches">
+ <title>Saved Searches</title>
+ <para>
+ On this tab you can view and run any Saved Searches that you have
+ created, and also any Saved Searches that other members of the group
+ defined in the "querysharegroup" parameter have shared.
+ Saved Searches can be added to the page footer from this screen.
+ If somebody is sharing a Search with a group she or he is allowed to
+ <link linkend="groups">assign users to</link>, the sharer may opt to have
+ the Search show up in the footer of the group's direct members by default.
+ </para>
+ </section>
+
+ <section id="accountpreferences" xreflabel="Name and Password">
+ <title>Name and Password</title>
+
+ <para>On this tab, you can change your basic account information,
+ including your password, email address and real name. For security
+ reasons, in order to change anything on this page you must type your
+ <emphasis>current</emphasis> password into the <quote>Password</quote>
+ field at the top of the page.
+ If you attempt to change your email address, a confirmation
+ email is sent to both the old and new addresses, with a link to use to
+ confirm the change. This helps to prevent account hijacking.</para>
+ </section>
+
+ <section id="permissionsettings">
+ <title>Permissions</title>
+
+ <para>
+ This is a purely informative page which outlines your current
+ permissions on this installation of Bugzilla.
+ </para>
+
+ <para>
+ A complete list of permissions is below. Only users with
+ <emphasis>editusers</emphasis> privileges can change the permissions
+ of other users.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ admin
+ </term>
+ <listitem>
+ <para>
+ Indicates user is an Administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ bz_canusewhineatothers
+ </term>
+ <listitem>
+ <para>
+ Indicates user can configure whine reports for other users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ bz_canusewhines
+ </term>
+ <listitem>
+ <para>
+ Indicates user can configure whine reports for self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ bz_sudoers
+ </term>
+ <listitem>
+ <para>
+ Indicates user can perform actions as other users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ bz_sudo_protect
+ </term>
+ <listitem>
+ <para>
+ Indicates user can not be impersonated by other users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ canconfirm
+ </term>
+ <listitem>
+ <para>
+ Indicates user can confirm a bug or mark it a duplicate.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ creategroups
+ </term>
+ <listitem>
+ <para>
+ Indicates user can create and destroy groups.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ editbugs
+ </term>
+ <listitem>
+ <para>
+ Indicates user can edit all bug fields.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ editclassifications
+ </term>
+ <listitem>
+ <para>
+ Indicates user can create, destroy, and edit classifications.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ editcomponents
+ </term>
+ <listitem>
+ <para>
+ Indicates user can create, destroy, and edit components.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ editkeywords
+ </term>
+ <listitem>
+ <para>
+ Indicates user can create, destroy, and edit keywords.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ editusers
+ </term>
+ <listitem>
+ <para>
+ Indicates user can edit or disable users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ tweakparams
+ </term>
+ <listitem>
+ <para>
+ Indicates user can change Parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <note>
+ <para>
+ For more information on how permissions work in Bugzilla (i.e. who can
+ change what), see <xref linkend="cust-change-permissions"/>.
+ </para>
+ </note>
+
+ </section>
+ </section>
+
+
+ <section id="reporting">
+ <title>Reports and Charts</title>
+
+ <para>As well as the standard buglist, Bugzilla has two more ways of
+ viewing sets of bugs. These are the reports (which give different
+ views of the current state of the database) and charts (which plot
+ the changes in particular sets of bugs over time.)</para>
+
+ <section id="reports">
+ <title>Reports</title>
+
+ <para>
+ A report is a view of the current state of the bug database.
+ </para>
+
+ <para>
+ You can run either an HTML-table-based report, or a graphical
+ line/pie/bar-chart-based one. The two have different pages to
+ define them, but are close cousins - once you've defined and
+ viewed a report, you can switch between any of the different
+ views of the data at will.
+ </para>
+
+ <para>
+ Both report types are based on the idea of defining a set of bugs
+ using the standard search interface, and then choosing some
+ aspect of that set to plot on the horizontal and/or vertical axes.
+ You can also get a form of 3-dimensional report by choosing to have
+ multiple images or tables.
+ </para>
+
+ <para>
+ So, for example, you could use the search form to choose "all
+ bugs in the WorldControl product", and then plot their severity
+ against their component to see which component had had the largest
+ number of bad bugs reported against it.
+ </para>
+
+ <para>
+ Once you've defined your parameters and hit "Generate Report",
+ you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie
+ is only available if you didn't define a vertical axis, as pie
+ charts don't have one.) The other controls are fairly self-explanatory;
+ you can change the size of the image if you find text is overwriting
+ other text, or the bars are too thin to see.
+ </para>
+
+ </section>
+
+ <section id="charts">
+ <title>Charts</title>
+
+ <para>
+ A chart is a view of the state of the bug database over time.
+ </para>
+
+ <para>
+ Bugzilla currently has two charting systems - Old Charts and New
+ Charts. Old Charts have been part of Bugzilla for a long time; they
+ chart each status and resolution for each product, and that's all.
+ They are deprecated, and going away soon - we won't say any more
+ about them.
+ New Charts are the future - they allow you to chart anything you
+ can define as a search.
+ </para>
+
+ <note>
+ <para>
+ Both charting forms require the administrator to set up the
+ data-gathering script. If you can't see any charts, ask them whether
+ they have done so.
+ </para>
+ </note>
+
+ <para>
+ An individual line on a chart is called a data set.
+ All data sets are organised into categories and subcategories. The
+ data sets that Bugzilla defines automatically use the Product name
+ as a Category and Component names as Subcategories, but there is no
+ need for you to follow that naming scheme with your own charts if
+ you don't want to.
+ </para>
+
+ <para>
+ Data sets may be public or private. Everyone sees public data sets in
+ the list, but only their creator sees private data sets. Only
+ administrators can make data sets public.
+ No two data sets, even two private ones, can have the same set of
+ category, subcategory and name. So if you are creating private data
+ sets, one idea is to have the Category be your username.
+ </para>
+
+ <section>
+ <title>Creating Charts</title>
+
+ <para>
+ You create a chart by selecting a number of data sets from the
+ list, and pressing Add To List for each. In the List Of Data Sets
+ To Plot, you can define the label that data set will have in the
+ chart's legend, and also ask Bugzilla to Sum a number of data sets
+ (e.g. you could Sum data sets representing RESOLVED, VERIFIED and
+ CLOSED in a particular product to get a data set representing all
+ the resolved bugs in that product.)
+ </para>
+
+ <para>
+ If you've erroneously added a data set to the list, select it
+ using the checkbox and click Remove. Once you add more than one
+ data set, a "Grand Total" line
+ automatically appears at the bottom of the list. If you don't want
+ this, simply remove it as you would remove any other line.
+ </para>
+
+ <para>
+ You may also choose to plot only over a certain date range, and
+ to cumulate the results - that is, to plot each one using the
+ previous one as a baseline, so the top line gives a sum of all
+ the data sets. It's easier to try than to explain :-)
+ </para>
+
+ <para>
+ Once a data set is in the list, one can also perform certain
+ actions on it. For example, one can edit the
+ data set's parameters (name, frequency etc.) if it's one you
+ created or if you are an administrator.
+ </para>
+
+ <para>
+ Once you are happy, click Chart This List to see the chart.
+ </para>
+
+ </section>
+
+ <section id="charts-new-series">
+ <title>Creating New Data Sets</title>
+
+ <para>
+ You may also create new data sets of your own. To do this,
+ click the "create a new data set" link on the Create Chart page.
+ This takes you to a search-like interface where you can define
+ the search that Bugzilla will plot. At the bottom of the page,
+ you choose the category, sub-category and name of your new
+ data set.
+ </para>
+
+ <para>
+ If you have sufficient permissions, you can make the data set public,
+ and reduce the frequency of data collection to less than the default
+ seven days.
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section id="flags">
+ <title>Flags</title>
+
+ <para>
+ A flag is a kind of status that can be set on bugs or attachments
+ to indicate that the bugs/attachments are in a certain state.
+ Each installation can define its own set of flags that can be set
+ on bugs or attachments.
+ </para>
+
+ <para>
+ If your installation has defined a flag, you can set or unset that flag,
+ and if your administrator has enabled requesting of flags, you can submit
+ a request for another user to set the flag.
+ </para>
+
+ <para>
+ To set a flag, select either "+" or "-" from the drop-down menu next to
+ the name of the flag in the "Flags" list. The meaning of these values are
+ flag-specific and thus cannot be described in this documentation,
+ but by way of example, setting a flag named "review" to "+" may indicate
+ that the bug/attachment has passed review, while setting it to "-"
+ may indicate that the bug/attachment has failed review.
+ </para>
+
+ <para>
+ To unset a flag, click its drop-down menu and select the blank value.
+ Note that marking an attachment as obsolete automatically cancels all
+ pending requests for the attachment.
+ </para>
+
+ <para>
+ If your administrator has enabled requests for a flag, request a flag
+ by selecting "?" from the drop-down menu and then entering the username
+ of the user you want to set the flag in the text field next to the menu.
+ </para>
+
+ <para>
+ A set flag appears in bug reports and on "edit attachment" pages with the
+ abbreviated username of the user who set the flag prepended to the
+ flag name. For example, if Jack sets a "review" flag to "+", it appears
+ as Jack: review [ + ]
+ </para>
+
+ <para>
+ A requested flag appears with the user who requested the flag prepended
+ to the flag name and the user who has been requested to set the flag
+ appended to the flag name within parentheses. For example, if Jack
+ asks Jill for review, it appears as Jack: review [ ? ] (Jill).
+ </para>
+
+ <para>
+ You can browse through open requests made of you and by you by selecting
+ 'My Requests' from the footer. You can also look at open requests limited
+ by other requesters, requestees, products, components, and flag names from
+ this page. Note that you can use '-' for requestee to specify flags with
+ 'no requestee' set.
+ </para>
+ </section>
+
+ <section id="whining">
+ <title>Whining</title>
+
+ <para>
+ Whining is a feature in Bugzilla that can regularly annoy users at
+ specified times. Using this feature, users can execute saved searches
+ at specific times (i.e. the 15th of the month at midnight) or at
+ regular intervals (i.e. every 15 minutes on Sundays). The results of the
+ searches are sent to the user, either as a single email or as one email
+ per bug, along with some descriptive text.
+ </para>
+
+ <warning>
+ <para>
+ Throughout this section it will be assumed that all users are members
+ of the bz_canusewhines group, membership in which is required in order
+ to use the Whining system. You can easily make all users members of
+ the bz_canusewhines group by setting the User RegExp to ".*" (without
+ the quotes).
+ </para>
+
+ <para>
+ Also worth noting is the bz_canusewhineatothers group. Members of this
+ group can create whines for any user or group in Bugzilla using a
+ extended form of the whining interface. Features only available to
+ members of the bz_canusewhineatothers group will be noted in the
+ appropriate places.
+ </para>
+ </warning>
+
+ <note>
+ <para>
+ For whining to work, a special Perl script must be executed at regular
+ intervals. More information on this is available in
+ <xref linkend="installation-whining"/>.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ This section does not cover the whineatnews.pl script. See
+ <xref linkend="installation-whining-cron"/> for more information on
+ The Whining Cron.
+ </para>
+ </note>
+
+ <section id="whining-overview">
+ <title>The Event</title>
+
+ <para>
+ The whining system defines an "Event" as one or more queries being
+ executed at regular intervals, with the results of said queries (if
+ there are any) being emailed to the user. Events are created by
+ clicking on the "Add new event" button.
+ </para>
+
+ <para>
+ Once a new event is created, the first thing to set is the "Email
+ subject line". The contents of this field will be used in the subject
+ line of every email generated by this event. In addition to setting a
+ subject, space is provided to enter some descriptive text that will be
+ included at the top of each message (to help you in understanding why
+ you received the email in the first place).
+ </para>
+
+ <para>
+ The next step is to specify when the Event is to be run (the Schedule)
+ and what searches are to be performed (the Searches).
+ </para>
+
+ </section>
+
+ <section id="whining-schedule">
+ <title>Whining Schedule</title>
+
+ <para>
+ Each whining event is associated with zero or more schedules. A
+ schedule is used to specify when the query (specified below) is to be
+ run. A new event starts out with no schedules (which means it will
+ never run, as it is not scheduled to run). To add a schedule, press
+ the "Add a new schedule" button.
+ </para>
+
+ <para>
+ Each schedule includes an interval, which you use to tell Bugzilla
+ when the event should be run. An event can be run on certain days of
+ the week, certain days of the month, during weekdays (defined as
+ Monday through Friday), or every day.
+ </para>
+
+ <warning>
+ <para>
+ Be careful if you set your event to run on the 29th, 30th, or 31st of
+ the month, as your event may not run exactly when expected. If you
+ want your event to run on the last day of the month, select "Last day
+ of the month" as the interval.
+ </para>
+ </warning>
+
+ <para>
+ Once you have specified the day(s) on which the event is to be run, you
+ should now specify the time at which the event is to be run. You can
+ have the event run at a certain hour on the specified day(s), or
+ every hour, half-hour, or quarter-hour on the specified day(s).
+ </para>
+
+ <para>
+ If a single schedule does not execute an event as many times as you
+ would want, you can create another schedule for the same event. For
+ example, if you want to run an event on days whose numbers are
+ divisible by seven, you would need to add four schedules to the event,
+ setting the schedules to run on the 7th, 14th, 21st, and 28th (one day
+ per schedule) at whatever time (or times) you choose.
+ </para>
+
+ <note>
+ <para>
+ If you are a member of the bz_canusewhineatothers group, then you
+ will be presented with another option: "Mail to". Using this you
+ can control who will receive the emails generated by this event. You
+ can choose to send the emails to a single user (identified by email
+ address) or a single group (identified by group name). To send to
+ multiple users or groups, create a new schedule for each additional
+ user/group.
+ </para>
+ </note>
+ </section>
+
+ <section id="whining-query">
+ <title>Whining Searches</title>
+
+ <para>
+ Each whining event is associated with zero or more searches. A search
+ is any saved search to be run as part of the specified schedule (see
+ above). You start out without any searches associated with the event
+ (which means that the event will not run, as there will never be any
+ results to return). To add a search, press the "Include search" button.
+ </para>
+
+ <para>
+ The first field to examine in your newly added search is the Sort field.
+ Searches are run, and results included, in the order specified by the
+ Sort field. Searches with smaller Sort values will run before searches
+ with bigger Sort values.
+ </para>
+
+ <para>
+ The next field to examine is the Search field. This is where you
+ choose the actual search that is to be run. Instead of defining search
+ parameters here, you are asked to choose from the list of saved
+ searches (the same list that appears at the bottom of every Bugzilla
+ page). You are only allowed to choose from searches that you have
+ saved yourself (the default saved search, "My Bugs", is not a valid
+ choice). If you do not have any saved searches, you can take this
+ opportunity to create one (see <xref linkend="list"/>).
+ </para>
+
+ <note>
+ <para>
+ When running queries, the whining system acts as if you are the user
+ executing the query. This means that the whining system will ignore
+ bugs that match your query, but that you can not access.
+ </para>
+ </note>
+
+ <para>
+ Once you have chosen the saved search to be executed, give the query a
+ descriptive title. This title will appear in the email, above the
+ results of the query. If you choose "One message per bug", the query
+ title will appear at the top of each email that contains a bug matching
+ your query.
+ </para>
+
+ <para>
+ Finally, decide if the results of the query should be sent in a single
+ email, or if each bug should appear in its own email.
+ </para>
+
+ <warning>
+ <para>
+ Think carefully before checking the "One message per bug" box. If
+ you create a query that matches thousands of bugs, you will receive
+ thousands of emails!
+ </para>
+ </warning>
+ </section>
+
+ <section>
+ <title>Saving Your Changes</title>
+
+ <para>
+ Once you have defined at least one schedule, and created at least one
+ query, go ahead and "Update/Commit". This will save your Event and make
+ it available for immediate execution.
+ </para>
+
+ <note>
+ <para>
+ If you ever feel like deleting your event, you may do so using the
+ "Remove Event" button in the upper-right corner of each Event. You
+ can also modify an existing event, so long as you "Update/Commit"
+ after completing your modifications.
+ </para>
+ </note>
+ </section>
+
+ </section>
+
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-always-quote-attributes:t
+sgml-auto-insert-required-elements:t
+sgml-balanced-tag-edit:t
+sgml-exposed-tags:nil
+sgml-general-insert-case:lower
+sgml-indent-data:t
+sgml-indent-step:2
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+sgml-minimize-attributes:nil
+sgml-namecase-general:t
+sgml-omittag:t
+sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-shorttag:t
+sgml-tag-region-if-active:t
+End:
+-->
+
# This script compiles all the documentation.
use strict;
+use Cwd;
# We need to be in this directory to use our libraries.
BEGIN {
my $modules = REQUIRED_MODULES;
my $opt_modules = OPTIONAL_MODULES;
-open(ENTITIES, '>', 'xml/bugzilla.ent') or die('Could not open xml/bugzilla.ent: ' . $!);
+open(ENTITIES, '>', 'bugzilla.ent') or die('Could not open bugzilla.ent: ' . $!);
print ENTITIES '<?xml version="1.0"?>' ."\n\n";
print ENTITIES '<!-- Module Versions -->' . "\n";
foreach my $module (@$modules, @$opt_modules)
$converter->contents_page_start($contents_start);
$converter->contents_page_end("</body></html>");
- $converter->add_css('style.css');
+ $converter->add_css('./../../../style.css');
$converter->javascript_flurry(0);
$converter->css_flurry(0);
- $converter->batch_convert(['../'], 'html/api/');
+ $converter->batch_convert(['../../'], 'html/api/');
print "\n";
}
# Make the docs ...
###############################################################################
-if (!-d 'txt') {
- unlink 'txt';
- mkdir 'txt', 0755;
+my @langs;
+# search for sub directories which have a 'xml' sub-directory
+opendir(LANGS, './');
+foreach my $dir (readdir(LANGS)) {
+ next if (($dir eq '.') || ($dir eq '..') || (! -d $dir));
+ if (-d "$dir/xml") {
+ push(@langs, $dir);
+ }
}
-if (!-d 'pdf') {
- unlink 'pdf';
- mkdir 'pdf', 0755;
-}
-
-make_pod() if $pod_simple;
-exit unless $build_docs;
-
-chdir 'html';
-
-MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
+closedir(LANGS);
+
+my $docparent = getcwd();
+foreach my $lang (@langs) {
+ chdir "$docparent/$lang";
+ MakeDocs(undef, 'cp ../bugzilla.ent ./xml/');
+
+ if (!-d 'txt') {
+ unlink 'txt';
+ mkdir 'txt', 0755;
+ }
+ if (!-d 'pdf') {
+ unlink 'pdf';
+ mkdir 'pdf', 0755;
+ }
+ if (!-d 'html') {
+ unlink 'html';
+ mkdir 'html', 0755;
+ }
+ if (!-d 'html/api') {
+ unlink 'html/api';
+ mkdir 'html/api', 0755;
+ }
+
+ make_pod() if $pod_simple;
+ next unless $build_docs;
+
+ chdir 'html';
+
+ MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
"$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml");
-MakeDocs('big HTML', "jade -V nochunks -t sgml -i html -d " .
+ MakeDocs('big HTML', "jade -V nochunks -t sgml -i html -d " .
"$LDP_HOME/ldp.dsl\#html $JADE_PUB/xml.dcl " .
"../xml/Bugzilla-Guide.xml > Bugzilla-Guide.html");
-MakeDocs('big text', "lynx -dump -justify=off -nolist Bugzilla-Guide.html " .
+ MakeDocs('big text', "lynx -dump -justify=off -nolist Bugzilla-Guide.html " .
"> ../txt/Bugzilla-Guide.txt");
-if (! grep($_ eq "--with-pdf", @ARGV)) {
- exit;
-}
+ if (! grep($_ eq "--with-pdf", @ARGV)) {
+ next;
+ }
-MakeDocs('PDF', "jade -t tex -d $LDP_HOME/ldp.dsl\#print $JADE_PUB/xml.dcl " .
+ MakeDocs('PDF', "jade -t tex -d $LDP_HOME/ldp.dsl\#print $JADE_PUB/xml.dcl " .
'../xml/Bugzilla-Guide.xml');
-chdir '../pdf';
-MakeDocs(undef, 'mv ../xml/Bugzilla-Guide.tex .');
-MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
-MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
-MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
-MakeDocs(undef, 'rm Bugzilla-Guide.tex Bugzilla-Guide.log Bugzilla-Guide.aux Bugzilla-Guide.out');
+ chdir '../pdf';
+ MakeDocs(undef, 'mv ../xml/Bugzilla-Guide.tex .');
+ MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
+ MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
+ MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
+ MakeDocs(undef, 'rm Bugzilla-Guide.tex Bugzilla-Guide.log Bugzilla-Guide.aux Bugzilla-Guide.out');
+
+}
--- /dev/null
+/* The contents of this file are subject to the Mozilla Public
+ * License Version 1.1 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS
+ * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * rights and limitations under the License.
+ *
+ * The Original Code is the Bugzilla Bug Tracking System.
+ *
+ * The Initial Developer of the Original Code is Everything Solved.
+ * Portions created by Everything Solved are Copyright (C) 2006
+ * Everything Solved. All Rights Reserved.
+ *
+ * Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+ */
+
+body {
+ background: white;
+ color: #111;
+ padding: 0 1em;
+ margin: 0;
+ font-family: Verdana, Arial, sans-serif;
+ font-size: small;
+}
+
+a:link, a:active { color: #36415c; }
+a:visited { color: #666; }
+a:hover { color: #888; }
+
+h1 {
+ font-size: 150%;
+ font-weight: bold;
+ border-bottom: 2px solid #ccc;
+}
+h2 {
+ font-size: 125%;
+ font-weight: bold;
+ border-bottom: 1px solid #ccc;
+ margin-bottom: 8px;
+}
+h3 {
+ font-size: 115%;
+ font-weight: bold;
+ margin-bottom: 0;
+ padding-bottom: 0;
+}
+
+/* This makes Description/Params/Returns look nice. */
+dd { margin-top: .2em; }
+dd p { margin-top: 0; }
+dl { margin-bottom: 1em; }
+
+/* This makes the names of functions slightly larger, in Gecko. */
+body > dl > dt code { font-size: 1.35em; }
+
+#pod h1 a, #pod h2 a, #pod h3 a {
+ color: #36415c;
+ text-decoration: none;
+}
+
+pre, code, tt, kbd, samp {
+ /* Unfortunately, the default monospace fonts on most browsers
+ look odd with relative sizing. */
+ font-size: 12px;
+}
+
+.code {
+ background: #eed;
+ border: 1px solid #ccc;
+}
+
+pre.code {
+ margin-left: 10px;
+ width: 90%;
+ padding: 10px;
+}
+
+/* Special styles for the Contents page */
+
+.contentspage dt {
+ font-size: large;
+ font-weight: bold;
+}
+
+.pod_desc_table {
+ border-collapse: collapse;
+ table-layout: auto;
+ border: 1px solid #ccc;
+}
+
+.pod_desc_table th {
+ text-align: left;
+}
+
+.pod_desc_table td, .pod_desc_table th {
+ padding: .25em;
+ border-top: 1px solid #ccc;
+}
+
+.pod_desc_table .odd th, .pod_desc_table .odd td {
+ background-color: #eee;
+}
+
+.pod_desc_table
"$terms.Bugzilla documentation URLs. " _
"It may be an absolute URL, or a URL relative to urlbase " _
"above. " _
- "Leave this empty to suppress links to the documentation.",
+ "Leave this empty to suppress links to the documentation." _
+ "'%lang%' will be replaced by user's preferred language " _
+ "(if available)."
sslbase => "The URL that is the common initial leading part of all HTTPS " _
"(SSL) $terms.Bugzilla URLs.",
[% IF doc_section %]
<li>
<span class="separator">| </span>
- <a href="[% Param("docs_urlbase") _ doc_section FILTER html %]" target="_blank">Help</a>
+ <a href="[% docs_urlbase _ doc_section FILTER html %]" target="_blank">Help</a>
</li>
[% END %]
[% END %]
[% BLOCK docslinkslist %]
[% FOREACH docslink = docstype.keys %]
<li>
- <a href="[% Param('docs_urlbase') %]
+ <a href="[% docs_urlbase FILTER html %]
[% docslink FILTER none %]">[% docstype.$docslink FILTER html %]</a>
</li>
[% END %]
</select>
[% IF Param('docs_urlbase') %]
- <a href="[% Param('docs_urlbase') %]query.html#individual-buglists">the named tag</a>
+ <a href="[% docs_urlbase FILTER html %]query.html#individual-buglists">the named tag</a>
[% ELSE %]
the named tag
[% END %]
of [% terms.Bugzilla %], see the
<a href="page.cgi?id=release-notes.html">release notes</a>!
You may also want to read the
- <a href="[% Param('docs_urlbase') FILTER html %]using.html">
+ <a href="[% docs_urlbase FILTER html %]using.html">
[%- terms.Bugzilla %] User's Guide</a> to find out more about
[%+ terms.Bugzilla %] and how to use it.</p>
to the <kbd>xmlrpc.cgi</kbd> on your installation.</p>
<p>Documentation can be found in the
- <a href="[% Param('docs_urlbase') FILTER html %]api/">[% terms.Bugzilla %]
+ <a href="[% docs_urlbase FILTER html %]api/">[% terms.Bugzilla %]
API Docs</a>, in the various <kbd>Bugzilla::WebService</kbd> modules.</p>
<h3><a name="v30_feat_skin"></a>Skins</h3>
<p>[% terms.Bugzilla %] can have multiple "skins" installed,
and users can pick between them. To write a skin, you just have to
- write several CSS files. See the <a href="[% Param('docs_urlbase') FILTER html %]cust-skins.html">Custom
+ write several CSS files. See the <a href="[% docs_urlbase FILTER html %]cust-skins.html">Custom
Skins Documentation</a> for more details.</p>
<p>We currently don't have any alternate skins shipping with
unsupported add-on, but it is now an official interface to
[%+ terms.Bugzilla %].</p>
-<p>For more details see the <a href="[% Param('docs_urlbase') FILTER html %]api/email_in.html">documentation
+<p>For more details see the <a href="[% docs_urlbase FILTER html %]api/email_in.html">documentation
for email_in.pl</a>.</p>
<h3><a name="v30_feat_gw"></a>Users Who Get All [% terms.Bug %]
<kbd>localconfig</kbd> file to the new installation.</p></li>
<li>Now follow the standard
- <a href="[% Param('docs_urlbase') FILTER html %]installing-bugzilla.html">
+ <a href="[% docs_urlbase FILTER html %]installing-bugzilla.html">
[%- terms.Bugzilla %] installation process</a>.</li>
<li>Run <kbd>checksetup.pl</kbd> after you install the new version.</li>
<p>[% terms.Bugzilla %] now supports a code hook mechanism. See the
documentation for
- <a href="[% Param('docs_urlbase') FILTER html %]api/Bugzilla/Hook.html">Bugzilla::Hook</a>
+ <a href="[% docs_urlbase FILTER html %]api/Bugzilla/Hook.html">Bugzilla::Hook</a>
for more details.</p>
<p>This gives [% terms.Bugzilla %] very advanced plugin support. You can
<p>[% terms.Bugzilla %] now ships with all of its perldoc built
as HTML. Go ahead and read the
- <a href="[% Param('docs_urlbase') FILTER html %]api/">API Documentation</a>
+ <a href="[% docs_urlbase FILTER html %]api/">API Documentation</a>
for all of the [% terms.Bugzilla %] modules now! Even scripts like
<kbd>checksetup.pl</kbd> have HTML documentation.</p>
<p>The <kbd>Bugzilla::Auth</kbd> family of modules have been completely
re-written. For details on how the new structure of authentication,
read the
- <a href="[% Param('docs_urlbase') FILTER html %]api/Bugzilla/Auth.html">Bugzilla::Auth
+ <a href="[% docs_urlbase FILTER html %]api/Bugzilla/Auth.html">Bugzilla::Auth
API docs</a>.</p>
<p>It should be very easy to write new authentication plugins, now.</p>
<h3><a name="v30_code_obj"></a>Bugzilla::Object</h3>
<p>There is a new base class for most of our objects,
- <a href="[% Param('docs_urlbase') FILTER html %]api/Bugzilla/Object.html">Bugzilla::Object</a>.
+ <a href="[% docs_urlbase FILTER html %]api/Bugzilla/Object.html">Bugzilla::Object</a>.
It makes it really easy to create new objects based on things that are
in the database.</p>
<li><code>checksetup.pl</code> has been completely re-written, and most
of its code moved into modules in the <kbd>Bugzilla::Install</kbd>
namespace. See the
- <a href="[% Param('docs_urlbase') FILTER html %]api/checksetup.html">checksetup
+ <a href="[% docs_urlbase FILTER html %]api/checksetup.html">checksetup
documentation</a> and <a href="https://bugzilla.mozilla.org/showdependencytree.cgi?id=277502&hide_resolved=0">[% terms.Bugzilla %]
[%+ terms.bug %] 277502</a> for details.</li>
<li>Instead of <kbd>UserInGroup()</kbd>, all of [% terms.Bugzilla %] now
<p>Release notes for versions of [% terms.Bugzilla %] for versions
prior to 3.0 are only available in text format:
- <a href="docs/rel_notes.txt">Release Notes for [% terms.Bugzilla %] 2.22
+ <a href="[% docs_urlbase FILTER remove('html/$') FILTER html %]rel_notes.txt">Release Notes for [% terms.Bugzilla %] 2.22
and Earlier</a>.</p>
[% INCLUDE global/footer.html.tmpl %]
projects / thirdparty / bugzilla.git / commitdiff
