diff options
Diffstat (limited to 'docs/en')
30 files changed, 15983 insertions, 0 deletions
diff --git a/docs/en/.cvsignore b/docs/en/.cvsignore new file mode 100644 index 000000000..19d1c430e --- /dev/null +++ b/docs/en/.cvsignore @@ -0,0 +1,3 @@ +txt +pdf +html diff --git a/docs/en/README.docs b/docs/en/README.docs new file mode 100644 index 000000000..5fdeb8570 --- /dev/null +++ b/docs/en/README.docs @@ -0,0 +1,155 @@ +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. diff --git a/docs/en/images/bzLifecycle.png b/docs/en/images/bzLifecycle.png Binary files differnew file mode 100644 index 000000000..c1d76e237 --- /dev/null +++ b/docs/en/images/bzLifecycle.png diff --git a/docs/en/images/bzLifecycle.xml b/docs/en/images/bzLifecycle.xml new file mode 100644 index 000000000..1adc6b70c --- /dev/null +++ b/docs/en/images/bzLifecycle.xml @@ -0,0 +1,1613 @@ +<?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> diff --git a/docs/en/images/callouts/1.gif b/docs/en/images/callouts/1.gif Binary files differnew file mode 100644 index 000000000..79fd388a8 --- /dev/null +++ b/docs/en/images/callouts/1.gif diff --git a/docs/en/images/callouts/2.gif b/docs/en/images/callouts/2.gif Binary files differnew file mode 100644 index 000000000..b9be050e4 --- /dev/null +++ b/docs/en/images/callouts/2.gif diff --git a/docs/en/images/callouts/3.gif b/docs/en/images/callouts/3.gif Binary files differnew file mode 100644 index 000000000..73635e3f7 --- /dev/null +++ b/docs/en/images/callouts/3.gif diff --git a/docs/en/images/caution.gif b/docs/en/images/caution.gif Binary files differnew file mode 100644 index 000000000..a48223013 --- /dev/null +++ b/docs/en/images/caution.gif diff --git a/docs/en/images/note.gif b/docs/en/images/note.gif Binary files differnew file mode 100644 index 000000000..613bc7f70 --- /dev/null +++ b/docs/en/images/note.gif diff --git a/docs/en/images/tip.gif b/docs/en/images/tip.gif Binary files differnew file mode 100644 index 000000000..c8d5ae9bd --- /dev/null +++ b/docs/en/images/tip.gif diff --git a/docs/en/images/warning.gif b/docs/en/images/warning.gif Binary files differnew file mode 100644 index 000000000..693ffc3e8 --- /dev/null +++ b/docs/en/images/warning.gif diff --git a/docs/en/rel_notes.txt b/docs/en/rel_notes.txt new file mode 100644 index 000000000..614fcb5a1 --- /dev/null +++ b/docs/en/rel_notes.txt @@ -0,0 +1,3028 @@ +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. + diff --git a/docs/en/xml/.cvsignore b/docs/en/xml/.cvsignore new file mode 100644 index 000000000..ef6b304bc --- /dev/null +++ b/docs/en/xml/.cvsignore @@ -0,0 +1 @@ +bugzilla.ent diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml new file mode 100644 index 000000000..e9650c7cb --- /dev/null +++ b/docs/en/xml/Bugzilla-Guide.xml @@ -0,0 +1,178 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ + <!ENTITY % myents SYSTEM "bugzilla.ent"> + %myents; + +<!-- Include macros --> +<!ENTITY about SYSTEM "about.xml"> +<!ENTITY conventions SYSTEM "conventions.xml"> +<!ENTITY doc-index SYSTEM "index.xml"> +<!ENTITY gfdl SYSTEM "gfdl.xml"> +<!ENTITY glossary SYSTEM "glossary.xml"> +<!ENTITY installation SYSTEM "installation.xml"> +<!ENTITY administration SYSTEM "administration.xml"> +<!ENTITY security SYSTEM "security.xml"> +<!ENTITY using SYSTEM "using.xml"> +<!ENTITY integration SYSTEM "integration.xml"> +<!ENTITY index SYSTEM "index.xml"> +<!ENTITY customization SYSTEM "customization.xml"> +<!ENTITY troubleshooting SYSTEM "troubleshooting.xml"> +<!ENTITY patches SYSTEM "patches.xml"> +<!ENTITY introduction SYSTEM "introduction.xml"> +<!ENTITY modules SYSTEM "modules.xml"> + +<!-- Things to change for a stable release: + * bz-ver to current stable + * bz-nexver to next stable + * bz-date to the release date + * landfillbase to the branch install + * Remove the BZ-DEVEL comments + - COMPILE DOCS AND CHECKIN - + Also, tag and tarball before completing + * bz-ver to devel version + + For a devel release, simple bump bz-ver and bz-date +--> + +<!ENTITY bz-ver "3.1.3"> +<!ENTITY bz-nextver "3.2"> +<!ENTITY bz-date "2008-02-01"> +<!ENTITY current-year "2008"> + +<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/"> +<!ENTITY bz "http://www.bugzilla.org/"> +<!ENTITY bzg-bugs "<ulink url='https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation'>Bugzilla Documentation</ulink>"> +<!ENTITY mysql "http://www.mysql.com/"> + +<!ENTITY min-perl-ver "5.8.1"> +]> + + +<!-- Coding standards for this document + +* Other than the GFDL, please use the "section" tag instead of "sect1", + "sect2", etc. +* Use Entities to include files for new chapters in Bugzilla-Guide.xml. +* Try to use Entities for frequently-used passages of text as well. +* Ensure all documents compile cleanly to HTML after modification. + The warning, "DTDDECL catalog types not supported" is normal. +* Try to index important terms wherever possible. +* Use "glossterm" whenever you introduce a new term. +* Follow coding standards at http://www.tldp.org, and + check out the KDE guidelines (they are nice, too) + http://i18n.kde.org/doc/markup.html +* All tags should be lowercase. +* Please use sensible spacing. The comments at the very end of each + file define reasonable defaults for PSGML mode in EMACS. +* Double-indent tags, use double spacing whenever possible, and + try to avoid clutter and feel free to waste space in the code to make it + more readable. + +--> + +<book id="index"> + +<!-- Header --> + + <bookinfo> + <title>The Bugzilla Guide - &bz-ver; + <!-- BZ-DEVEL -->Development <!-- /BZ-DEVEL --> + Release</title> + + <authorgroup> + <corpauthor>The Bugzilla Team</corpauthor> + </authorgroup> + + <pubdate>&bz-date;</pubdate> + + <abstract> + <para> + This is the documentation for Bugzilla, a + bug-tracking system from mozilla.org. + Bugzilla is an enterprise-class piece of software + that tracks millions of bugs and issues for hundreds of + organizations around the world. + </para> + + <para> + The most current version of this document can always be found on the + <ulink url="http://www.bugzilla.org/docs/">Bugzilla + Documentation Page</ulink>. + </para> + + </abstract> + + <keywordset> + <keyword>Bugzilla</keyword> + <keyword>Guide</keyword> + <keyword>installation</keyword> + <keyword>FAQ</keyword> + <keyword>administration</keyword> + <keyword>integration</keyword> + <keyword>MySQL</keyword> + <keyword>Mozilla</keyword> + <keyword>webtools</keyword> + </keywordset> + </bookinfo> + +<!-- About This Guide --> +&about; + +<!-- Installing Bugzilla --> +&installation; + +<!-- Administering Bugzilla --> +&administration; + +<!-- Securing Bugzilla --> +&security; + +<!-- Using Bugzilla --> +&using; + +<!-- Customizing Bugzilla --> +&customization; + +<!-- Appendix: Troubleshooting --> +&troubleshooting; + +<!-- Appendix: Custom Patches --> +&patches; + +<!-- Appendix: Manually Installing Perl Modules --> +&modules; + +<!-- Appendix: GNU Free Documentation License --> +&gfdl; + +<!-- Glossary --> +&glossary; + +<!-- Index --> +&index; + + +</book> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml new file mode 100644 index 000000000..2594e873f --- /dev/null +++ b/docs/en/xml/about.xml @@ -0,0 +1,243 @@ +<!-- <!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: --> + diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml new file mode 100644 index 000000000..7a75604de --- /dev/null +++ b/docs/en/xml/administration.xml @@ -0,0 +1,3448 @@ +<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<chapter id="administration"> + <title>Administering Bugzilla</title> + + <section id="parameters"> + <title>Bugzilla Configuration</title> + + <para> + Bugzilla is configured by changing various parameters, accessed + from the "Parameters" link in the Administration page (the + Administration page can be found by clicking the "Administration" + link in the footer). The parameters are divided into several categories, + accessed via the menu on the left. Following is a description of the + different categories and important parameters within those categories. + </para> + + <section id="param-requiredsettings"> + <title>Required Settings</title> + + <para> + The core required parameters for any Bugzilla installation are set + here. These parameters must be set before a new Bugzilla installation + can be used. Administrators should review this list before + deploying a new Bugzilla installation. + </para> + + <indexterm> + <primary>checklist</primary> + </indexterm> + + <variablelist> + + <varlistentry> + <term> + maintainer + </term> + <listitem> + <para> + Email address of the person + responsible for maintaining this Bugzilla installation. + The address need not be that of a valid Bugzilla account. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + urlbase + </term> + <listitem> + <para> + Defines the fully qualified domain name and web + server path to this Bugzilla installation. + </para> + <para> + For example, if the Bugzilla query page is + <filename>http://www.foo.com/bugzilla/query.cgi</filename>, + the <quote>urlbase</quote> should be set + to <filename>http://www.foo.com/bugzilla/</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + docs_urlbase + </term> + <listitem> + <para> + Defines path to the Bugzilla documentation. This can be a fully + qualified domain name, or a path relative to "urlbase". + </para> + <para> + For example, if the "Bugzilla Configuration" page + of the documentation is + <filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>, + set the <quote>docs_urlbase</quote> + to <filename>http://www.foo.com/bugzilla/docs/html/</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + sslbase + </term> + <listitem> + <para> + Defines the fully qualified domain name and web + server path for HTTPS (SSL) connections to this Bugzilla installation. + </para> + <para> + For example, if the Bugzilla main page is + <filename>https://www.foo.com/bugzilla/index.cgi</filename>, + the <quote>sslbase</quote> should be set + to <filename>https://www.foo.com/bugzilla/</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + ssl + </term> + <listitem> + <para> + Determines when Bugzilla will force HTTPS (SSL) connections, using + the URL defined in <command>sslbase</command>. + Options include "always", "never", and "authenticated sessions". + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + cookiedomain + </term> + <listitem> + <para> + Defines the domain for Bugzilla cookies. This is typically left blank. + If there are multiple hostnames that point to the same webserver, which + require the same cookie, then this parameter can be utilized. For + example, If your website is at + <filename>https://www.foo.com/</filename>, setting this to + <filename>.foo.com/</filename> will also allow + <filename>bar.foo.com/</filename> to access Bugzilla cookies. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + cookiepath + </term> + <listitem> + <para> + Defines a path, relative to the web server root, that Bugzilla + cookies will be restricted to. For example, if the + <command>urlbase</command> is set to + <filename>http://www.foo.com/bugzilla/</filename>, the + <command>cookiepath</command> should be set to + <filename>/bugzilla/</filename>. Setting it to "/" will allow all sites + served by this web server or virtual host to read Bugzilla cookies. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + timezone + </term> + <listitem> + <para> + Timezone of server. The timezone is displayed with timestamps. If + this parameter is left blank, the timezone is not displayed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + utf8 + </term> + <listitem> + <para> + Determines whether to use UTF-8 (Unicode) encoding for all text in + Bugzilla. New installations should set this to true to avoid character + encoding problems. Existing databases should set this to true only + after the data has been converted from existing legacy character + encoding to UTF-8, using the + <filename>contrib/recode.pl</filename> script. + </para> + <note> + <para> + If you turn this parameter from "off" to "on", you must re-run + <filename>checksetup.pl</filename> immediately afterward. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + shutdownhtml + </term> + <listitem> + <para> + If there is any text in this field, this Bugzilla installation will + be completely disabled and this text will appear instead of all + Bugzilla pages for all users, including Admins. Used in the event + of site maintenance or outage situations. + </para> + <note> + <para> + Although regular log-in capability is disabled while + <command>shutdownhtml</command> + is enabled, safeguards are in place to protect the unfortunate + admin who loses connection to Bugzilla. Should this happen to you, + go directly to the <filename>editparams.cgi</filename> (by typing + the URL in manually, if necessary). Doing this will prompt you to + log in, and your name/password will be accepted here (but nowhere + else). + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + announcehtml + </term> + <listitem> + <para> + Any text in this field will be displayed at the top of every HTML + page in this Bugzilla installation. The text is not wrapped in any + tags. For best results, wrap the text in a <quote><div></quote> + tag. Any style attributes from the CSS can be applied. For example, + to make the text green inside of a red box, add <quote>id=message</quote> + to the <quote><div></quote> tag. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + proxy_url + </term> + <listitem> + <para> + If this Bugzilla installation is behind a proxy, enter the proxy + information here to enable Bugzilla to access the Internet. Bugzilla + requires Internet access to utilize the + <command>upgrade_notification</command> parameter (below). If the + proxy requires authentication, use the syntax: + <filename>http://user:pass@proxy_url/</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + upgrade_notification + </term> + <listitem> + <para> + Enable or disable a notification on the homepage of this Bugzilla + installation when a newer version of Bugzilla is available. This + notification is only visible to administrators. Choose "disabled", + to turn off the notification. Otherwise, choose which version of + Bugzilla you want to be notified about: "development_snapshot" is the + latest release on the trunk; "latest_stable_release" is the most + recent release available on the most recent stable branch; + "stable_branch_release" the most recent release on the branch + this installation is based on. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-admin-policies"> + <title>Administrative Policies</title> + <para> + This page contains parameters for basic administrative functions. + Options include whether to allow the deletion of bugs and users, whether + to allow users to change their email address, and whether to allow + user watching (one user receiving all notifications of a selected + other user). + </para> + + <variablelist> + + <varlistentry> + <term> + supportwatchers + </term> + <listitem> + <para> + Turning on this option allows users to ask to receive copies + of bug mail sent to another user. Watching a user with + different group permissions is not a way to 'get around' the + system; copied emails are still subject to the normal groupset + permissions of a bug, and <quote>watchers</quote> will only be + copied on emails from bugs they would normally be allowed to view. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-user-authentication"> + <title>User Authentication</title> + <para> + This page contains the settings that control how this Bugzilla + installation will do its authentication. Choose what authentication + mechanism to use (the Bugzilla database, or an external source such + as LDAP), and set basic behavioral parameters. For example, choose + whether to require users to login to browse bugs, the management + of authentication cookies, and the regular expression used to + validate email addresses. Some parameters are highlighted below. + </para> + + <variablelist> + + <varlistentry> + <term> + emailregexp + </term> + <listitem> + <para> + Defines the regular expression used to validate email addresses + used for login names. The default attempts to match fully + qualified email addresses (i.e. 'user@example.com'). Some + Bugzilla installations allow only local user names (i.e 'user' + instead of 'user@example.com'). In that case, the + <command>emailsuffix</command> parameter should be used to define + the email domain. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + emailsuffix + </term> + <listitem> + <para> + This string is appended to login names when actually sending + email to a user. For example, + If <command>emailregexp</command> has been set to allow + local usernames, + then this parameter would contain the email domain for all users + (i.e. '@example.com'). + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-attachments"> + <title>Attachments</title> + <para> + This page allows for setting restrictions and other parameters + regarding attachments to bugs. For example, control size limitations + and whether to allow pointing to external files via a URI. + </para> + </section> + + <section id="param-bug-change-policies"> + <title>Bug Change Policies</title> + <para> + Set policy on default behavior for bug change events. For example, + choose which status to set a bug to when it is marked as a duplicate, + and choose whether to allow bug reporters to set the priority or + target milestone. Also allows for configuration of what changes + should require the user to make a comment, described below. + </para> + + <variablelist> + + <varlistentry> + <term> + commenton* + </term> + <listitem> + <para> + All these fields allow you to dictate what changes can pass + without comment, and which must have a comment from the + person who changed them. Often, administrators will allow + users to add themselves to the CC list, accept bugs, or + change the Status Whiteboard without adding a comment as to + their reasons for the change, yet require that most other + changes come with an explanation. + </para> + + <para> + Set the "commenton" options according to your site policy. It + is a wise idea to require comments when users resolve, reassign, or + reopen bugs at the very least. + </para> + + <note> + <para> + It is generally far better to require a developer comment + when resolving bugs than not. Few things are more annoying to bug + database users than having a developer mark a bug "fixed" without + any comment as to what the fix was (or even that it was truly + fixed!) + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + noresolveonopenblockers + </term> + <listitem> + <para> + This option will prevent users from resolving bugs as FIXED if + they have unresolved dependencies. Only the FIXED resolution + is affected. Users will be still able to resolve bugs to + resolutions other than FIXED if they have unresolved dependent + bugs. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-bugfields"> + <title>Bug Fields</title> + <para> + The parameters in this section determine the default settings of + several Bugzilla fields for new bugs, and also control whether + certain fields are used. For example, choose whether to use the + "target milestone" field or the "status whiteboard" field. + </para> + + <variablelist> + + <varlistentry> + <term> + useqacontact + </term> + <listitem> + <para> + This allows you to define an email address for each component, + in addition to that of the default assignee, who will be sent + carbon copies of incoming bugs. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + usestatuswhiteboard + </term> + <listitem> + <para> + This defines whether you wish to have a free-form, overwritable field + associated with each bug. The advantage of the Status Whiteboard is + that it can be deleted or modified with ease, and provides an + easily-searchable field for indexing some bugs that have some trait + in common. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-bugmoving"> + <title>Bug Moving</title> + <para> + This page controls whether this Bugzilla installation allows certain + users to move bugs to an external database. If bug moving is enabled, + there are a number of parameters that control bug moving behaviors. + For example, choose which users are allowed to move bugs, the location + of the external database, and the default product and component that + bugs moved <emphasis>from</emphasis> other bug databases to this + Bugzilla installation are assigned to. + </para> + + </section> + + <section id="param-dependency-graphs"> + <title>Dependency Graphs</title> + <para> + This page has one parameter that sets the location of a Web Dot + server, or of the Web Dot binary on the local system, that is used + to generate dependency graphs. Web Dot is a CGI program that creates + images from <filename>.dot</filename> graphic description files. If + no Web Dot server or binary is specified, then dependency graphs will + be disabled. + </para> + </section> + + <section id="param-group-security"> + <title>Group Security</title> + <para> + Bugzilla allows for the creation of different groups, with the + ability to restrict the visibility of bugs in a group to a set of + specific users. Specific products can also be associated with + groups, and users restricted to only see products in their groups. + Several parameters are described in more detail below. Most of the + configuration of groups and their relationship to products is done + on the "Groups" and "Product" pages of the "Administration" area. + The options on this page control global default behavior. + For more information on Groups and Group Security, see + <xref linkend="groups"/> + </para> + + <variablelist> + + <varlistentry> + <term> + makeproductgroups + </term> + <listitem> + <para> + Determines whether or not to automatically create groups + when new products are created. If this is on, the groups will be + used for querying bugs. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + useentrygroupdefault + </term> + <listitem> + <para> + Bugzilla products can have a group associated with them, so that + certain users can only see bugs in certain products. When this + parameter is set to <quote>on</quote>, this + causes the initial group controls on newly created products + to place all newly-created bugs in the group + having the same name as the product immediately. + After a product is initially created, the group controls + can be further adjusted without interference by + this mechanism. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + usevisibilitygroups + </term> + <listitem> + <para> + If selected, user visibility will be restricted to members of + groups, as selected in the group configuration settings. + Each user-defined group can be allowed to see members of selected + other groups. + For details on configuring groups (including the visibility + restrictions) see <xref linkend="edit-groups"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + querysharegroup + </term> + <listitem> + <para> + The name of the group of users who are allowed to share saved + searches with one another. For more information on using + saved searches, see <xref linkend="savedsearches"/>. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="bzldap"> + <title>LDAP Authentication</title> + + <para>LDAP authentication is a module for Bugzilla's plugin + authentication architecture. This page contains all the parameters + necessary to configure Bugzilla for use with LDAP authentication. + </para> + + <para> + The existing authentication + scheme for Bugzilla uses email addresses as the primary user ID, and a + password to authenticate that user. All places within Bugzilla that + require a user ID (e.g assigning a bug) use the email + address. The LDAP authentication builds on top of this scheme, rather + than replacing it. The initial log-in is done with a username and + password for the LDAP directory. Bugzilla tries to bind to LDAP using + those credentials and, if successful, tries to map this account to a + Bugzilla account. If an LDAP mail attribute is defined, the value of this + attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP + username to form a full email address. If an account for this address + already exists in the Bugzilla installation, it will log in to that account. + If no account for that email address exists, one is created at the time + of login. (In this case, Bugzilla will attempt to use the "displayName" + or "cn" attribute to determine the user's full name.) After + authentication, all other user-related tasks are still handled by email + address, not LDAP username. For example, bugs are still assigned by + email address and users are still queried by email address. + </para> + + <caution> + <para>Because the Bugzilla account is not created until the first time + a user logs in, a user who has not yet logged is unknown to Bugzilla. + This means they cannot be used as an assignee or QA contact (default or + otherwise), added to any CC list, or any other such operation. One + possible workaround is the <filename>bugzilla_ldapsync.rb</filename> + script in the + <glossterm linkend="gloss-contrib"> + <filename class="directory">contrib</filename></glossterm> + directory. Another possible solution is fixing + <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug + 201069</ulink>. + </para> + </caution> + + <para>Parameters required to use LDAP Authentication:</para> + + <variablelist> + <varlistentry id="param-user_verify_class_for_ldap"> + <term>user_verify_class</term> + <listitem> + <para>If you want to list <quote>LDAP</quote> here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + well, you may otherwise not be able to log back in to Bugzilla once + you log out. + If this happens to you, you will need to manually edit + <filename>data/params</filename> and set user_verify_class to + <quote>DB</quote>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="param-LDAPserver"> + <term>LDAPserver</term> + <listitem> + <para>This parameter should be set to the name (and optionally the + port) of your LDAP server. If no port is specified, it assumes + the default LDAP port of 389. + </para> + <para>Ex. <quote>ldap.company.com</quote> + or <quote>ldap.company.com:3268</quote> + </para> + <para>You can also specify a LDAP URI, so as to use other + protocols, such as LDAPS or LDAPI. If port was not specified in + the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' + schemes respectively. + </para> + <para>Ex. <quote>ldap://ldap.company.com</quote>, + <quote>ldaps://ldap.company.com</quote> or + <quote>ldapi://%2fvar%2flib%2fldap_sock</quote> + </para> + </listitem> + </varlistentry> + + <varlistentry id="param-LDAPbinddn"> + <term>LDAPbinddn [Optional]</term> + <listitem> + <para>Some LDAP servers will not allow an anonymous bind to search + the directory. If this is the case with your configuration you + should set the LDAPbinddn parameter to the user account Bugzilla + should use instead of the anonymous bind. + </para> + <para>Ex. <quote>cn=default,cn=user:password</quote></para> + </listitem> + </varlistentry> + + <varlistentry id="param-LDAPBaseDN"> + <term>LDAPBaseDN</term> + <listitem> + <para>The LDAPBaseDN parameter should be set to the location in + your LDAP tree that you would like to search for email addresses. + Your uids should be unique under the DN specified here. + </para> + <para>Ex. <quote>ou=People,o=Company</quote></para> + </listitem> + </varlistentry> + + <varlistentry id="param-LDAPuidattribute"> + <term>LDAPuidattribute</term> + <listitem> + <para>The LDAPuidattribute parameter should be set to the attribute + which contains the unique UID of your users. The value retrieved + from this attribute will be used when attempting to bind as the + user to confirm their password. + </para> + <para>Ex. <quote>uid</quote></para> + </listitem> + </varlistentry> + + <varlistentry id="param-LDAPmailattribute"> + <term>LDAPmailattribute</term> + <listitem> + <para>The LDAPmailattribute parameter should be the name of the + attribute which contains the email address your users will enter + into the Bugzilla login boxes. + </para> + <para>Ex. <quote>mail</quote></para> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section id="bzradius"> + <title>RADIUS Authentication</title> + + <para> + RADIUS authentication is a module for Bugzilla's plugin + authentication architecture. This page contains all the parameters + necessary for configuring Bugzilla to use RADIUS authentication. + </para> + <note> + <para> + Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. See <xref linkend="bzldap"/> for details. + </para> + </note> + + <para>Parameters required to use RADIUS Authentication:</para> + + <variablelist> + <varlistentry id="param-user_verify_class_for_radius"> + <term>user_verify_class</term> + <listitem> + <para>If you want to list <quote>RADIUS</quote> here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + well, you may otherwise not be able to log back in to Bugzilla once + you log out. + If this happens to you, you will need to manually edit + <filename>data/params</filename> and set user_verify_class to + <quote>DB</quote>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="param-RADIUS_server"> + <term>RADIUS_server</term> + <listitem> + <para>This parameter should be set to the name (and optionally the + port) of your RADIUS server. + </para> + </listitem> + </varlistentry> + + <varlistentry id="param-RADIUS_secret"> + <term>RADIUS_secret</term> + <listitem> + <para>This parameter should be set to the RADIUS server's secret. + </para> + </listitem> + </varlistentry> + + <varlistentry id="param-RADIUS_email_suffix"> + <term>RADIUS_email_suffix</term> + <listitem> + <para>Bugzilla needs an e-mail address for each user account. + Therefore, it needs to determine the e-mail address corresponding + to a RADIUS user. + Bugzilla offers only a simple way to do this: it can concatenate + a suffix to the RADIUS user name to convert it into an e-mail + address. + You can specify this suffix in the RADIUS_email_suffix parameter. + </para> + <para>If this simple solution does not work for you, you'll + probably need to modify + <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your + requirements. + </para> + </listitem> + </varlistentry> + </variablelist> + + </section> + + <section id="param-email"> + <title>Email</title> + <para> + This page contains all of the parameters for configuring how + Bugzilla deals with the email notifications it sends. See below + for a summary of important options. + </para> + + <variablelist> + + <varlistentry> + <term> + mail_delivery_method + </term> + <listitem> + <para> + This is used to specify how email is sent, or if it is sent at + all. There are several options included for different MTAs, + along with two additional options that disable email sending. + "Test" does not send mail, but instead saves it in + <filename>data/mailer.testfile</filename> for later review. + "None" disables email sending entirely. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + mailfrom + </term> + <listitem> + <para> + This is the email address that will appear in the "From" field + of all emails sent by this Bugzilla installation. Some email + servers require mail to be from a valid email address, therefore + it is recommended to choose a valid email address here. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + sendmailnow + </term> + <listitem> + <para> + When Bugzilla is using Sendmail older than 8.12, turning this option + off will improve performance by not waiting for Sendmail to actually + send mail. If Sendmail 8.12 or later is being used, there is + nothing to gain by turning this off. If another MTA is being used, + such as Postfix, then this option *must* be turned on (even if you + are using the fake sendmail executable that Postfix provides). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + whinedays + </term> + <listitem> + <para> + Set this to the number of days you want to let bugs go + in the NEW or REOPENED state before notifying people they have + untouched new bugs. If you do not plan to use this feature, simply + do not set up the whining cron job described in the installation + instructions, or set this value to "0" (never whine). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + globalwatcher + </term> + <listitem> + <para> + This allows you to define specific users who will + receive notification each time a new bug in entered, or when + an existing bug changes, according to the normal groupset + permissions. It may be useful for sending notifications to a + mailing-list, for instance. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + <section id="param-patchviewer"> + <title>Patch Viewer</title> + <para> + This page contains configuration parameters for the CVS server, + Bonsai server and LXR server that Bugzilla will use to enable the + features of the Patch Viewer. Bonsai is a tool that enables queries + to a CVS tree. LXR is a tool that can cross reference and index source + code. + </para> + </section> + + <section id="param-querydefaults"> + <title>Query Defaults</title> + <para> + This page controls the default behavior of Bugzilla in regards to + several aspects of querying bugs. Options include what the default + query options are, what the "My Bugs" page returns, whether users + can freely add bugs to the quip list, and how many duplicate bugs are + needed to add a bug to the "most frequently reported" list. + </para> + </section> + + <section id="param-shadowdatabase"> + <title>Shadow Database</title> + <para> + This page controls whether a shadow database is used, and all the + parameters associated with the shadow database. Versions of Bugzilla + prior to 3.2 used the MyISAM table type, which supports + only table-level write locking. With MyISAM, any time someone is making a change to + a bug, the entire table is locked until the write operation is complete. + Locking for write also blocks reads until the write is complete. + </para> + <para> + The <quote>shadowdb</quote> parameter was designed to get around + this limitation. While only a single user is allowed to write to + a table at a time, reads can continue unimpeded on a read-only + shadow copy of the database. + </para> + + <note> + <para> + As of version 3.2, Bugzilla no longer uses the MyISAM table type. + Instead, InnoDB is used, which can do transaction-based locking. + Therefore, the limitations the Shadow Database feature was designed + to workaround no longer exist. + </para> + </note> + + </section> + + <section id="admin-usermatching"> + <title>User Matching</title> + <para> + The settings on this page control how users are selected and queried + when adding a user to a bug. For example, users need to be selected + when choosing who the bug is assigned to, adding to the CC list or + selecting a QA contact. With the "usemenuforusers" parameter, it is + possible to configure Bugzilla to + display a list of users in the fields instead of an empty text field. + This should only be used in Bugzilla installations with a small number + of users. If users are selected via a text box, this page also + contains parameters for how user names can be queried and matched + when entered. + </para> + + </section> + + </section> + + <section id="useradmin"> + <title>User Administration</title> + + <section id="defaultuser"> + <title>Creating the Default User</title> + + <para>When you first run checksetup.pl after installing Bugzilla, it + will prompt you for the administrative username (email address) and + password for this "super user". If for some reason you delete + the "super user" account, re-running checksetup.pl will again prompt + you for this username and password.</para> + + <tip> + <para>If you wish to add more administrative users, add them to + the "admin" group and, optionally, edit the tweakparams, editusers, + creategroups, editcomponents, and editkeywords groups to add the + entire admin group to those groups (which is the case by default). + </para> + </tip> + </section> + + <section id="manageusers"> + <title>Managing Other Users</title> + + <section id="user-account-search"> + <title>Searching for existing users</title> + + <para> + If you have <quote>editusers</quote> privileges or if you are allowed + to grant privileges for some groups, the <quote>Users</quote> link + will appear in the Administration page. + </para> + + <para> + The first screen is a search form to search for existing user + accounts. You can run searches based either on the user ID, real + name or login name (i.e. the email address, or just the first part + of the email address if the "emailsuffix" parameter is set). + The search can be conducted + in different ways using the listbox to the right of the text entry + box. You can match by case-insensitive substring (the default), + regular expression, a <emphasis>reverse</emphasis> regular expression + match (which finds every user name which does NOT match the regular + expression), or the exact string if you know exactly who you are + looking for. The search can be restricted to users who are in a + specific group. By default, the restriction is turned off. + </para> + + <para> + The search returns a list of + users matching your criteria. User properties can be edited by clicking + the login name. The Account History of a user can be viewed by clicking + the "View" link in the Account History column. The Account History + displays changes that have been made to the user account, the time of + the change and the user who made the change. For example, the Account + History page will display details of when a user was added or removed + from a group. + </para> + </section> + + <section id="createnewusers"> + <title>Creating new users</title> + + <section id="self-registration"> + <title>Self-registration</title> + + <para> + By default, users can create their own user accounts by clicking the + <quote>New Account</quote> link at the bottom of each page (assuming + they aren't logged in as someone else already). If you want to disable + this self-registration, or if you want to restrict who can create his + own user account, you have to edit the <quote>createemailregexp</quote> + parameter in the <quote>Configuration</quote> page, see + <xref linkend="parameters" />. + </para> + </section> + + <section id="user-account-creation"> + <title>Accounts created by an administrator</title> + + <para> + Users with <quote>editusers</quote> privileges, such as administrators, + can create user accounts for other users: + </para> + + <orderedlist> + <listitem> + <para>After logging in, click the "Users" link at the footer of + the query page, and then click "Add a new user".</para> + </listitem> + + <listitem> + <para>Fill out the form presented. This page is self-explanatory. + When done, click "Submit".</para> + + <note> + <para>Adding a user this way will <emphasis>not</emphasis> + send an email informing them of their username and password. + While useful for creating dummy accounts (watchers which + shuttle mail to another system, for instance, or email + addresses which are a mailing list), in general it is + preferable to log out and use the <quote>New Account</quote> + button to create users, as it will pre-populate all the + required fields and also notify the user of her account name + and password.</para> + </note> + </listitem> + </orderedlist> + </section> + </section> + + <section id="modifyusers"> + <title>Modifying Users</title> + + <para>Once you have found your user, you can change the following + fields:</para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Login Name</emphasis>: + This is generally the user's full email address. However, if you + have are using the <quote>emailsuffix</quote> parameter, this may + just be the user's login name. Note that users can now change their + login names themselves (to any valid email address). + </para> + </listitem> + + <listitem> + <para> + <emphasis>Real Name</emphasis>: The user's real name. Note that + Bugzilla does not require this to create an account.</para> + </listitem> + + <listitem> + <para> + <emphasis>Password</emphasis>: + You can change the user's password here. Users can automatically + request a new password, so you shouldn't need to do this often. + If you want to disable an account, see Disable Text below. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Bugmail Disabled</emphasis>: + Mark this checkbox to disable bugmail and whinemail completely + for this account. This checkbox replaces the data/nomail file + which existed in older versions of Bugzilla. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Disable Text</emphasis>: + If you type anything in this box, including just a space, the + user is prevented from logging in, or making any changes to + bugs via the web interface. + The HTML you type in this box is presented to the user when + they attempt to perform these actions, and should explain + why the account was disabled. + </para> + <para> + Users with disabled accounts will continue to receive + mail from Bugzilla; furthermore, they will not be able + to log in themselves to change their own preferences and + stop it. If you want an account (disabled or active) to + stop receiving mail, simply check the + <quote>Bugmail Disabled</quote> checkbox above. + </para> + <note> + <para> + Even users whose accounts have been disabled can still + submit bugs via the e-mail gateway, if one exists. + The e-mail gateway should <emphasis>not</emphasis> be + enabled for secure installations of Bugzilla. + </para> + </note> + <warning> + <para> + Don't disable all the administrator accounts! + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis><groupname></emphasis>: + If you have created some groups, e.g. "securitysensitive", then + checkboxes will appear here to allow you to add users to, or + remove them from, these groups. + </para> + </listitem> + + <listitem> + <para> + <emphasis>canconfirm</emphasis>: + This field is only used if you have enabled the "unconfirmed" + status. If you enable this for a user, + that user can then move bugs from "Unconfirmed" to a "Confirmed" + status (e.g.: "New" status).</para> + </listitem> + + <listitem> + <para> + <emphasis>creategroups</emphasis>: + This option will allow a user to create and destroy groups in + Bugzilla.</para> + </listitem> + + <listitem> + <para> + <emphasis>editbugs</emphasis>: + Unless a user has this bit set, they can only edit those bugs + for which they are the assignee or the reporter. Even if this + option is unchecked, users can still add comments to bugs. + </para> + </listitem> + + <listitem> + <para> + <emphasis>editcomponents</emphasis>: + This flag allows a user to create new products and components, + as well as modify and destroy those that have no bugs associated + with them. If a product or component has bugs associated with it, + those bugs must be moved to a different product or component + before Bugzilla will allow them to be destroyed. + </para> + </listitem> + + <listitem> + <para> + <emphasis>editkeywords</emphasis>: + If you use Bugzilla's keyword functionality, enabling this + feature allows a user to create and destroy keywords. As always, + the keywords for existing bugs containing the keyword the user + wishes to destroy must be changed before Bugzilla will allow it + to die.</para> + </listitem> + + <listitem> + <para> + <emphasis>editusers</emphasis>: + This flag allows a user to do what you're doing right now: edit + other users. This will allow those with the right to do so to + remove administrator privileges from other users or grant them to + themselves. Enable with care.</para> + </listitem> + + + <listitem> + <para> + <emphasis>tweakparams</emphasis>: + This flag allows a user to change Bugzilla's Params + (using <filename>editparams.cgi</filename>.)</para> + </listitem> + + <listitem> + <para> + <emphasis><productname></emphasis>: + This allows an administrator to specify the products + in which a user can see bugs. If you turn on the + <quote>makeproductgroups</quote> parameter in + the Group Security Panel in the Parameters page, + then Bugzilla creates one group per product (at the time you create + the product), and this group has exactly the same name as the + product itself. Note that for products that already exist when + the parameter is turned on, the corresponding group will not be + created. The user must still have the <quote>editbugs</quote> + privilege to edit bugs in these products.</para> + </listitem> + </itemizedlist> + </section> + + <section id="user-account-deletion"> + <title>Deleting Users</title> + <para> + If the <quote>allowuserdeletion</quote> parameter is turned on, see + <xref linkend="parameters" />, then you can also delete user accounts. + Note that this is most of the time not the best thing to do. If only + a warning in a yellow box is displayed, then the deletion is safe. + If a warning is also displayed in a red box, then you should NOT try + to delete the user account, else you will get referential integrity + problems in your database, which can lead to unexpected behavior, + such as bugs not appearing in bug lists anymore, or data displaying + incorrectly. You have been warned! + </para> + </section> + + <section id="impersonatingusers"> + <title>Impersonating Users</title> + + <para> + There may be times when an administrator would like to do something as + another user. The <command>sudo</command> feature may be used to do + this. + </para> + + <note> + <para> + To use the sudo feature, you must be in the + <emphasis>bz_sudoers</emphasis> group. By default, all + administrators are in this group.</para> + </note> + + <para> + If you have access to this feature, you may start a session by + going to the Edit Users page, Searching for a user and clicking on + their login. You should see a link below their login name titled + "Impersonate this user". Click on the link. This will take you + to a page where you will see a description of the feature and + instructions for using it. After reading the text, simply + enter the login of the user you would like to impersonate, provide + a short message explaining why you are doing this, and press the + button.</para> + + <para> + As long as you are using this feature, everything you do will be done + as if you were logged in as the user you are impersonating.</para> + + <warning> + <para> + The user you are impersonating will not be told about what you are + doing. If you do anything that results in mail being sent, that + mail will appear to be from the user you are impersonating. You + should be extremely careful while using this feature.</para> + </warning> + </section> + </section> + </section> + + <section id="classifications" xreflabel="Classifications"> + <title>Classifications</title> + + <para>Classifications tend to be used in order to group several related + products into one distinct entity.</para> + + <para>The classifications layer is disabled by default; it can be turned + on or off using the useclassification parameter, + in the <emphasis>Bug Fields</emphasis> section of the edit parameters screen.</para> + + <para>Access to the administration of classifications is controlled using + the <emphasis>editclassifications</emphasis> system group, which defines + a privilege for creating, destroying, and editing classifications.</para> + + <para>When activated, classifications will introduce an additional + step when filling bugs (dedicated to classification selection), and they + will also appear in the advanced search form.</para> + </section> + + <section id="products" xreflabel="Products"> + <title>Products</title> + + <para> + <glossterm linkend="gloss-product" baseform="product"> + Products</glossterm> typically represent real-world + shipping products. Products can be given + <xref linkend="classifications"/>. + For example, if a company makes computer games, + they could have a classification of "Games", and a separate + product for each game. This company might also have a + <quote>Common</quote> product for units of technology used + in multiple games, and perhaps a few special products that + represent items that are not actually shipping products + (for example, "Website", or "Administration"). + </para> + + <para> + Many of Bugzilla's settings are configurable on a per-product + basis. The number of <quote>votes</quote> available to + users is set per-product, as is the number of votes + required to move a bug automatically from the UNCONFIRMED + status to the NEW status. + </para> + + <para> + When creating or editing products the following options are + available: + </para> + + <variablelist> + + <varlistentry> + <term> + Product + </term> + <listitem> + <para> + The name of the product + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Description + </term> + <listitem> + <para> + A brief description of the product + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + URL describing milestones for this product + </term> + <listitem> + <para> + If there is reference URL, provide it here + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Default milestone + </term> + <listitem> + <para> + Select the default milestone for this product. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Closed for bug entry + </term> + <listitem> + <para> + Select this box to prevent new bugs from being + entered against this product. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Maximum votes per person + </term> + <listitem> + <para> + Maximum votes a user is allowed to give for this + product + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Maximum votes a person can put on a single bug + </term> + <listitem> + <para> + Maximum votes a user is allowed to give for this + product in a single bug + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Confirmation threshold + </term> + <listitem> + <para> + Number of votes needed to automatically remove any + bug against this product from the UNCONFIRMED state + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Version + </term> + <listitem> + <para> + Specify which version of the product bugs will be + entered against. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Create chart datasets for this product + </term> + <listitem> + <para> + Select to make chart datasets available for this product. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + When editing a product there is also a link to edit Group Access Controls, + see <xref linkend="product-group-controls"/>. + </para> + + <section id="create-product"> + <title>Creating New Products</title> + + <para> + To create a new product: + </para> + + <orderedlist> + <listitem> + <para> + Select <quote>Administration</quote> from the footer and then + choose <quote>Products</quote> from the main administration page. + </para> + </listitem> + + <listitem> + <para> + Select the <quote>Add</quote> link in the bottom right. + </para> + </listitem> + + <listitem> + <para> + Enter the name of the product and a description. The + Description field may contain HTML. + </para> + </listitem> + + <listitem> + <para> + When the product is created, Bugzilla will give a message + stating that a component must be created before any bugs can + be entered against the new product. Follow the link to create + a new component. See <xref linkend="components"/> for more + information. + </para> + </listitem> + </orderedlist> + + </section> + + <section id="edit-products"> + <title>Editing Products</title> + + <para> + To edit an existing product, click the "Products" link from the + "Administration" page. If the 'useclassification' parameter is + turned on, a table of existing classifications is displayed, + including an "Unclassified" category. The table indicates how many products + are in each classification. Click on the classification name to see its + products. If the 'useclassification' parameter is not in use, the table + lists all products directly. The product table summarizes the information + about the product defined + when the product was created. Click on the product name to edit these + properties, and to access links to other product attributes such as the + product's components, versions, milestones, and group access controls. + </para> + + </section> + + <section id="comps-vers-miles-products"> + <title>Adding or Editing Components, Versions and Target Milestones</title> + <para> + To edit existing, or add new, Components, Versions or Target Milestones + to a Product, select the "Edit Components", "Edit Versions" or "Edit + Milestones" links from the "Edit Product" page. A table of existing + Components, Versions or Milestones is displayed. Click on a item name + to edit the properties of that item. Below the table is a link to add + a new Component, Version or Milestone. + </para> + <para> + For more information on components, see <xref linkend="components"/>. + </para> + <para> + For more information on versions, see <xref linkend="versions"/>. + </para> + <para> + For more information on milestones, see <xref linkend="milestones"/>. + </para> + </section> + + <section id="product-group-controls"> + <title>Assigning Group Controls to Products</title> + + <para> + On the <quote>Edit Product</quote> page, there is a link called + <quote>Edit Group Access Controls</quote>. The settings on this page + control the relationship of the groups to the product being edited. + </para> + + <para> + Group Access Controls are an important aspect of using groups for + isolating products and restricting access to bugs filed against those + products. For more information on groups, including how to create, edit + add users to, and alter permission of, see <xref linkend="groups"/>. + </para> + + <para> + After selecting the "Edit Group Access Controls" link from the "Edit + Product" page, a table containing all user-defined groups for this + Bugzilla installation is displayed. The system groups that are created + when Bugzilla is installed are not applicable to Group Access Controls. + Below is description of what each of these fields means. + </para> + + <para> + Groups may be applicable (e.g bugs in this product can be associated + with this group) , default (e.g. bugs in this product are in this group + by default), and mandatory (e.g. bugs in this product must be associated + with this group) for each product. Groups can also control access + to bugs for a given product, or be used to make bugs for a product + totally read-only unless the group restrictions are met. The best way to + understand these relationships is by example. See + <xref linkend="group-control-examples"/> for examples of + product and group relationships. + </para> + + <note> + <para> + Products and Groups are not limited to a one-to-one relationship. + Multiple groups can be associated with the same product, and groups + can be associated with more than one product. + </para> + </note> + + <para> + If any group has <emphasis>Entry</emphasis> selected, then the + product will restrict bug entry to only those users + who are members of <emphasis>all</emphasis> the groups with + <emphasis>Entry</emphasis> selected. + </para> + + <para> + If any group has <emphasis>Canedit</emphasis> selected, + then the product will be read-only for any users + who are not members of <emphasis>all</emphasis> of the groups with + <emphasis>Canedit</emphasis> selected. <emphasis>Only</emphasis> users who + are members of all the <emphasis>Canedit</emphasis> groups + will be able to edit bugs for this product. This is an additional + restriction that enables finer-grained control over products rather + than just all-or-nothing access levels. + </para> + + <para> + The following settings let you + choose privileges on a <emphasis>per-product basis</emphasis>. + This is a convenient way to give privileges to + some users for some products only, without having + to give them global privileges which would affect + all products. + </para> + + <para> + Any group having <emphasis>editcomponents</emphasis> + selected allows users who are in this group to edit all + aspects of this product, including components, milestones + and versions. + </para> + + <para> + Any group having <emphasis>canconfirm</emphasis> selected + allows users who are in this group to confirm bugs + in this product. + </para> + + <para> + Any group having <emphasis>editbugs</emphasis> selected allows + users who are in this group to edit all fields of + bugs in this product. + </para> + + <para> + The <emphasis>MemberControl</emphasis> and + <emphasis>OtherControl</emphasis> are used in tandem to determine which + bugs will be placed in this group. The only allowable combinations of + these two parameters are listed in a table on the "Edit Group Access Controls" + page. Consult this table for details on how these fields can be used. + Examples of different uses are described below. + </para> + + <section id="group-control-examples"> + <title>Common Applications of Group Controls</title> + + <para> + The use of groups is best explained by providing examples that illustrate + configurations for common use cases. The examples follow a common syntax: + <emphasis>Group: Entry, MemberControl, OtherControl, CanEdit, + EditComponents, CanConfirm, EditBugs</emphasis>. Where "Group" is the name + of the group being edited for this product. The other fields all + correspond to the table on the "Edit Group Access Controls" page. If any + of these options are not listed, it means they are not checked. + </para> + + <para> + Basic Product/Group Restriction + </para> + + <para> + Suppose there is a product called "Bar". The + "Bar" product can only have bugs entered against it by users in the + group "Foo". Additionally, bugs filed against product "Bar" must stay + restricted to users to "Foo" at all times. Furthermore, only members + of group "Foo" can edit bugs filed against product "Bar", even if other + users could see the bug. This arrangement would achieved by the + following: + </para> + + <programlisting> +Product Bar: +foo: ENTRY, MANDATORY/MANDATORY, CANEDIT + </programlisting> + + <para> + Perhaps such strict restrictions are not needed for product "Bar". A + more lenient way to configure product "Bar" and group "Foo" would be: + </para> + + <programlisting> +Product Bar: +foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS + </programlisting> + + <para> + The above indicates that for product "Bar", members of group "Foo" can + enter bugs. Any one with permission to edit a bug against product "Bar" + can put the bug + in group "Foo", even if they themselves are not in "Foo". Anyone in group + "Foo" can edit all aspects of the components of product "Bar", can confirm + bugs against product "Bar", and can edit all fields of any bug against + product "Bar". + </para> + + <para> + General User Access With Security Group + </para> + + <para> + To permit any user to file bugs against "Product A", + and to permit any user to submit those bugs into a + group called "Security": + </para> + + <programlisting> +Product A: +security: SHOWN/SHOWN + </programlisting> + + <para> + General User Access With A Security Product + </para> + + <para> + To permit any user to file bugs against product called "Security" + while keeping those bugs from becoming visible to anyone + outside the group "SecurityWorkers" (unless a member of the + "SecurityWorkers" group removes that restriction): + </para> + + <programlisting> +Product Security: +securityworkers: DEFAULT/MANDATORY + </programlisting> + + <para> + Product Isolation With a Common Group + </para> + + <para> + To permit users of "Product A" to access the bugs for + "Product A", users of "Product B" to access the bugs for + "Product B", and support staff, who are members of the "Support + Group" to access both, three groups are needed: + </para> + + <orderedlist> + + <listitem> + <para>Support Group: Contains members of the support staff.</para> + </listitem> + + <listitem> + <para>AccessA Group: Contains users of product A and the Support group.</para> + </listitem> + + <listitem> + <para>AccessB Group: Contains users of product B and the Support group.</para> + </listitem> + + </orderedlist> + + <para> + Once these three groups are defined, the product group controls + can be set to: + </para> + + <programlisting> +Product A: +AccessA: ENTRY, MANDATORY/MANDATORY +Product B: +AccessB: ENTRY, MANDATORY/MANDATORY + </programlisting> + + <para> + Perhaps the "Support Group" wants more control. For example, + the "Support Group" could be permitted to make bugs inaccessible to + users of both groups "AccessA" and "AccessB". + Then, the "Support Group" could be permitted to publish + bugs relevant to all users in a third product (let's call it + "Product Common") that is read-only + to anyone outside the "Support Group". In this way the "Support Group" + could control bugs that should be seen by both groups. + That configuration would be: + </para> + + <programlisting> +Product A: +AccessA: ENTRY, MANDATORY/MANDATORY +Support: SHOWN/NA +Product B: +AccessB: ENTRY, MANDATORY/MANDATORY +Support: SHOWN/NA +Product Common: +Support: ENTRY, DEFAULT/MANDATORY, CANEDIT + </programlisting> + + <para> + Make a Product Read Only + </para> + + <para> + Sometimes a product is retired and should no longer have + new bugs filed against it (for example, an older version of a software + product that is no longer supported). A product can be made read-only + by creating a group called "readonly" and adding products to the + group as needed: + </para> + + <programlisting> +Product A: +ReadOnly: ENTRY, NA/NA, CANEDIT + </programlisting> + + <note> + <para> + For more information on Groups outside of how they relate to products + see <xref linkend="groups"/>. + </para> + </note> + + </section> + + </section> + + </section> + + <section id="components" xreflabel="Components"> + <title>Components</title> + + <para>Components are subsections of a Product. E.g. the computer game + you are designing may have a "UI" + component, an "API" component, a "Sound System" component, and a + "Plugins" component, each overseen by a different programmer. It + often makes sense to divide Components in Bugzilla according to the + natural divisions of responsibility within your Product or + company.</para> + + <para> + Each component has a default assignee and (if you turned it on in the parameters), + a QA Contact. The default assignee should be the primary person who fixes bugs in + that component. The QA Contact should be the person who will ensure + these bugs are completely fixed. The Assignee, QA Contact, and Reporter + will get email when new bugs are created in this Component and when + these bugs change. Default Assignee and Default QA Contact fields only + dictate the + <emphasis>default assignments</emphasis>; + these can be changed on bug submission, or at any later point in + a bug's life.</para> + + <para>To create a new Component:</para> + + <orderedlist> + <listitem> + <para>Select the <quote>Edit components</quote> link + from the <quote>Edit product</quote> page</para> + </listitem> + + <listitem> + <para>Select the <quote>Add</quote> link in the bottom right.</para> + </listitem> + + <listitem> + <para>Fill out the <quote>Component</quote> field, a + short <quote>Description</quote>, the + <quote>Default Assignee</quote>, <quote>Default CC List</quote> + and <quote>Default QA Contact</quote> (if enabled). + The <quote>Component Description</quote> field may contain a + limited subset of HTML tags. The <quote>Default Assignee</quote> + field must be a login name already existing in the Bugzilla database. + </para> + </listitem> + </orderedlist> + </section> + + <section id="versions"> + <title>Versions</title> + + <para>Versions are the revisions of the product, such as "Flinders + 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select + field; the usual practice is to select the earliest version known to have + the bug. + </para> + + <para>To create and edit Versions:</para> + + <orderedlist> + <listitem> + <para>From the "Edit product" screen, select "Edit Versions"</para> + </listitem> + + <listitem> + <para>You will notice that the product already has the default + version "undefined". Click the "Add" link in the bottom right.</para> + </listitem> + + <listitem> + <para>Enter the name of the Version. This field takes text only. + Then click the "Add" button.</para> + </listitem> + + </orderedlist> + </section> + + <section id="milestones"> + <title>Milestones</title> + + <para>Milestones are "targets" that you plan to get a bug fixed by. For + example, you have a bug that you plan to fix for your 3.0 release, it + would be assigned the milestone of 3.0.</para> + + <note> + <para>Milestone options will only appear for a Product if you turned + on the "usetargetmilestone" Param in the "Edit Parameters" screen. + </para> + </note> + + <para>To create new Milestones, set Default Milestones, and set + Milestone URL:</para> + + <orderedlist> + <listitem> + <para>Select "Edit milestones" from the "Edit product" page.</para> + </listitem> + + <listitem> + <para>Select "Add" in the bottom right corner. + text</para> + </listitem> + + <listitem> + <para>Enter the name of the Milestone in the "Milestone" field. You + can optionally set the "sortkey", which is a positive or negative + number (-32768 to 32767) that defines where in the list this particular + milestone appears. This is because milestones often do not + occur in alphanumeric order For example, "Future" might be + after "Release 1.2". Select "Add".</para> + </listitem> + + <listitem> + <para>From the Edit product screen, you can enter the URL of a + page which gives information about your milestones and what + they mean. </para> + </listitem> + </orderedlist> + </section> + + <section id="flags-overview"> + <title>Flags</title> + + <para> + Flags are a way to attach a specific status to a bug or attachment, + either <quote>+</quote> or <quote>-</quote>. The meaning of these symbols depends on the text + the flag itself, but contextually they could mean pass/fail, + accept/reject, approved/denied, or even a simple yes/no. If your site + allows requestable flags, then users may set a flag to <quote>?</quote> as a + request to another user that they look at the bug/attachment, and set + the flag to its correct status. + </para> + + <section id="flags-simpleexample"> + <title>A Simple Example</title> + + <para> + A developer might want to ask their manager, + <quote>Should we fix this bug before we release version 2.0?</quote> + They might want to do this for a <emphasis>lot</emphasis> of bugs, + so it would be nice to streamline the process... + </para> + <para> + In Bugzilla, it would work this way: + <orderedlist> + <listitem> + <para> + The Bugzilla administrator creates a flag type called + <quote>blocking2.0</quote> that shows up on all bugs in + your product. + </para> + + <para> + It shows up on the <quote>Show Bug</quote> screen + as the text <quote>blocking2.0</quote> with a drop-down box next + to it. The drop-down box contains four values: an empty space, + <quote>?</quote>, <quote>-</quote>, and <quote>+</quote>. + </para> + </listitem> + <listitem> + <para>The developer sets the flag to <quote>?</quote>.</para> + </listitem> + <listitem> + <para> + The manager sees the <computeroutput>blocking2.0</computeroutput> + flag with a <quote>?</quote> value. + </para> + </listitem> + <listitem> + <para> + If the manager thinks the feature should go into the product + before version 2.0 can be released, he sets the flag to + <quote>+</quote>. Otherwise, he sets it to <quote>-</quote>. + </para> + </listitem> + <listitem> + <para> + Now, every Bugzilla user who looks at the bug knows whether or + not the bug needs to be fixed before release of version 2.0. + </para> + </listitem> + </orderedlist> + </para> + + </section> + + <section id="flags-about"> + <title>About Flags</title> + + <section id="flag-values"> + <title>Values</title> + <para> + Flags can have three values: + <variablelist> + <varlistentry> + <term><computeroutput>?</computeroutput></term> + <listitem><simpara> + A user is requesting that a status be set. (Think of it as 'A question is being asked'.) + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>-</computeroutput></term> + <listitem><simpara> + The status has been set negatively. (The question has been answered <quote>no</quote>.) + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><computeroutput>+</computeroutput></term> + <listitem><simpara> + The status has been set positively. + (The question has been answered <quote>yes</quote>.) + </simpara></listitem> + </varlistentry> + </variablelist> + </para> + <para> + Actually, there's a fourth value a flag can have -- + <quote>unset</quote> -- which shows up as a blank space. This + just means that nobody has expressed an opinion (or asked + someone else to express an opinion) about this bug or attachment. + </para> + </section> + </section> + + <section id="flag-askto"> + <title>Using flag requests</title> + <para> + If a flag has been defined as 'requestable', and a user has enough privileges + to request it (see below), the user can set the flag's status to <quote>?</quote>. + This status indicates that someone (a.k.a. <quote>the requester</quote>) is asking + someone else to set the flag to either <quote>+</quote> or <quote>-</quote>. + </para> + <para> + If a flag has been defined as 'specifically requestable', + a text box will appear next to the flag into which the requester may + enter a Bugzilla username. That named person (a.k.a. <quote>the requestee</quote>) + will receive an email notifying them of the request, and pointing them + to the bug/attachment in question. + </para> + <para> + If a flag has <emphasis>not</emphasis> been defined as 'specifically requestable', + then no such text-box will appear. A request to set this flag cannot be made of + any specific individual, but must be asked <quote>to the wind</quote>. + A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank. + </para> + </section> + + <section id="flag-types"> + <title>Two Types of Flags</title> + + <para> + Flags can go in two places: on an attachment, or on a bug. + </para> + + <section id="flag-type-attachment"> + <title>Attachment Flags</title> + + <para> + Attachment flags are used to ask a question about a specific + attachment on a bug. + </para> + <para> + Many Bugzilla installations use this to + request that one developer <quote>review</quote> another + developer's code before they check it in. They attach the code to + a bug report, and then set a flag on that attachment called + <quote>review</quote> to + <computeroutput>review?boss@domain.com</computeroutput>. + boss@domain.com is then notified by email that + he has to check out that attachment and approve it or deny it. + </para> + + <para> + For a Bugzilla user, attachment flags show up in three places: + <orderedlist> + <listitem> + <para> + On the list of attachments in the <quote>Show Bug</quote> + screen, you can see the current state of any flags that + have been set to ?, +, or -. You can see who asked about + the flag (the requester), and who is being asked (the + requestee). + </para> + </listitem> + <listitem> + <para> + When you <quote>Edit</quote> an attachment, you can + see any settable flag, along with any flags that have + already been set. This <quote>Edit Attachment</quote> + screen is where you set flags to ?, -, +, or unset them. + </para> + </listitem> + <listitem> + <para> + Requests are listed in the <quote>Request Queue</quote>, which + is accessible from the <quote>My Requests</quote> link (if you are + logged in) or <quote>Requests</quote> link (if you are logged out) + visible in the footer of all pages. + </para> + </listitem> + </orderedlist> + </para> + + </section> + + <section id="flag-type-bug"> + <title>Bug Flags</title> + + <para> + Bug flags are used to set a status on the bug itself. You can + see Bug Flags in the <quote>Show Bug</quote> and <quote>Requests</quote> + screens, as described above. + </para> + <para> + Only users with enough privileges (see below) may set flags on bugs. + This doesn't necessarily include the assignee, reporter, or users with the + <computeroutput>editbugs</computeroutput> permission. + </para> + </section> + + </section> + + <section id="flags-admin"> + <title>Administering Flags</title> + + <para> + If you have the <quote>editcomponents</quote> permission, you can + edit Flag Types from the main administration page. Clicking the + <quote>Flags</quote> link will bring you to the <quote>Administer + Flag Types</quote> page. Here, you can select whether you want + to create (or edit) a Bug flag, or an Attachment flag. + </para> + <para> + No matter which you choose, the interface is the same, so we'll + just go over it once. + </para> + + <section id="flags-edit"> + <title>Editing a Flag</title> + <para> + To edit a flag's properties, just click on the <quote>Edit</quote> + link next to the flag's description. That will take you to the same + form as described below (<xref linkend="flags-create"/>). + </para> + </section> + + <section id="flags-create"> + <title>Creating a Flag</title> + + <para> + When you click on the <quote>Create a Flag Type for...</quote> + link, you will be presented with a form. Here is what the fields in + the form mean: + </para> + + <section id="flags-create-field-name"> + <title>Name</title> + <para> + This is the name of the flag. This will be displayed + to Bugzilla users who are looking at or setting the flag. + The name may contain any valid Unicode characters except commas + and spaces. + </para> + </section> + + <section id="flags-create-field-description"> + <title>Description</title> + <para> + The description describes the flag in more detail. It is visible + in a tooltip when hovering over a flag either in the <quote>Show Bug</quote> + or <quote>Edit Attachment</quote> pages. This field can be as + long as you like, and can contain any character you want. + </para> + </section> + + <section id="flags-create-field-category"> + <title>Category</title> + + <para> + Default behaviour for a newly-created flag is to appear on + products and all components, which is why <quote>__Any__:__Any__</quote> + is already entered in the <quote>Inclusions</quote> box. + If this is not your desired behaviour, you must either set some + exclusions (for products on which you don't want the flag to appear), + or you must remove <quote>__Any__:__Any__</quote> from the Inclusions box + and define products/components specifically for this flag. + </para> + + <para> + To create an Inclusion, select a Product from the top drop-down box. + You may also select a specific component from the bottom drop-down box. + (Setting <quote>__Any__</quote> for Product translates to, + <quote>all the products in this Bugzilla</quote>. + Selecting <quote>__Any__</quote> in the Component field means + <quote>all components in the selected product.</quote>) + Selections made, press <quote>Include</quote>, and your + Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right. + </para> + + <para> + To create an Exclusion, the process is the same; select a Product from the + top drop-down box, select a specific component if you want one, and press + <quote>Exclude</quote>. The Product/Component pairing will show up in the + <quote>Exclusions</quote> box on the right. + </para> + + <para> + This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any + products/components that appearing in the <quote>Inclusions</quote> box + (or which fall under the appropriate <quote>__Any__</quote>). + This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on + any products appearing in the <quote>Exclusions</quote> box. + <emphasis> IMPORTANT: Exclusions override inclusions.</emphasis> + </para> + + <para> + You may select a Product without selecting a specific Component, + but you can't select a Component without a Product, or to select a + Component that does not belong to the named Product. If you do so, + Bugzilla will display an error message, even if all your products + have a component by that name. + </para> + + <para><emphasis>Example:</emphasis> Let's say you have a product called + <quote>Jet Plane</quote> that has thousands of components. You want + to be able to ask if a problem should be fixed in the next model of + plane you release. We'll call the flag <quote>fixInNext</quote>. + But, there's one component in <quote>Jet Plane,</quote> + called <quote>Pilot.</quote> It doesn't make sense to release a + new pilot, so you don't want to have the flag show up in that component. + So, you include <quote>Jet Plane:__Any__</quote> and you exclude + <quote>Jet Plane:Pilot</quote>. + </para> + </section> + + <section id="flags-create-field-sortkey"> + <title>Sort Key</title> + <para> + Flags normally show up in alphabetical order. If you want them to + show up in a different order, you can use this key set the order on each flag. + Flags with a lower sort key will appear before flags with a higher + sort key. Flags that have the same sort key will be sorted alphabetically, + but they will still be after flags with a lower sort key, and before flags + with a higher sort key. + </para> + <para> + <emphasis>Example:</emphasis> I have AFlag (Sort Key 100), BFlag (Sort Key 10), + CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in + the order: DFlag, BFlag, CFlag, AFlag. + </para> + </section> + + <section id="flags-create-field-active"> + <title>Active</title> + <para> + Sometimes, you might want to keep old flag information in the + Bugzilla database, but stop users from setting any new flags of this type. + To do this, uncheck <quote>active</quote>. Deactivated + flags will still show up in the UI if they are ?, +, or -, but they + may only be cleared (unset), and cannot be changed to a new value. + Once a deactivated flag is cleared, it will completely disappear from a + bug/attachment, and cannot be set again. + </para> + </section> + + <section id="flags-create-field-requestable"> + <title>Requestable</title> + <para> + New flags are, by default, <quote>requestable</quote>, meaning that they + offer users the <quote>?</quote> option, as well as <quote>+</quote> + and <quote>-</quote>. + To remove the ? option, uncheck <quote>requestable</quote>. + </para> + </section> + + <section id="flags-create-field-specific"> + <title>Specifically Requestable</title> + <para> + By default this box is checked for new flags, meaning that users may make + flag requests of specific individuals. Unchecking this box will remove the + text box next to a flag; if it is still requestable, then requests may + only be made <quote>to the wind.</quote> Removing this after specific + requests have been made will not remove those requests; that data will + stay in the database (though it will no longer appear to the user). + </para> + </section> + + <section id="flags-create-field-multiplicable"> + <title>Multiplicable</title> + <para> + Any flag with <quote>Multiplicable</quote> set (default for new flags is 'on') + may be set more than once. After being set once, an unset flag + of the same type will appear below it with <quote>addl.</quote> (short for + <quote>additional</quote>) before the name. There is no limit to the number of + times a Multiplicable flags may be set on the same bug/attachment. + </para> + </section> + + <section id="flags-create-field-cclist"> + <title>CC List</title> + + <para> + If you want certain users to be notified every time this flag is + set to ?, -, +, or unset, add them here. This is a comma-separated + list of email addresses that need not be restricted to Bugzilla usernames. + </para> + </section> + + <section id="flags-create-grant-group"> + <title>Grant Group</title> + <para> + When this field is set to some given group, only users in the group + can set the flag to <quote>+</quote> and <quote>-</quote>. This + field does not affect who can request or cancel the flag. For that, + see the <quote>Request Group</quote> field below. If this field + is left blank, all users can set or delete this flag. This field is + useful for restricting which users can approve or reject requests. + </para> + </section> + + <section id="flags-create-request-group"> + <title>Request Group</title> + <para> + When this field is set to some given group, only users in the group + can request or cancel this flag. Note that this field has no effect + if the <quote>grant group</quote> field is empty. You can set the + value of this field to a different group, but both fields have to be + set to a group for this field to have an effect. + </para> + </section> + </section> <!-- flags-create --> + + <section id="flags-delete"> + <title>Deleting a Flag</title> + + <para> + When you are at the <quote>Administer Flag Types</quote> screen, + you will be presented with a list of Bug flags and a list of Attachment + Flags. + </para> + <para> + To delete a flag, click on the <quote>Delete</quote> link next to + the flag description. + </para> + <warning> + <para> + Once you delete a flag, it is <emphasis>gone</emphasis> from + your Bugzilla. All the data for that flag will be deleted. + Everywhere that flag was set, it will disappear, + and you cannot get that data back. If you want to keep flag data, + but don't want anybody to set any new flags or change current flags, + unset <quote>active</quote> in the flag Edit form. + </para> + </warning> + </section> + + </section> <!-- flags-admin --> + + <!-- XXX We should add a "Uses of Flags" section, here, with examples. --> + + </section> <!-- flags --> + + <section id="keywords"> + <title>Keywords</title> + + <para> + The administrator can define keywords which can be used to tag and + categorise bugs. For example, the keyword "regression" is commonly used. + A company might have a policy stating all regressions + must be fixed by the next release - this keyword can make tracking those + bugs much easier. + </para> + <para> + Keywords are global, rather than per-product. If the administrator changes + a keyword currently applied to any bugs, the keyword cache must be rebuilt + using the <xref linkend="sanitycheck"/> script. Currently keywords can not + be marked obsolete to prevent future usage. + </para> + <para> + Keywords can be created, edited or deleted by clicking the "Keywords" + link in the admin page. There are two fields for each keyword - the keyword + itself and a brief description. Once created, keywords can be selected + and applied to individual bugs in that bug's "Details" section. + </para> + </section> + + <section id="custom-fields"> + <title>Custom Fields</title> + + <para> + The release of Bugzilla 3.0 added the ability to create Custom Fields. + Custom Fields are treated like any other field - they can be set in bugs + and used for search queries. Administrators should keep in mind that + adding too many fields can make the user interface more complicated and + harder to use. Custom Fields should be added only when necessary and with + careful consideration. + </para> + <tip> + <para> + Before adding a Custom Field, make sure that Bugzilla can not already + do the desired behavior. Many Bugzilla options are not enabled by + default, and many times Administrators find that simply enabling + certain options that already exist is sufficient. + </para> + </tip> + <para> + Administrators can manage Custom Fields using the + <quote>Custom Fields</quote> link on the Administration page. The Custom + Fields administration page displays a list of Custom Fields, if any exist, + and a link to "Add a new custom field". + </para> + + <section id="add-custom-fields"> + <title>Adding Custom Fields</title> + + <para> + To add a new Custom Field, click the "Add a new custom field" link. This + page displays several options for the new field, described below. + </para> + + <para> + The following attributes must be set for each new custom field: + <itemizedlist> + <listitem> + <para> + <emphasis>Name:</emphasis> + The name of the field in the database, used internally. This name + MUST begin with <quote>cf_</quote> to prevent confusion with + standard fields. If this string is omitted, it will + be automatically added to the name entered. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Description:</emphasis> + A brief string which is used as the label for this Custom Field. + That is the string that users will see, and should be + short and explicit. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Type:</emphasis> + The type of field to create. There are + several types available: + <simplelist> + <member> + Large Text Box: A multiple line box for entering free text. + </member> + <member> + Free Text: A single line box for entering free text. + </member> + <member> + Multiple-Selection Box: A list box where multiple options + can be selected. After creating this field, it must be edited + to add the selection options. See + <xref linkend="edit-values-list" /> for information about + editing legal values. + </member> + <member> + Drop Down: A list box where only one option can be selected. + After creating this field, it must be edited to add the + selection options. See + <xref linkend="edit-values-list" /> for information about + editing legal values. + </member> + <member> + Date/Time: A date field. This field appears with a + calendar widget for choosing the date. + </member> + </simplelist> + </para> + </listitem> + + <listitem> + <para> + <emphasis>Sortkey:</emphasis> + Integer that determines in which order Custom Fields are + displayed in the User Interface, especially when viewing a bug. + Fields with lower values are displayed first. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Can be set on bug creation:</emphasis> + Boolean that determines whether this field can be set on + bug creation. If not selected, then a bug must be created + before this field can be set. See <xref linkend="bugreports" /> + for information about filing bugs. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Displayed in bugmail for new bugs:</emphasis> + Boolean that determines whether the value set on this field + should appear in bugmail when the bug is filed. This attribute + has no effect if the field cannot be set on bug creation. + </para> + </listitem> + + <listitem> + <para> + <emphasis>Is obsolete:</emphasis> + Boolean that determines whether this field should + be displayed at all. Obsolete Custom Fields are hidden. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="edit-custom-fields"> + <title>Editing Custom Fields</title> + + <para> + As soon as a Custom Field is created, its name and type cannot be + changed. If this field is a drop down menu, its legal values can + be set as described in <xref linkend="edit-values-list" />. All + other attributes can be edited as described above. + </para> + </section> + + <section id="delete-custom-fields"> + <title>Deleting Custom Fields</title> + + <para> + It is only possible to delete obsolete Custom Fields + if the field has never been used in the database. + To remove a field which already has content, + mark it as obsolete. + </para> + </section> + </section> + + <section id="edit-values"> + <title>Legal Values</title> + + <para> + Since Bugzilla 2.20 RC1, legal values for Operating Systems, platforms, + bug priorities and severities can be edited from the User Interface + directly. This means that it is no longer required to manually edit + <filename>localconfig</filename>. Starting with Bugzilla 2.23.3, + the list of valid resolutions can be customized from the same interface. + Since Bugzilla 3.1.1 the list of valid bug statuses can be customized + as well. + </para> + + <section id="edit-values-list"> + <title>Viewing/Editing legal values</title> + <para> + Editing legal values requires <quote>admin</quote> privileges. + Select "Legal Values" from the Administration page. A list of all + fields, both system fields and Custom Fields, for which legal values + can be edited appears. Click a field name to edit its legal values. + </para> + <para> + There is no limit to how many values a field can have, but each value + must be unique to that field. The sortkey is important to display these + values in the desired order. + </para> + </section> + + <section id="edit-values-delete"> + <title>Deleting legal values</title> + <para> + Legal values from Custom Fields can be deleted, but only if the + following two conditions are respected: + </para> + + <orderedlist> + <listitem> + <para>The value is not used by default for the field.</para> + </listitem> + + <listitem> + <para>No bug is currently using this value.</para> + </listitem> + </orderedlist> + + <para> + If any of these conditions is not respected, the value cannot be deleted. + The only way to delete these values is to reassign bugs to another value + and to set another value as default for the field. + </para> + </section> + </section> + + <section id="bug_status_workflow"> + <title>Bug Status Workflow</title> + + <para> + The bug status workflow is no longer hardcoded but can be freely customized + from the web interface. Only one bug status cannot be renamed nor deleted, + UNCONFIRMED, but the workflow involving it is free. The configuration + page displays all existing bug statuses twice, first on the left for bug + statuses we come from and on the top for bug statuses we move to. + If the checkbox is checked, then the transition between the two bug statuses + is legal, else it's forbidden independently of your privileges. The bug status + used for the "duplicate_or_move_bug_status" parameter must be part of the + workflow as that is the bug status which will be used when duplicating or + moving a bug, so it must be available from each bug status. + </para> + <para> + When the workflow is set, the "View Current Triggers" link below the table + lets you set which transitions require a comment from the user. + </para> + </section> + + <section id="voting"> + <title>Voting</title> + + <para>Voting allows users to be given a pot of votes which they can allocate + to bugs, to indicate that they'd like them fixed. + This allows developers to gauge + user need for a particular enhancement or bugfix. By allowing bugs with + a certain number of votes to automatically move from "UNCONFIRMED" to + "NEW", users of the bug system can help high-priority bugs garner + attention so they don't sit for a long time awaiting triage.</para> + + <para>To modify Voting settings:</para> + + <orderedlist> + <listitem> + <para>Navigate to the "Edit product" screen for the Product you + wish to modify</para> + </listitem> + + <listitem> + <para><emphasis>Maximum Votes per person</emphasis>: + Setting this field to "0" disables voting.</para> + </listitem> + + <listitem> + <para><emphasis>Maximum Votes a person can put on a single + bug</emphasis>: + It should probably be some number lower than the + "Maximum votes per person". Don't set this field to "0" if + "Maximum votes per person" is non-zero; that doesn't make + any sense.</para> + </listitem> + + <listitem> + <para><emphasis>Number of votes a bug in this product needs to + automatically get out of the UNCONFIRMED state</emphasis>: + Setting this field to "0" disables the automatic move of + bugs from UNCONFIRMED to NEW. + </para> + </listitem> + + <listitem> + <para>Once you have adjusted the values to your preference, click + "Update".</para> + </listitem> + </orderedlist> + </section> + + <section id="quips"> + <title>Quips</title> + + <para> + Quips are small text messages that can be configured to appear + next to search results. A Bugzilla installation can have its own specific + quips. Whenever a quip needs to be displayed, a random selection + is made from the pool of already existing quips. + </para> + + <para> + Quips are controlled by the <emphasis>enablequips</emphasis> parameter. + It has several possible values: on, approved, frozen or off. + In order to enable quips approval you need to set this parameter + to "approved". In this way, users are free to submit quips for + addition but an administrator must explicitly approve them before + they are actually used. + </para> + + <para> + In order to see the user interface for the quips, it is enough to click + on a quip when it is displayed together with the search results. Or + it can be seen directly in the browser by visiting the quips.cgi URL + (prefixed with the usual web location of the Bugzilla installation). + Once the quip interface is displayed, it is enough to click the + "view and edit the whole quip list" in order to see the administration + page. A page with all the quips available in the database will + be displayed. + </para> + + <para> + Next to each tip there is a checkbox, under the + "Approved" column. Quips who have this checkbox checked are + already approved and will appear next to the search results. + The ones that have it unchecked are still preserved in the + database but they will not appear on search results pages. + User submitted quips have initially the checkbox unchecked. + </para> + + <para> + Also, there is a delete link next to each quip, + which can be used in order to permanently delete a quip. + </para> + </section> + + <section id="groups"> + <title>Groups and Group Security</title> + + <para> + Groups allow for separating bugs into logical divisions. + Groups are typically used to + to isolate bugs that should only be seen by certain people. For + example, a company might create a different group for each one of its customers + or partners. Group permissions could be set so that each partner or customer would + only have access to their own bugs. Or, groups might be used to create + variable access controls for different departments within an organization. + Another common use of groups is to associate groups with products, + creating isolation and access control on a per-product basis. + </para> + + <para> + Groups and group behaviors are controlled in several places: + </para> + + <orderedlist> + + <listitem> + <para> + The group configuration page. To view or edit existing groups, or to + create new groups, access the "Groups" link from the "Administration" + page. This section of the manual deals primarily with the aspect of + group controls accessed on this page. + </para> + </listitem> + + <listitem> + <para> + Global configuration parameters. Bugzilla has several parameters + that control the overall default group behavior and restriction + levels. For more information on the parameters that control + group behavior globally, see <xref linkend="param-group-security"/>. + </para> + + </listitem> + + <listitem> + <para> + Product association with groups. Most of the functionality of groups + and group security is controlled at the product level. Some aspects + of group access controls for products are discussed in this section, + but for more detail see <xref linkend="product-group-controls"/>. + </para> + </listitem> + + <listitem> + <para> + Group access for users. See <xref linkend="users-and-groups"/> for + details on how users are assigned group access. + </para> + </listitem> + + </orderedlist> + + <para> + Group permissions are such that if a bug belongs to a group, only members + of that group can see the bug. If a bug is in more than one group, only + members of <emphasis>all</emphasis> the groups that the bug is in can see + the bug. For information on granting read-only access to certain people and + full edit access to others, see <xref linkend="product-group-controls"/>. + </para> + + <note> + <para> + By default, bugs can also be seen by the Assignee, the Reporter, and + by everyone on the CC List, regardless of whether or not the bug would + typically be viewable by them. Visibility to the Reporter and CC List can + be overridden (on a per-bug basis) by bringing up the bug, finding the + section that starts with <quote>Users in the roles selected below...</quote> + and un-checking the box next to either 'Reporter' or 'CC List' (or both). + </para> + </note> + + <section id="create-groups"> + <title>Creating Groups</title> + + <para> + To create a new group, follow the steps below: + </para> + + <orderedlist> + + <listitem> + <para> + Select the <quote>Administration</quote> link in the page footer, + and then select the <quote>Groups</quote> link from the + Administration page. + </para> + </listitem> + + <listitem> + <para> + A table of all the existing groups is displayed. Below the table is a + description of all the fields. To create a new group, select the + <quote>Add Group</quote> link under the table of existing groups. + </para> + </listitem> + + <listitem> + <para> + There are five fields to fill out. These fields are documented below + the form. Choose a name and description for the group. Decide whether + this group should be used for bugs (in all likelihood this should be + selected). Optionally, choose a regular expression that will + automatically add any matching users to the group, and choose an + icon that will help identify user comments for the group. The regular + expression can be useful, for example, to automatically put all users + from the same company into one group (if the group is for a specific + customer or partner). + </para> + <note> + <para> + If <quote>User RegExp</quote> is filled out, users whose email + addresses match the regular expression will automatically be + members of the group as long as their email addresses continue + to match the regular expression. If their email address changes + and no longer matches the regular expression, they will be removed + from the group. Versions 2.16 and older of Bugzilla did not automatically + remove users who's email addresses no longer matched the RegExp. + </para> + </note> + <warning> + <para> + If specifying a domain in the regular expression, end + the regexp with a "$". Otherwise, when granting access to + "@mycompany\.com", access will also be granted to + 'badperson@mycompany.com.cracker.net'. Use the syntax, + '@mycompany\.com$' for the regular expression. + </para> + </warning> + </listitem> + + <listitem> + <para> + After the new group is created, it can be edited for additional options. + The "Edit Group" page allows for specifying other groups that should be included + in this group and which groups should be permitted to add and delete + users from this group. For more details, see <xref linkend="edit-groups"/>. + </para> + </listitem> + </orderedlist> + + </section> + + <section id="edit-groups"> + <title>Editing Groups and Assigning Group Permissions</title> + + <para> + To access the "Edit Groups" page, select the + <quote>Administration</quote> link in the page footer, + and then select the <quote>Groups</quote> link from the Administration page. + A table of all the existing groups is displayed. Click on a group name + you wish to edit or control permissions for. + </para> + + <para> + The "Edit Groups" page contains the same five fields present when + creating a new group. Below that are two additional sections, "Group + Permissions," and "Mass Remove". The "Mass Remove" option simply removes + all users from the group who match the regular expression entered. The + "Group Permissions" section requires further explanation. + </para> + + <para> + The "Group Permissions" section on the "Edit Groups" page contains four sets + of permissions that control the relationship of this group to other + groups. If the 'usevisibilitygroups' parameter is in use (see + <xref linkend="parameters"/>) two additional sets of permissions are displayed. + Each set consists of two select boxes. On the left, a select box + with a list of all existing groups. On the right, a select box listing + all groups currently selected for this permission setting (this box will + be empty for new groups). The way these controls allow groups to relate + to one another is called <emphasis>inheritance</emphasis>. + Each of the six permissions is described below. + </para> + + <variablelist> + + <varlistentry> + + <term> + <emphasis>Groups That Are a Member of This Group</emphasis> + </term> + + <listitem> + <para> + Members of any groups selected here will automatically have + membership in this group. In other words, members of any selected + group will inherit membership in this group. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + + <term> + <emphasis>Groups That This Group Is a Member Of</emphasis> + </term> + + <listitem> + <para> + Members of this group will inherit membership to any group + selected here. For example, suppose the group being edited is + an Admin group. If there are two products (Product1 and Product2) + and each product has its + own group (Group1 and Group2), and the Admin group + should have access to both products, + simply select both Group1 and Group2 here. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + + <term> + <emphasis>Groups That Can Grant Membership in This Group</emphasis> + </term> + + <listitem> + <para> + The members of any group selected here will be able add users + to this group, even if they themselves are not in this group. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + + <term> + <emphasis>Groups That This Group Can Grant Membership In</emphasis> + </term> + + <listitem> + <para> + Members of this group can add users to any group selected here, + even if they themselves are not in the selected groups. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + + <term> + <emphasis>Groups That Can See This Group</emphasis> + </term> + + <listitem> + <para> + Members of any selected group can see the users in this group. + This setting is only visible if the 'usevisibilitygroups' parameter + is enabled on the Bugzilla Configuration page. See + <xref linkend="parameters"/> for information on configuring Bugzilla. + </para> + </listitem> + + </varlistentry> + + <varlistentry> + + <term> + <emphasis>Groups That This Group Can See</emphasis> + </term> + + <listitem> + <para> + Members of this group can see members in any of the selected groups. + This setting is only visible if the 'usevisibilitygroups' parameter + is enabled on the the Bugzilla Configuration page. See + <xref linkend="parameters"/> for information on configuring Bugzilla. + </para> + </listitem> + + </varlistentry> + + </variablelist> + + </section> + + <section id="users-and-groups"> + <title>Assigning Users to Groups</title> + + <para> + A User can become a member of a group in several ways: + </para> + + <orderedlist> + + <listitem> + <para> + The user can be explicitly placed in the group by editing + the user's profile. This can be done by accessing the "Users" page + from the "Administration" page. Use the search form to find the user + you want to edit group membership for, and click on their email + address in the search results to edit their profile. The profile + page lists all the groups, and indicates if the user is a member of + the group either directly or indirectly. More information on indirect + group membership is below. For more details on User administration, + see <xref linkend="useradmin"/>. + </para> + </listitem> + + <listitem> + <para> + The group can include another group of which the user is + a member. This is indicated by square brackets around the checkbox + next to the group name in the user's profile. + See <xref linkend="edit-groups"/> for details on group inheritance. + </para> + </listitem> + + <listitem> + <para> + The user's email address can match the regular expression + that has been specified to automatically grant membership to + the group. This is indicated by "*" around the check box by the + group name in the user's profile. + See <xref linkend="create-groups"/> for details on + the regular expression option when creating groups. + </para> + </listitem> + + </orderedlist> + + </section> + + <section> + <title>Assigning Group Controls to Products</title> + + <para> + The primary functionality of groups is derived from the relationship of + groups to products. The concepts around segregating access to bugs with + product group controls can be confusing. For details and examples on this + topic, see <xref linkend="product-group-controls" />. + </para> + + </section> + + </section> + + <section id="sanitycheck"> + <title>Checking and Maintaining Database Integrity</title> + + <para> + Over time it is possible for the Bugzilla database to become corrupt + or to have anomalies. + This could happen through normal usage of Bugzilla, manual database + administration outside of the Bugzilla user interface, or from some + other unexpected event. Bugzilla includes a "Sanity Check" script that + can perform several basic database checks, and repair certain problems or + inconsistencies. + </para> + <para> + To run the "Sanity Check" script, log in as an Administrator and click the + "Sanity Check" link in the admin page. Any problems that are found will be + displayed in red letters. If the script is capable of fixing a problem, + it will present a link to initiate the fix. If the script can not + fix the problem it will require manual database administration or recovery. + </para> + <para> + The "Sanity Check" script can also be run from the command line via the perl + script <filename>sanitycheck.pl</filename>. The script can also be run as + a <command>cron</command> job. Results will be delivered by email. + </para> + <para> + The "Sanity Check" script should be run on a regular basis as a matter of + best practice. + </para> + <warning> + <para> + The "Sanity Check" script is no substitute for a competent database + administrator. It is only designed to check and repair basic database + problems. + </para> + </warning> + + </section> + + <section id="upgrading"> + <title>Upgrading to New Releases</title> + + <para> + Upgrading Bugzilla is something we all want to do from time to time, + be it to get new features or pick up the latest security fix. How easy + it is to update depends on a few factors: + </para> + + <itemizedlist> + <listitem> + <para> + If the new version is a revision or a new point release + </para> + </listitem> + <listitem> + <para> + How many local changes (if any) have been made + </para> + </listitem> + </itemizedlist> + + <section id="upgrading-version-defns"> + <title>Version Definitions</title> + + <para> + Bugzilla displays the version you are using at the top of the home + page <filename>index.cgi</filename>. It looks something like + '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is + the Major Version. This does not change very often; + Bugzilla was 1.x.x when it was first created, and went to 2.x.x + when it was re-written in perl in Sept 1998. The major version + 3.x.x, released in early 2007, is pretty far from what the 2.x.x + series looked like, both about its UI and its code. + </para> + + <para> + The second number in the version is called the 'minor number', and + a release that changes the minor number is called a 'point release'. + An even number in this position (2.18, 2.20, 2.22, 3.0, 3.2, etc.) + represents a stable version, while an odd number (2.19, 2.21, 2.23, etc.) + represents a development version. In the past, stable point releases + were feature-based, coming when certain enhancements had been + completed, or the Bugzilla development team felt that enough + progress had been made overall. As of version 2.18, however, + Bugzilla has moved to a time-based release schedule; current plans + are to create a stable point release every 6 months or so after + 2.18 is deployed. + </para> + + <para> + The third number in the Bugzilla version represents a bugfix version. + Bugfix Revisions are released only to address security vulnerabilities + and, for a limited period, bug fixes. Once enough of these + bugfixes have accumulated (or a new security vulnerability is + identified and closed), a bugfix release is made. As an + example, 2.20.3 was a bugfix release, and improved on 2.20.2. + </para> + + <note> + <para> + When reading version numbers, everything separated by a point ('.') + should be read as a single number. It is <emphasis>not</emphasis> + the same as decimal. 2.22 is newer than 2.8 because minor version + 22 is greater than minor version 8. The now unsupported release 2.16.11 + was newer than 2.16.9 (because bugfix 11 is greater than bugfix 9. This is + confusing to some people who aren't used to dealing with software. + </para> + </note> + </section> + + <section id="upgrading-notifications"> + <title>Upgrading - Notifications</title> + + <para> + Bugzilla 3.0 introduces the ability to automatically notify + administrators when new releases are available, based on the + <literal>upgrade_notification</literal> parameter, see + <xref linkend="parameters"/>. Administrators will see these + notifications when they access the <filename>index.cgi</filename> + page, i.e. generally when logging in. Bugzilla will check once per + day for new releases, unless the parameter is set to + <quote>disabled</quote>. If you are behind a proxy, you may have to set + the <literal>proxy_url</literal> parameter accordingly. If the proxy + requires authentication, use the + <literal>http://user:pass@proxy_url/</literal> syntax. + </para> + </section> + + <section id="upgrading-methods"> + <title>Upgrading - Methods and Procedure</title> + <para> + There are three different ways to upgrade your installation. + </para> + + <orderedlist> + <listitem> + <para> + Using CVS (<xref linkend="upgrade-cvs"/>) + </para> + </listitem> + <listitem> + <para> + Downloading a new tarball (<xref linkend="upgrade-tarball"/>) + </para> + </listitem> + <listitem> + <para> + Applying the relevant patches (<xref linkend="upgrade-patches"/>) + </para> + </listitem> + </orderedlist> + + <para> + Each of these options has its own pros and cons; the one that's + right for you depends on how long it has been since you last + installed, the degree to which you have customized your installation, + and/or your network configuration. (Some discussion of the various + methods of updating compared with degree and methods of local + customization can be found in <xref linkend="template-method"/>.) + </para> + + <para> + The larger the jump you are trying to make, the more difficult it + is going to be to upgrade if you have made local customizations. + Upgrading from 2.22 to 2.22.1 should be fairly painless even if + you are heavily customized, but going from 2.18 to 3.0 is going + to mean a fair bit of work re-writing your local changes to use + the new files, logic, templates, etc. If you have done no local + changes at all, however, then upgrading should be approximately + the same amount of work regardless of how long it has been since + your version was released. + </para> + + <warning> + <para> + Upgrading is a one-way process. You should backup your database + and current Bugzilla directory before attempting the upgrade. If + you wish to revert to the old Bugzilla version for any reason, you + will have to restore from these backups. + </para> + </warning> + + <para> + The examples in the following sections are written as though the + user were updating to version 2.22.1, but the procedures are the + same regardless of whether one is updating to a new point release + or simply trying to obtain a new bugfix release. Also, in the + examples the user's Bugzilla installation is found at + <filename>/var/www/html/bugzilla</filename>. If that is not the + same as the location of your Bugzilla installation, simply + substitute the proper paths where appropriate. + </para> + + <section id="upgrade-cvs"> + <title>Upgrading using CVS</title> + + <para> + Every release of Bugzilla, whether it is a point release or a bugfix, + is tagged in CVS. Also, every tarball that has been distributed since + version 2.12 has been created in such a way that it can be used with + CVS once it is unpacked. Doing so, however, requires that you are able + to access cvs-mirror.mozilla.org on port 2401, which may not be an + option or a possibility for some users, especially those behind a + highly restrictive firewall. + </para> + + <tip> + <para> + If you can, updating using CVS is probably the most painless + method, especially if you have a lot of local changes. + </para> + </tip> + + <para> + The following shows the sequence of commands needed to update a + Bugzilla installation via CVS, and a typical series of results. + </para> + + <programlisting> +bash$ <command>cd /var/www/html/bugzilla</command> +bash$ <command>cvs login</command> +Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot +CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis> +bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command> +P checksetup.pl +P collectstats.pl +P docs/rel_notes.txt +P template/en/default/list/quips.html.tmpl +<emphasis>(etc.)</emphasis> + </programlisting> + + <caution> + <para> + If a line in the output from <command>cvs update</command> begins + with a <computeroutput>C</computeroutput>, then that represents a + file with local changes that CVS was unable to properly merge. You + need to resolve these conflicts manually before Bugzilla (or at + least the portion using that file) will be usable. + </para> + </caution> + </section> + + <section id="upgrade-tarball"> + <title>Upgrading using the tarball</title> + + <para> + If you are unable (or unwilling) to use CVS, another option that's + always available is to obtain the latest tarball from the <ulink + url="http://www.bugzilla.org/download/">Download Page</ulink> and + create a new Bugzilla installation from that. + </para> + + <para> + This sequence of commands shows how to get the tarball from the + command-line; it is also possible to download it from the site + directly in a web browser. If you go that route, save the file + to the <filename class="directory">/var/www/html</filename> + directory (or its equivalent, if you use something else) and + omit the first three lines of the example. + </para> + + <programlisting> +bash$ <command>cd /var/www/html</command> +bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command> +<emphasis>(Output omitted)</emphasis> +bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command> +bugzilla-2.22.1/ +bugzilla-2.22.1/.cvsignore +<emphasis>(Output truncated)</emphasis> +bash$ <command>cd bugzilla-2.22.1</command> +bash$ <command>cp ../bugzilla/localconfig* .</command> +bash$ <command>cp -r ../bugzilla/data .</command> +bash$ <command>cd ..</command> +bash$ <command>mv bugzilla bugzilla.old</command> +bash$ <command>mv bugzilla-2.22.1 bugzilla</command> + </programlisting> + + <warning> + <para> + The <command>cp</command> commands both end with periods which + is a very important detail, it tells the shell that the destination + directory is the current working directory. + </para> + </warning> + + <para> + This upgrade method will give you a clean install of Bugzilla with the + same version as the tarball. That's fine if you don't have any local + customizations that you want to maintain, but if you do then you will + need to reapply them by hand to the appropriate files. + </para> + + <para> + It's worth noting that since 2.12, the Bugzilla tarballs come + CVS-ready, so if you decide at a later date that you'd rather use + CVS as an upgrade method, your code will already be set up for it. + </para> + </section> + + <section id="upgrade-patches"> + <title>Upgrading using patches</title> + + <para> + If you are doing a bugfix upgrade -- that is, one where only the + last number of the revision changes, such as from 2.22 to 2.22.1 + -- then you have the option of obtaining and applying a patch file + from the <ulink + url="http://www.bugzilla.org/download/">Download Page</ulink>. + This file is made available by the <ulink + url="http://www.bugzilla.org/developers/profiles.html">Bugzilla + Development Team</ulink>, and is a collection of all the bug fixes + and security patches that have been made since the last bugfix + release. If you are planning to upgrade via patches, it is safer + to grab this developer-made patch file than to read the patch + notes and apply all (or even just some of) the patches oneself, + as sometimes patches on bugs get changed before they get checked in. + </para> + + <para> + As above, this example starts with obtaining the file via the + command line. If you have already downloaded it, you can omit the + first two commands. + </para> + + <programlisting> +bash$ <command>cd /var/www/html/bugzilla</command> +bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command> +<emphasis>(Output omitted)</emphasis> +bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command> +bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command> +patching file checksetup.pl +patching file collectstats.pl +<emphasis>(etc.)</emphasis> + </programlisting> + + <warning> + <para> + Be aware that upgrading from a patch file does not change the + entries in your <filename class="directory">CVS</filename> directory. + This could make it more difficult to upgrade using CVS + (<xref linkend="upgrade-cvs"/>) in the future. + </para> + </warning> + + </section> + </section> + + <section id="upgrading-completion"> + <title>Completing Your Upgrade</title> + + <para> + Regardless of which upgrade method you choose, you will need to + run <command>./checksetup.pl</command> before your Bugzilla + upgrade will be complete. + </para> + + <programlisting> +bash$ <command>cd bugzilla</command> +bash$ <command>./checksetup.pl</command> + </programlisting> + + <warning> + <para> + The period at the beginning of the command + <command>./checksetup.pl</command> is important and can not + be omitted. + </para> + </warning> + + <para> + If you have done a lot of local modifications, it wouldn't hurt + to run the Bugzilla Testing suite. This is not a required step, + but it isn't going to hurt anything, and might help point out + some areas that could be improved. (More information on the + test suite can be had by following this link to the appropriate + section in the <ulink + url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers' + Guide</ulink>.) + </para> + + </section> + </section> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml new file mode 100644 index 000000000..70e6624f7 --- /dev/null +++ b/docs/en/xml/conventions.xml @@ -0,0 +1,164 @@ +<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<section id="conventions"> + <title>Document Conventions</title> + + <indexterm zone="conventions"> + <primary>conventions</primary> + </indexterm> + + <para>This document uses the following conventions:</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Descriptions</entry> + + <entry>Appearance</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Caution</entry> + + <entry> + <caution> + <para>Don't run with scissors!</para> + </caution> + </entry> + </row> + + <row> + <entry>Hint or Tip</entry> + + <entry> + <tip> + <para>For best results... </para> + </tip> + </entry> + </row> + + <row> + <entry>Note</entry> + + <entry> + <note> + <para>Dear John...</para> + </note> + </entry> + </row> + + <row> + <entry>Warning</entry> + + <entry> + <warning> + <para>Read this or the cat gets it.</para> + </warning> + </entry> + </row> + + <row> + <entry>File or directory name</entry> + + <entry> + <filename>filename</filename> + </entry> + </row> + + <row> + <entry>Command to be typed</entry> + + <entry> + <command>command</command> + </entry> + </row> + + <row> + <entry>Application name</entry> + + <entry> + <application>application</application> + </entry> + </row> + + <row> + <entry> + Normal user's prompt under bash shell</entry> + + <entry>bash$</entry> + </row> + + <row> + <entry> + Root user's prompt under bash shell</entry> + + <entry>bash#</entry> + </row> + + <row> + <entry> + Normal user's prompt under tcsh shell</entry> + + <entry>tcsh$</entry> + </row> + + <row> + <entry>Environment variables</entry> + + <entry> + <envar>VARIABLE</envar> + </entry> + </row> + + <row> + <entry>Term found in the glossary</entry> + + <entry> + <glossterm linkend="gloss-bugzilla">Bugzilla</glossterm> + </entry> + </row> + + <row> + <entry>Code example</entry> + + <entry> + <programlisting><sgmltag class="starttag">para</sgmltag> +Beginning and end of paragraph +<sgmltag class="endtag">para</sgmltag></programlisting> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + This documentation is maintained in DocBook 4.1.2 XML format. + Changes are best submitted as plain text or XML diffs, attached + to a bug filed in the &bzg-bugs; component. + </para> + +</section> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml new file mode 100644 index 000000000..bb89cb12b --- /dev/null +++ b/docs/en/xml/customization.xml @@ -0,0 +1,820 @@ +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<chapter id="customization"> + <title>Customizing Bugzilla</title> + + <section id="cust-skins"> + <title>Custom Skins</title> + + <para> + Bugzilla allows you to have multiple skins. These are custom CSS and possibly + also custom images for Bugzilla. To create a new custom skin, you have two + choices: + <itemizedlist> + <listitem> + <para> + Make a single CSS file, and put it in the + <filename>skins/contrib</filename> directory. + </para> + </listitem> + <listitem> + <para> + Make a directory that contains all the same CSS file + names as <filename>skins/standard/</filename>, and put + your directory in <filename>skins/contrib/</filename>. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + After you put the file or the directory there, make sure to run checksetup.pl + so that it can reset the file permissions correctly. + </para> + <para> + After you have installed the new skin, it will show up as an option in the + user's General Preferences. If you would like to force a particular skin on all + users, just select it in the Default Preferences and then uncheck "Enabled" on + the preference. + </para> + </section> + + <section id="cust-templates"> + <title>Template Customization</title> + + <para> + Administrators can configure the look and feel of Bugzilla without + having to edit Perl files or face the nightmare of massive merge + conflicts when they upgrade to a newer version in the future. + </para> + + <para> + Templatization also makes localized versions of Bugzilla possible, + for the first time. It's possible to have Bugzilla's UI language + determined by the user's browser. More information is available in + <xref linkend="template-http-accept"/>. + </para> + + <section id="template-directory"> + <title>Template Directory Structure</title> + <para> + The template directory structure starts with top level directory + named <filename>template</filename>, which contains a directory + for each installed localization. The next level defines the + language used in the templates. Bugzilla comes with English + templates, so the directory name is <filename>en</filename>, + and we will discuss <filename>template/en</filename> throughout + the documentation. Below <filename>template/en</filename> is the + <filename>default</filename> directory, which contains all the + standard templates shipped with Bugzilla. + </para> + + <warning> + <para> + A directory <filename>data/templates</filename> also exists; + this is where Template Toolkit puts the compiled versions of + the templates from either the default or custom directories. + <emphasis>Do not</emphasis> directly edit the files in this + directory, or all your changes will be lost the next time + Template Toolkit recompiles the templates. + </para> + </warning> + </section> + + <section id="template-method"> + <title>Choosing a Customization Method</title> + <para> + If you want to edit Bugzilla's templates, the first decision + you must make is how you want to go about doing so. There are two + choices, and which you use depends mainly on the scope of your + modifications, and the method you plan to use to upgrade Bugzilla. + </para> + + <para> + The first method of making customizations is to directly edit the + templates found in <filename>template/en/default</filename>. + This is probably the best way to go about it if you are going to + be upgrading Bugzilla through CVS, because if you then execute + a <command>cvs update</command>, any changes you have made will + be merged automagically with the updated versions. + </para> + + <note> + <para> + If you use this method, and CVS conflicts occur during an + update, the conflicted templates (and possibly other parts + of your installation) will not work until they are resolved. + </para> + </note> + + <para> + The second method is to copy the templates to be modified + into a mirrored directory structure under + <filename>template/en/custom</filename>. Templates in this + directory structure automatically override any identically-named + and identically-located templates in the + <filename>default</filename> directory. + </para> + + <note> + <para> + The <filename>custom</filename> directory does not exist + at first and must be created if you want to use it. + </para> + </note> + + <para> + The second method of customization should be used if you + use the overwriting method of upgrade, because otherwise + your changes will be lost. This method may also be better if + you are using the CVS method of upgrading and are going to make major + changes, because it is guaranteed that the contents of this directory + will not be touched during an upgrade, and you can then decide whether + to continue using your own templates, or make the effort to merge your + changes into the new versions by hand. + </para> + + <para> + Using this method, your installation may break if incompatible + changes are made to the template interface. Such changes should + be documented in the release notes, provided you are using a + stable release of Bugzilla. If you use using unstable code, you will + need to deal with this one yourself, although if possible the changes + will be mentioned before they occur in the deprecations section of the + previous stable release's release notes. + </para> + + <note> + <para> + Regardless of which method you choose, it is recommended that + you run <command>./checksetup.pl</command> after creating or + editing any templates in the <filename>template/en/default</filename> + directory, and after editing any templates in the + <filename>custom</filename> directory. + </para> + </note> + + <warning> + <para> + It is <emphasis>required</emphasis> that you run + <command>./checksetup.pl</command> after creating a new + template in the <filename>custom</filename> directory. Failure + to do so will raise an incomprehensible error message. + </para> + </warning> + </section> + + <section id="template-edit"> + <title>How To Edit Templates</title> + + <note> + <para> + If you are making template changes that you intend on submitting back + for inclusion in standard Bugzilla, you should read the relevant + sections of the + <ulink url="http://www.bugzilla.org/docs/developer.html">Developers' + Guide</ulink>. + </para> + </note> + + <para> + The syntax of the Template Toolkit language is beyond the scope of + this guide. It's reasonably easy to pick up by looking at the current + templates; or, you can read the manual, available on the + <ulink url="http://www.template-toolkit.org">Template Toolkit home + page</ulink>. + </para> + + <para> + One thing you should take particular care about is the need + to properly HTML filter data that has been passed into the template. + This means that if the data can possibly contain special HTML characters + such as <, and the data was not intended to be HTML, they need to be + converted to entity form, i.e. &lt;. You use the 'html' filter in the + Template Toolkit to do this. If you forget, you may open up + your installation to cross-site scripting attacks. + </para> + + <para> + Also note that Bugzilla adds a few filters of its own, that are not + in standard Template Toolkit. In particular, the 'url_quote' filter + can convert characters that are illegal or have special meaning in URLs, + such as &, to the encoded form, i.e. %26. This actually encodes most + characters (but not the common ones such as letters and numbers and so + on), including the HTML-special characters, so there's never a need to + HTML filter afterwards. + </para> + + <para> + Editing templates is a good way of doing a <quote>poor man's custom + fields</quote>. + For example, if you don't use the Status Whiteboard, but want to have + a free-form text entry box for <quote>Build Identifier</quote>, + then you can just + edit the templates to change the field labels. It's still be called + status_whiteboard internally, but your users don't need to know that. + </para> + + </section> + + + <section id="template-formats"> + <title>Template Formats and Types</title> + + <para> + Some CGI's have the ability to use more than one template. For example, + <filename>buglist.cgi</filename> can output itself as RDF, or as two + formats of HTML (complex and simple). The mechanism that provides this + feature is extensible. + </para> + + <para> + Bugzilla can support different types of output, which again can have + multiple formats. In order to request a certain type, you can append + the &ctype=<contenttype> (such as rdf or html) to the + <filename><cginame>.cgi</filename> URL. If you would like to + retrieve a certain format, you can use the &format=<format> + (such as simple or complex) in the URL. + </para> + + <para> + To see if a CGI supports multiple output formats and types, grep the + CGI for <quote>get_format</quote>. If it's not present, adding + multiple format/type support isn't too hard - see how it's done in + other CGIs, e.g. config.cgi. + </para> + + <para> + To make a new format template for a CGI which supports this, + open a current template for + that CGI and take note of the INTERFACE comment (if present.) This + comment defines what variables are passed into this template. If + there isn't one, I'm afraid you'll have to read the template and + the code to find out what information you get. + </para> + + <para> + Write your template in whatever markup or text style is appropriate. + </para> + + <para> + You now need to decide what content type you want your template + served as. The content types are defined in the + <filename>Bugzilla/Constants.pm</filename> file in the + <filename>contenttypes</filename> + constant. If your content type is not there, add it. Remember + the three- or four-letter tag assigned to your content type. + This tag will be part of the template filename. + </para> + + <note> + <para> + After adding or changing a content type, it's suitable to edit + <filename>Bugzilla/Constants.pm</filename> in order to reflect + the changes. Also, the file should be kept up to date after an + upgrade if content types have been customized in the past. + </para> + </note> + + <para> + Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>. + Try out the template by calling the CGI as + <filename><cginame>.cgi?format=<formatname>&ctype=<type></filename> . + </para> + </section> + + + <section id="template-specific"> + <title>Particular Templates</title> + + <para> + There are a few templates you may be particularly interested in + customizing for your installation. + </para> + + <para> + <command>index.html.tmpl</command>: + This is the Bugzilla front page. + </para> + + <para> + <command>global/header.html.tmpl</command>: + This defines the header that goes on all Bugzilla pages. + The header includes the banner, which is what appears to users + and is probably what you want to edit instead. However the + header also includes the HTML HEAD section, so you could for + example add a stylesheet or META tag by editing the header. + </para> + + <para> + <command>global/banner.html.tmpl</command>: + This contains the <quote>banner</quote>, the part of the header + that appears + at the top of all Bugzilla pages. The default banner is reasonably + barren, so you'll probably want to customize this to give your + installation a distinctive look and feel. It is recommended you + preserve the Bugzilla version number in some form so the version + you are running can be determined, and users know what docs to read. + </para> + + <para> + <command>global/footer.html.tmpl</command>: + This defines the footer that goes on all Bugzilla pages. Editing + this is another way to quickly get a distinctive look and feel for + your Bugzilla installation. + </para> + + <para> + <command>global/variables.none.tmpl</command>: + This defines a list of terms that may be changed in order to + <quote>brand</quote> the Bugzilla instance In this way, terms + like <quote>bugs</quote> can be replaced with <quote>issues</quote> + across the whole Bugzilla installation. The name + <quote>Bugzilla</quote> and other words can be customized as well. + </para> + + <para> + <command>list/table.html.tmpl</command>: + This template controls the appearance of the bug lists created + by Bugzilla. Editing this template allows per-column control of + the width and title of a column, the maximum display length of + each entry, and the wrap behaviour of long entries. + For long bug lists, Bugzilla inserts a 'break' every 100 bugs by + default; this behaviour is also controlled by this template, and + that value can be modified here. + </para> + + <para> + <command>bug/create/user-message.html.tmpl</command>: + This is a message that appears near the top of the bug reporting page. + By modifying this, you can tell your users how they should report + bugs. + </para> + + <para> + <command>bug/process/midair.html.tmpl</command>: + This is the page used if two people submit simultaneous changes to the + same bug. The second person to submit their changes will get this page + to tell them what the first person did, and ask if they wish to + overwrite those changes or go back and revisit the bug. The default + title and header on this page read "Mid-air collision detected!" If + you work in the aviation industry, or other environment where this + might be found offensive (yes, we have true stories of this happening) + you'll want to change this to something more appropriate for your + environment. + </para> + + <para> + <command>bug/create/create.html.tmpl</command> and + <command>bug/create/comment.txt.tmpl</command>: + You may not wish to go to the effort of creating custom fields in + Bugzilla, yet you want to make sure that each bug report contains + a number of pieces of important information for which there is not + a special field. The bug entry system has been designed in an + extensible fashion to enable you to add arbitrary HTML widgets, + such as drop-down lists or textboxes, to the bug entry page + and have their values appear formatted in the initial comment. + A hidden field that indicates the format should be added inside + the form in order to make the template functional. Its value should + be the suffix of the template filename. For example, if the file + is called <filename>create-cust.html.tmpl</filename>, then + <programlisting><input type="hidden" name="format" value="cust"></programlisting> + should be used inside the form. + </para> + + <para> + An example of this is the mozilla.org + <ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&format=guided">guided + bug submission form</ulink>. The code for this comes with the Bugzilla + distribution as an example for you to copy. It can be found in the + files + <filename>create-guided.html.tmpl</filename> and + <filename>comment-guided.html.tmpl</filename>. + </para> + + <para> + So to use this feature, create a custom template for + <filename>enter_bug.cgi</filename>. The default template, on which you + could base it, is + <filename>custom/bug/create/create.html.tmpl</filename>. + Call it <filename>create-<formatname>.html.tmpl</filename>, and + in it, add widgets for each piece of information you'd like + collected - such as a build number, or set of steps to reproduce. + </para> + + <para> + Then, create a template like + <filename>custom/bug/create/comment.txt.tmpl</filename>, and call it + <filename>comment-<formatname>.txt.tmpl</filename>. This + template should reference the form fields you have created using + the syntax <filename>[% form.<fieldname> %]</filename>. When a + bug report is + submitted, the initial comment attached to the bug report will be + formatted according to the layout of this template. + </para> + + <para> + For example, if your custom enter_bug template had a field + <programlisting><input type="text" name="buildid" size="30"></programlisting> + and then your comment.txt.tmpl had + <programlisting>BuildID: [% form.buildid %]</programlisting> + then something like + <programlisting>BuildID: 20020303</programlisting> + would appear in the initial comment. + </para> + </section> + + + <section id="template-http-accept"> + <title>Configuring Bugzilla to Detect the User's Language</title> + + <para>Bugzilla honours the user's Accept: HTTP header. You can install + templates in other languages, and Bugzilla will pick the most appropriate + according to a priority order defined by you. Many + language templates can be obtained from <ulink + url="http://www.bugzilla.org/download.html#localizations"/>. Instructions + for submitting new languages are also available from that location. + </para> + </section> + + </section> + + <section id="cust-hooks"> + <title>The Bugzilla Extension Mechanism</title> + + <warning> + <para> + Custom extensions require Template Toolkit version 2.12 or + above, or the application of a patch. See <ulink + url="http://bugzilla.mozilla.org/show_bug.cgi?id=239112">bug + 239112</ulink> for details. + </para> + </warning> + + <para> + Extensions are a way for extensions to Bugzilla to insert code + into the standard Bugzilla templates and source files + without modifying these files themselves. The extension mechanism + defines a consistent API for extending the standard templates and source files + in a way that cleanly separates standard code from extension code. + Hooks reduce merge conflicts and make it easier to write extensions that work + across multiple versions of Bugzilla, making upgrading a Bugzilla installation + with installed extensions easier. Furthermore, they make it easy to install + and remove extensions as each extension is nothing more than a + simple directory structure. + </para> + + <para> + There are two main types of hooks: code hooks and template hooks. Code + hooks allow extensions to invoke code at specific points in various + source files, while template hooks allow extensions to add elements to + the Bugzilla user interface. + </para> + + <para> + A hook is just a named place in a standard source or template file + where extension source code or template files for that hook get processed. + Each extension has a corresponding directory in the Bugzilla directory + tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>). Hooking + an extension source file or template to a hook is as simple as putting + the extension file into extension's template or code directory. + When Bugzilla processes the source file or template and reaches the hook, + it will process all extension files in the hook's directory. + The hooks themselves can be added into any source file or standard template + upon request by extension authors. + </para> + + <para> + To use hooks to extend Bugzilla, first make sure there is + a hook at the appropriate place within the source file or template you + want to extend. The exact appearance of a hook depends on if the hook + is a code hook or a template hook. + </para> + + <para> + Code hooks appear in Bugzilla source files as a single method call + in the format <literal role="code">Bugzilla::Hook->process("<varname>name</varname>");</literal>. + For instance, <filename>enter_bug.cgi</filename> may invoke the hook + "<varname>enter_bug-entrydefaultvars</varname>". Thus, a source file at + <filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename> + will be automatically invoked when the code hook is reached. + </para> + + <para> + Template hooks appear in the standard Bugzilla templates as a + single directive in the format + <literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>, + where <varname>name</varname> is the unique name of the hook. + </para> + + <para> + If you aren't sure what you want to extend or just want to browse the + available hooks, either use your favorite multi-file search + tool (e.g. <command>grep</command>) to search the standard templates + for occurrences of <methodname>Hook.process</methodname> or the source + files for occurrences of <methodname>Bugzilla::Hook::process</methodname>. + </para> + + <para> + If there is no hook at the appropriate place within the Bugzilla + source file or template you want to extend, + <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface">file + a bug requesting one</ulink>, specifying: + </para> + + <simplelist> + <member>the source or template file for which you are + requesting a hook;</member> + <member> + where in the file you would like the hook to be placed + (line number/position for latest version of the file in CVS + or description of location); + </member> + <member>the purpose of the hook;</member> + <member>a link to information about your extension, if any.</member> + </simplelist> + + <para> + The Bugzilla reviewers will promptly review each hook request, + name the hook, add it to the template or source file, and check + the new version of the template into CVS. + </para> + + <para> + You may optionally attach a patch to the bug which implements the hook + and check it in yourself after receiving approval from a Bugzilla + reviewer. The developers may suggest changes to the location of the + hook based on their analysis of your needs or so the hook can satisfy + the needs of multiple extensions, but the process of getting hooks + approved and checked in is not as stringent as the process for general + changes to Bugzilla, and any extension, whether released or still in + development, can have hooks added to meet their needs. + </para> + + <para> + After making sure the hook you need exists (or getting it added if not), + add your extension to the directory within the Bugzilla + extensions tree corresponding to the hook. + </para> + + <para> + That's it! Now, when the source file or template containing the hook + is processed, your extension file will be processed at the point + where the hook appears. + </para> + + <para> + For example, let's say you have an extension named Projman that adds + project management capabilities to Bugzilla. Projman has an + administration interface <filename>edit-projects.cgi</filename>, + and you want to add a link to it into the navigation bar at the bottom + of every Bugzilla page for those users who are authorized + to administer projects. + </para> + + <para> + The navigation bar is generated by the template file + <filename>useful-links.html.tmpl</filename>, which is located in + the <filename>global/</filename> subdirectory on the standard Bugzilla + template path + <filename>BUGZILLA_ROOT/template/en/default/</filename>. + Looking in <filename>useful-links.html.tmpl</filename>, you find + the following hook at the end of the list of standard Bugzilla + administration links: + </para> + + <programlisting><![CDATA[... + [% ', <a href="editkeywords.cgi">keywords</a>' + IF user.groups.editkeywords %] + [% Hook.process("edit") %] +...]]></programlisting> + + <para> + The corresponding extension file for this hook is + <filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl</filename>. + You then create that template file and add the following constant: + </para> + + <programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting> + + <para> + Voila! The link now appears after the other administration links in the + navigation bar for users in the <literal>projman_admins</literal> group. + </para> + + <para> + Now, let us say your extension adds a custom "project_manager" field + to enter_bug.cgi. You want to modify the CGI script to set the default + project manager to be productname@company.com. Looking at + <filename>enter_bug.cgi</filename>, you see the enter_bug-entrydefaultvars + hook near the bottom of the file before the default form values are set. + The corresponding extension source file for this hook is located at + <filename>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</filename>. + You then create that file and add the following: + </para> + + <programlisting>$default{'project_manager'} = $product.'@company.com';</programlisting> + + <para> + This code will be invoked whenever enter_bug.cgi is executed. + Assuming that the rest of the customization was completed (e.g. the + custom field was added to the enter_bug template and the required hooks + were used in process_bug.cgi), the new field will now have this + default value. + </para> + + <para> + Notes: + </para> + + <itemizedlist> + <listitem> + <para> + If your extension includes entirely new templates in addition to + extensions of standard templates, it should store those new + templates in its + <filename>BUGZILLA_ROOT/extensions/template/en/</filename> + directory. Extension template directories, like the + <filename>default/</filename> and <filename>custom/</filename> + directories, are part of the template search path, so putting templates + there enables them to be found by the template processor. + </para> + + <para> + The template processor looks for templates first in the + <filename>custom/</filename> directory (i.e. templates added by the + specific installation), then in the <filename>extensions/</filename> + directory (i.e. templates added by extensions), and finally in the + <filename>default/</filename> directory (i.e. the standard Bugzilla + templates). Thus, installation-specific templates override both + default and extension templates. + </para> + </listitem> + + <listitem> + <para> + If you are looking to customize Bugzilla, you can also take advantage + of template hooks. To do so, create a directory in + <filename>BUGZILLA_ROOT/template/en/custom/hook/</filename> + that corresponds to the hook you wish to use, then place your + customization templates into those directories. For example, + if you wanted to use the hook "end" in + <filename>global/useful-links.html.tmpl</filename>, you would + create the directory <filename>BUGZILLA_ROOT/template/en/custom/hook/ + global/useful-links.html.tmpl/end/</filename> and add your customization + template to this directory. + </para> + + <para> + Obviously this method of customizing Bugzilla only lets you add code + to the standard source files and templates; you cannot change the + existing code. Nevertheless, for those customizations that only add + code, this method can reduce conflicts when merging changes, + making upgrading your customized Bugzilla installation easier. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="cust-change-permissions"> + <title>Customizing Who Can Change What</title> + + <warning> + <para> + This feature should be considered experimental; the Bugzilla code you + will be changing is not stable, and could change or move between + versions. Be aware that if you make modifications as outlined here, + you may have + to re-make them or port them if Bugzilla changes internally between + versions, and you upgrade. + </para> + </warning> + + <para> + Companies often have rules about which employees, or classes of employees, + are allowed to change certain things in the bug system. For example, + only the bug's designated QA Contact may be allowed to VERIFY the bug. + Bugzilla has been + designed to make it easy for you to write your own custom rules to define + who is allowed to make what sorts of value transition. + </para> + + <para> + By default, assignees, QA owners and users + with <emphasis>editbugs</emphasis> privileges can edit all fields of bugs, + except group restrictions (unless they are members of the groups they + are trying to change). Bug reporters also have the ability to edit some + fields, but in a more restrictive manner. Other users, without + <emphasis>editbugs</emphasis> privileges, can not edit + bugs, except to comment and add themselves to the CC list. + </para> + + <para> + For maximum flexibility, customizing this means editing Bugzilla's Perl + code. This gives the administrator complete control over exactly who is + allowed to do what. The relevant method is called + <filename>check_can_change_field()</filename>, + and is found in <filename>Bug.pm</filename> in your + Bugzilla/ directory. If you open that file and search for + <quote>sub check_can_change_field</quote>, you'll find it. + </para> + + <para> + This function has been carefully commented to allow you to see exactly + how it works, and give you an idea of how to make changes to it. + Certain marked sections should not be changed - these are + the <quote>plumbing</quote> which makes the rest of the function work. + In between those sections, you'll find snippets of code like: + <programlisting> # Allow the assignee to change anything. + if ($ownerid eq $whoid) { + return 1; + }</programlisting> + It's fairly obvious what this piece of code does. + </para> + + <para> + So, how does one go about changing this function? Well, simple changes + can be made just by removing pieces - for example, if you wanted to + prevent any user adding a comment to a bug, just remove the lines marked + <quote>Allow anyone to change comments.</quote> If you don't want the + Reporter to have any special rights on bugs they have filed, just + remove the entire section that deals with the Reporter. + </para> + + <para> + More complex customizations are not much harder. Basically, you add + a check in the right place in the function, i.e. after all the variables + you are using have been set up. So, don't look at $ownerid before + $ownerid has been obtained from the database. You can either add a + positive check, which returns 1 (allow) if certain conditions are true, + or a negative check, which returns 0 (deny.) E.g.: + <programlisting> if ($field eq "qacontact") { + if (Bugzilla->user->groups("quality_assurance")) { + return 1; + } + else { + return 0; + } + }</programlisting> + This says that only users in the group "quality_assurance" can change + the QA Contact field of a bug. + </para> + + <para> + Getting more weird: + <programlisting><![CDATA[ if (($field eq "priority") && + (Bugzilla->user->email =~ /.*\@example\.com$/)) + { + if ($oldvalue eq "P1") { + return 1; + } + else { + return 0; + } + }]]></programlisting> + This says that if the user is trying to change the priority field, + and their email address is @example.com, they can only do so if the + old value of the field was "P1". Not very useful, but illustrative. + </para> + + <warning> + <para> + If you are modifying <filename>process_bug.cgi</filename> in any + way, do not change the code that is bounded by DO_NOT_CHANGE blocks. + Doing so could compromise security, or cause your installation to + stop working entirely. + </para> + </warning> + + <para> + For a list of possible field names, look at the bugs table in the + database. If you need help writing custom rules for your organization, + ask in the newsgroup. + </para> + </section> + + <!-- Integrating Bugzilla with Third-Party Tools --> + &integration; + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml new file mode 100644 index 000000000..1d84d1255 --- /dev/null +++ b/docs/en/xml/gfdl.xml @@ -0,0 +1,445 @@ +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<appendix id="gfdl"> + <title>GNU Free Documentation License</title> + +<!-- - GNU Project - Free Software Foundation (FSF) --> +<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" --> +<!-- section> + <title>GNU Free Documentation License</title --> + <para>Version 1.1, March 2000</para> + + <blockquote> + <para>Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, + Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and + distribute verbatim copies of this license document, but changing it is + not allowed.</para> + </blockquote> + + <section label="0" id="gfdl-0"> + <title>Preamble</title> + + <para>The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone the + effective freedom to copy and redistribute it, with or without modifying + it, either commercially or noncommercially. Secondarily, this License + preserves for the author and publisher a way to get credit for their + work, while not being considered responsible for modifications made by + others.</para> + + <para>This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. It + complements the GNU General Public License, which is a copyleft license + designed for free software.</para> + + <para>We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a free + program should come with manuals providing the same freedoms that the + software does. But this License is not limited to software manuals; it + can be used for any textual work, regardless of subject matter or whether + it is published as a printed book. We recommend this License principally + for works whose purpose is instruction or reference.</para> + </section> + + <section label="1" id="gfdl-1"> + <title>Applicability and Definition</title> + + <para>This License applies to any manual or other work that contains a + notice placed by the copyright holder saying it can be distributed under + the terms of this License. The "Document", below, refers to any such + manual or work. Any member of the public is a licensee, and is addressed + as "you".</para> + + <para>A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language.</para> + + <para>A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall subject + (or to related matters) and contains nothing that could fall directly + within that overall subject. (For example, if the Document is in part a + textbook of mathematics, a Secondary Section may not explain any + mathematics.) The relationship could be a matter of historical connection + with the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding them.</para> + + <para>The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License.</para> + + <para>The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says + that the Document is released under this License.</para> + + <para>A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the general + public, whose contents can be viewed and edited directly and + straightforwardly with generic text editors or (for images composed of + pixels) generic paint programs or (for drawings) some widely available + drawing editor, and that is suitable for input to text formatters or for + automatic translation to a variety of formats suitable for input to text + formatters. A copy made in an otherwise Transparent file format whose + markup has been designed to thwart or discourage subsequent modification + by readers is not Transparent. A copy that is not "Transparent" is called + "Opaque".</para> + + <para>Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, SGML or + XML using a publicly available DTD, and standard-conforming simple HTML + designed for human modification. Opaque formats include PostScript, PDF, + proprietary formats that can be read and edited only by proprietary word + processors, SGML or XML for which the DTD and/or processing tools are not + generally available, and the machine-generated HTML produced by some word + processors for output purposes only.</para> + + <para>The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the material + this License requires to appear in the title page. For works in formats + which do not have any title page as such, "Title Page" means the text + near the most prominent appearance of the work's title, preceding the + beginning of the body of the text.</para> + </section> + + <section label="2" id="gfdl-2"> + <title>Verbatim Copying</title> + + <para>You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License applies to + the Document are reproduced in all copies, and that you add no other + conditions whatsoever to those of this License. You may not use technical + measures to obstruct or control the reading or further copying of the + copies you make or distribute. However, you may accept compensation in + exchange for copies. If you distribute a large enough number of copies + you must also follow the conditions in section 3.</para> + + <para>You may also lend copies, under the same conditions stated above, + and you may publicly display copies.</para> + </section> + + <section label="3" id="gfdl-3"> + <title>Copying in Quantity</title> + + <para>If you publish printed copies of the Document numbering more than + 100, and the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all these + Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts + on the back cover. Both covers must also clearly and legibly identify you + as the publisher of these copies. The front cover must present the full + title with all words of the title equally prominent and visible. You may + add other material on the covers in addition. Copying with changes + limited to the covers, as long as they preserve the title of the Document + and satisfy these conditions, can be treated as verbatim copying in other + respects.</para> + + <para>If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit reasonably) + on the actual cover, and continue the rest onto adjacent pages.</para> + + <para>If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with each + Opaque copy a publicly-accessible computer-network location containing a + complete Transparent copy of the Document, free of added material, which + the general network-using public has access to download anonymously at no + charge using public-standard network protocols. If you use the latter + option, you must take reasonably prudent steps, when you begin + distribution of Opaque copies in quantity, to ensure that this + Transparent copy will remain thus accessible at the stated location until + at least one year after the last time you distribute an Opaque copy + (directly or through your agents or retailers) of that edition to the + public.</para> + + <para>It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, to + give them a chance to provide you with an updated version of the + Document.</para> + </section> + + <section label="4" id="gfdl-4"> + <title>Modifications</title> + + <para>You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you release + the Modified Version under precisely this License, with the Modified + Version filling the role of the Document, thus licensing distribution and + modification of the Modified Version to whoever possesses a copy of it. + In addition, you must do these things in the Modified Version:</para> + + <orderedlist numeration="upperalpha"> + <listitem> + <para>Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the History + section of the Document). You may use the same title as a previous + version if the original publisher of that version gives + permission.</para> + </listitem> + + <listitem> + <para>List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has less + than five).</para> + </listitem> + + <listitem> + <para>State on the Title page the name of the publisher of the + Modified Version, as the publisher.</para> + </listitem> + + <listitem> + <para>Preserve all the copyright notices of the Document.</para> + </listitem> + + <listitem> + <para>Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.</para> + </listitem> + + <listitem> + <para>Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version under + the terms of this License, in the form shown in the Addendum + below.</para> + </listitem> + + <listitem> + <para>Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's license + notice.</para> + </listitem> + + <listitem> + <para>Include an unaltered copy of this License.</para> + </listitem> + + <listitem> + <para>Preserve the section entitled "History", and its title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence.</para> + </listitem> + + <listitem> + <para>Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions it + was based on. These may be placed in the "History" section. You may + omit a network location for a work that was published at least four + years before the Document itself, or if the original publisher of the + version it refers to gives permission.</para> + </listitem> + + <listitem> + <para>In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements and/or + dedications given therein.</para> + </listitem> + + <listitem> + <para>Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the equivalent + are not considered part of the section titles.</para> + </listitem> + + <listitem> + <para>Delete any section entitled "Endorsements". Such a section may + not be included in the Modified Version.</para> + </listitem> + + <listitem> + <para>Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section.</para> + </listitem> + </orderedlist> + + <para>If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no material + copied from the Document, you may at your option designate some or all of + these sections as invariant. To do this, add their titles to the list of + Invariant Sections in the Modified Version's license notice. These titles + must be distinct from any other section titles.</para> + + <para>You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various parties--for + example, statements of peer review or that the text has been approved by + an organization as the authoritative definition of a standard.</para> + + <para>You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of the + list of Cover Texts in the Modified Version. Only one passage of + Front-Cover Text and one of Back-Cover Text may be added by (or through + arrangements made by) any one entity. If the Document already includes a + cover text for the same cover, previously added by you or by arrangement + made by the same entity you are acting on behalf of, you may not add + another; but you may replace the old one, on explicit permission from the + previous publisher that added the old one.</para> + + <para>The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to assert + or imply endorsement of any Modified Version.</para> + </section> + + <section label="5" id="gfdl-5"> + <title>Combining Documents</title> + + <para>You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for modified + versions, provided that you include in the combination all of the + Invariant Sections of all of the original documents, unmodified, and list + them all as Invariant Sections of your combined work in its license + notice.</para> + + <para>The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single copy. + If there are multiple Invariant Sections with the same name but different + contents, make the title of each such section unique by adding at the end + of it, in parentheses, the name of the original author or publisher of + that section if known, or else a unique number. Make the same adjustment + to the section titles in the list of Invariant Sections in the license + notice of the combined work.</para> + + <para>In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section entitled + "History"; likewise combine any sections entitled "Acknowledgements", and + any sections entitled "Dedications". You must delete all sections + entitled "Endorsements."</para> + </section> + + <section label="6" id="gfdl-6"> + <title>Collections of Documents</title> + + <para>You may make a collection consisting of the Document and other + documents released under this License, and replace the individual copies + of this License in the various documents with a single copy that is + included in the collection, provided that you follow the rules of this + License for verbatim copying of each of the documents in all other + respects.</para> + + <para>You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert a copy + of this License into the extracted document, and follow this License in + all other respects regarding verbatim copying of that document.</para> + </section> + + <section label="7" id="gfdl-7"> + <title>Aggregation with Independent Works</title> + + <para>A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, does not as a whole count as a Modified + Version of the Document, provided no compilation copyright is claimed for + the compilation. Such a compilation is called an "aggregate", and this + License does not apply to the other self-contained works thus compiled + with the Document, on account of their being thus compiled, if they are + not themselves derivative works of the Document.</para> + + <para>If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one quarter of + the entire aggregate, the Document's Cover Texts may be placed on covers + that surround only the Document within the aggregate. Otherwise they must + appear on covers around the whole aggregate.</para> + </section> + + <section label="8" id="gfdl-8"> + <title>Translation</title> + + <para>Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section 4. + Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include translations + of some or all Invariant Sections in addition to the original versions of + these Invariant Sections. You may include a translation of this License + provided that you also include the original English version of this + License. In case of a disagreement between the translation and the + original English version of this License, the original English version + will prevail.</para> + </section> + + <section label="9" id="gfdl-9"> + <title>Termination</title> + + <para>You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other attempt to + copy, modify, sublicense or distribute the Document is void, and will + automatically terminate your rights under this License. However, parties + who have received copies, or rights, from you under this License will not + have their licenses terminated so long as such parties remain in full + compliance.</para> + </section> + + <section label="10" id="gfdl-10"> + <title>Future Revisions of this License</title> + + <para>The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new versions + will be similar in spirit to the present version, but may differ in + detail to address new problems or concerns. See + <ulink url="http://www.gnu.org/copyleft/"/>.</para> + + <para>Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered version of + this License "or any later version" applies to it, you have the option of + following the terms and conditions either of that specified version or of + any later version that has been published (not as a draft) by the Free + Software Foundation. If the Document does not specify a version number of + this License, you may choose any version ever published (not as a draft) + by the Free Software Foundation.</para> + </section> + + <section label="" id="gfdl-howto"> + <title>How to use this License for your documents</title> + + <para>To use this License in a document you have written, include a copy + of the License in the document and put the following copyright and + license notices just after the title page:</para> + + <blockquote> + <para>Copyright (c) YEAR YOUR NAME. Permission is granted to copy, + distribute and/or modify this document under the terms of the GNU Free + Documentation License, Version 1.1 or any later version published by + the Free Software Foundation; with the Invariant Sections being LIST + THEIR TITLES, with the Front-Cover Texts being LIST, and with the + Back-Cover Texts being LIST. A copy of the license is included in the + section entitled "GNU Free Documentation License".</para> + </blockquote> + + <para>If you have no Invariant Sections, write "with no Invariant + Sections" instead of saying which ones are invariant. If you have no + Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover + Texts being LIST"; likewise for Back-Cover Texts.</para> + + <para>If your document contains nontrivial examples of program code, we + recommend releasing these examples in parallel under your choice of free + software license, such as the GNU General Public License, to permit their + use in free software.</para> + </section> +</appendix> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml new file mode 100644 index 000000000..5b6d1a6e7 --- /dev/null +++ b/docs/en/xml/glossary.xml @@ -0,0 +1,551 @@ +<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> +<glossary id="glossary"> + <glossdiv> + <title>0-9, high ascii</title> + + <glossentry id="gloss-htaccess"> + <glossterm>.htaccess</glossterm> + + <glossdef> + <para>Apache web server, and other NCSA-compliant web servers, + observe the convention of using files in directories called + <filename>.htaccess</filename> + + to restrict access to certain files. In Bugzilla, they are used + to keep secret files which would otherwise + compromise your installation - e.g. the + <filename>localconfig</filename> + file contains the password to your database. + curious.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-a"> + <title>A</title> + + <glossentry id="gloss-apache"> + <glossterm>Apache</glossterm> + + <glossdef> + <para>In this context, Apache is the web server most commonly used + for serving up Bugzilla + pages. Contrary to popular belief, the apache web server has nothing + to do with the ancient and noble Native American tribe, but instead + derived its name from the fact that it was + <quote>a patchy</quote> + version of the original + <acronym>NCSA</acronym> + world-wide-web server.</para> + + <variablelist> + <title>Useful Directives when configuring Bugzilla</title> + + <varlistentry> + <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#addhandler">AddHandler</ulink></computeroutput></term> + <listitem> + <para>Tell Apache that it's OK to run CGI scripts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#allowoverride">AllowOverride</ulink></computeroutput></term> + <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#options">Options</ulink></computeroutput></term> + <listitem> + <para>These directives are used to tell Apache many things about + the directory they apply to. For Bugzilla's purposes, we need + them to allow script execution and <filename>.htaccess</filename> + overrides. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/mod_dir.html#directoryindex">DirectoryIndex</ulink></computeroutput></term> + <listitem> + <para>Used to tell Apache what files are indexes. If you can + not add <filename>index.cgi</filename> to the list of valid files, + you'll need to set <computeroutput>$index_html</computeroutput> to + 1 in <filename>localconfig</filename> so + <command>./checksetup.pl</command> will create an + <filename>index.html</filename> that redirects to + <filename>index.cgi</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink></computeroutput></term> + <listitem> + <para>Used when running Apache on windows so the shebang line + doesn't have to be changed in every Bugzilla script. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>For more information about how to configure Apache for Bugzilla, + see <xref linkend="http-apache"/>. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-b"> + <title>B</title> + + <glossentry> + <glossterm>Bug</glossterm> + + <glossdef> + <para>A + <quote>bug</quote> + + in Bugzilla refers to an issue entered into the database which has an + associated number, assignments, comments, etc. Some also refer to a + <quote>tickets</quote> + or + <quote>issues</quote>; + in the context of Bugzilla, they are synonymous.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Bug Number</glossterm> + + <glossdef> + <para>Each Bugzilla bug is assigned a number that uniquely identifies + that bug. The bug associated with a bug number can be pulled up via a + query, or easily from the very front page by typing the number in the + "Find" box.</para> + </glossdef> + </glossentry> + + <glossentry id="gloss-bugzilla"> + <glossterm>Bugzilla</glossterm> + + <glossdef> + <para>Bugzilla is the world-leading free software bug tracking system. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-c"> + <title>C</title> + + <glossentry id="gloss-cgi"> + <glossterm>Common Gateway Interface</glossterm> + <acronym>CGI</acronym> + <glossdef> + <para><acronym>CGI</acronym> is an acronym for Common Gateway Interface. This is + a standard for interfacing an external application with a web server. Bugzilla + is an example of a <acronym>CGI</acronym> application. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-component"> + <glossterm>Component</glossterm> + + <glossdef> + <para>A Component is a subsection of a Product. It should be a narrow + category, tailored to your organization. All Products must contain at + least one Component (and, as a matter of fact, creating a Product + with no Components will create an error in Bugzilla).</para> + </glossdef> + </glossentry> + + <glossentry id="gloss-cpan"> + <glossterm>Comprehensive Perl Archive Network</glossterm> + <acronym>CPAN</acronym> + + <!-- TODO: Rewrite def for CPAN --> + <glossdef> + <para> + <acronym>CPAN</acronym> + + stands for the + <quote>Comprehensive Perl Archive Network</quote>. + CPAN maintains a large number of extremely useful + <glossterm>Perl</glossterm> + modules - encapsulated chunks of code for performing a + particular task.</para> + </glossdef> + </glossentry> + + <glossentry id="gloss-contrib"> + <glossterm><filename class="directory">contrib</filename></glossterm> + + <glossdef> + <para>The <filename class="directory">contrib</filename> directory is + a location to put scripts that have been contributed to Bugzilla but + are not a part of the official distribution. These scripts are written + by third parties and may be in languages other than perl. For those + that are in perl, there may be additional modules or other requirements + than those of the official distribution. + <note> + <para>Scripts in the <filename class="directory">contrib</filename> + directory are not officially supported by the Bugzilla team and may + break in between versions. + </para> + </note> + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-d"> + <title>D</title> + + <glossentry id="gloss-daemon"> + <glossterm>daemon</glossterm> + + <glossdef> + <para>A daemon is a computer program which runs in the background. In + general, most daemons are started at boot time via System V init + scripts, or through RC scripts on BSD-based systems. + <glossterm>mysqld</glossterm>, + the MySQL server, and + <glossterm>apache</glossterm>, + a web server, are generally run as daemons.</para> + </glossdef> + </glossentry> + + <glossentry id="gloss-dos"> + <glossterm>DOS Attack</glossterm> + + <glossdef> + <para>A DOS, or Denial of Service attack, is when a user attempts to + deny access to a web server by repeatedly accessing a page or sending + malformed requests to a webserver. A D-DOS, or + Distributed Denial of Service attack, is when these requests come + from multiple sources at the same time. Unfortunately, these are much + more difficult to defend against. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id="gloss-g"> + <title>G</title> + + <glossentry id="gloss-groups"> + <glossterm>Groups</glossterm> + + <glossdef> + <para>The word + <quote>Groups</quote> + + has a very special meaning to Bugzilla. Bugzilla's main security + mechanism comes by placing users in groups, and assigning those + groups certain privileges to view bugs in particular + <glossterm>Products</glossterm> + in the + <glossterm>Bugzilla</glossterm> + database.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-j"> + <title>J</title> + + <glossentry id="gloss-javascript"> + <glossterm>JavaScript</glossterm> + <glossdef> + <para>JavaScript is cool, we should talk about it. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-m"> + <title>M</title> + + <glossentry id="gloss-mta"> + <glossterm>Message Transport Agent</glossterm> + <acronym>MTA</acronym> + + <glossdef> + <para>A Message Transport Agent is used to control the flow of email on a system. + The <ulink url="http://search.cpan.org/dist/Email-Send/lib/Email/Send.pm">Email::Send</ulink> + Perl module, which Bugzilla uses to send email, can be configured to + use many different underlying implementations for actually sending the + mail using the <option>mail_delivery_method</option> parameter. + Implementations other than <literal>sendmail</literal> require that the + <option>sendmailnow</option> param be set to <literal>on</literal>. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-mysql"> + <glossterm>MySQL</glossterm> + + <glossdef> + <para>MySQL is currently the required + <glossterm linkend="gloss-rdbms">RDBMS</glossterm> for Bugzilla. MySQL + can be downloaded from <ulink url="http://www.mysql.com"/>. While you + should familiarize yourself with all of the documentation, some high + points are: + </para> + <variablelist> + <varlistentry> + <term><ulink url="http://www.mysql.com/doc/en/Backup.html">Backup</ulink></term> + <listitem> + <para>Methods for backing up your Bugzilla database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><ulink url="http://www.mysql.com/doc/en/Option_files.html">Option Files</ulink></term> + <listitem> + <para>Information about how to configure MySQL using + <filename>my.cnf</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><ulink url="http://www.mysql.com/doc/en/Privilege_system.html">Privilege System</ulink></term> + <listitem> + <para>Much more detailed information about the suggestions in + <xref linkend="security-mysql"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-p"> + <title>P</title> + + <glossentry id="gloss-ppm"> + <glossterm>Perl Package Manager</glossterm> + <acronym>PPM</acronym> + + <glossdef> + <para><ulink url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/"/> + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm id="gloss-product">Product</glossterm> + + <glossdef> + <para>A Product is a broad category of types of bugs, normally + representing a single piece of software or entity. In general, + there are several Components to a Product. A Product may define a + group (used for security) for all bugs entered into + its Components.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Perl</glossterm> + + <glossdef> + <para>First written by Larry Wall, Perl is a remarkable program + language. It has the benefits of the flexibility of an interpreted + scripting language (such as shell script), combined with the speed + and power of a compiled language, such as C. + <glossterm>Bugzilla</glossterm> + + is maintained in Perl.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-q"> + <title>Q</title> + + <glossentry> + <glossterm>QA</glossterm> + + <glossdef> + <para> + <quote>QA</quote>, + <quote>Q/A</quote>, and + <quote>Q.A.</quote> + are short for + <quote>Quality Assurance</quote>. + In most large software development organizations, there is a team + devoted to ensuring the product meets minimum standards before + shipping. This team will also generally want to track the progress of + bugs over their life cycle, thus the need for the + <quote>QA Contact</quote> + + field in a bug.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-r"> + <title>R</title> + + <glossentry id="gloss-rdbms"> + <glossterm>Relational DataBase Management System</glossterm> + <acronym>RDBMS</acronym> + + <glossdef> + <para>A relational database management system is a database system + that stores information in tables that are related to each other. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-regexp"> + <glossterm>Regular Expression</glossterm> + <acronym>regexp</acronym> + + <glossdef> + <para>A regular expression is an expression used for pattern matching. + <ulink url="http://perldoc.com/perl5.6/pod/perlre.html#Regular-Expressions">Documentation</ulink> + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-s"> + <title>S</title> + + <glossentry id="gloss-service"> + <glossterm>Service</glossterm> + + <glossdef> + <para>In Windows NT environment, a boot-time background application + is referred to as a service. These are generally managed through the + control panel while logged in as an account with + <quote>Administrator</quote> level capabilities. For more + information, consult your Windows manual or the MSKB. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm> + <acronym>SGML</acronym> + </glossterm> + + <glossdef> + <para> + <acronym>SGML</acronym> + + stands for + <quote>Standard Generalized Markup Language</quote>. + Created in the 1980's to provide an extensible means to maintain + documentation based upon content instead of presentation, + <acronym>SGML</acronym> + + has withstood the test of time as a robust, powerful language. + <glossterm> + <acronym>XML</acronym> + </glossterm> + + is the + <quote>baby brother</quote> + + of SGML; any valid + <acronym>XML</acronym> + + document it, by definition, a valid + <acronym>SGML</acronym> + + document. The document you are reading is written and maintained in + <acronym>SGML</acronym>, + and is also valid + <acronym>XML</acronym> + + if you modify the Document Type Definition.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-t"> + <title>T</title> + + <glossentry id="gloss-target-milestone" xreflabel="Target Milestone"> + <glossterm>Target Milestone</glossterm> + + <glossdef> + <para>Target Milestones are Product goals. They are configurable on a + per-Product basis. Most software development houses have a concept of + + <quote>milestones</quote> + + where the people funding a project expect certain functionality on + certain dates. Bugzilla facilitates meeting these milestones by + giving you the ability to declare by which milestone a bug will be + fixed, or an enhancement will be implemented.</para> + </glossdef> + </glossentry> + + <glossentry id="gloss-tcl"> + <glossterm>Tool Command Language</glossterm> + <acronym>TCL</acronym> + <glossdef> + <para>TCL is an open source scripting language available for Windows, + Macintosh, and Unix based systems. Bugzilla 1.0 was written in TCL but + never released. The first release of Bugzilla was 2.0, which was when + it was ported to perl. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="gloss-z"> + <title>Z</title> + + <glossentry id="gloss-zarro"> + <glossterm>Zarro Boogs Found</glossterm> + + <glossdef> + <para>This is just a goofy way of saying that there were no bugs + found matching your query. When asked to explain this message, + Terry had the following to say: + </para> + + <blockquote> + <attribution>Terry Weissman</attribution> + <para>I've been asked to explain this ... way back when, when + Netscape released version 4.0 of its browser, we had a release + party. Naturally, there had been a big push to try and fix every + known bug before the release. Naturally, that hadn't actually + happened. (This is not unique to Netscape or to 4.0; the same thing + has happened with every software project I've ever seen.) Anyway, + at the release party, T-shirts were handed out that said something + like "Netscape 4.0: Zarro Boogs". Just like the software, the + T-shirt had no known bugs. Uh-huh. + </para> + + <para>So, when you query for a list of bugs, and it gets no results, + you can think of this as a friendly reminder. Of *course* there are + bugs matching your query, they just aren't in the bugsystem yet... + </para> + </blockquote> + + </glossdef> + </glossentry> + </glossdiv> +</glossary> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> diff --git a/docs/en/xml/index.xml b/docs/en/xml/index.xml new file mode 100644 index 000000000..7fc1a4c14 --- /dev/null +++ b/docs/en/xml/index.xml @@ -0,0 +1,21 @@ +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml new file mode 100644 index 000000000..0373ab72c --- /dev/null +++ b/docs/en/xml/installation.xml @@ -0,0 +1,2040 @@ +<!-- <!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: +--> diff --git a/docs/en/xml/integration.xml b/docs/en/xml/integration.xml new file mode 100644 index 000000000..485a03dcd --- /dev/null +++ b/docs/en/xml/integration.xml @@ -0,0 +1,120 @@ +<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> +<!-- Keep these tools listings in alphabetical order please. -MPB --> +<section id="integration"> + <title>Integrating Bugzilla with Third-Party Tools</title> + + <section id="bonsai" + xreflabel="Bonsai, the Mozilla automated CVS management system"> + <title>Bonsai</title> + + <para>Bonsai is a web-based tool for managing + <xref linkend="cvs" /> + + . Using Bonsai, administrators can control open/closed status of trees, + query a fast relational database back-end for change, branch, and comment + information, and view changes made since the last time the tree was + closed. Bonsai + also integrates with + <xref linkend="tinderbox" />. + </para> + </section> + + <section id="cvs" xreflabel="CVS, the Concurrent Versioning System"> + <title>CVS</title> + + <para>CVS integration is best accomplished, at this point, using the + Bugzilla Email Gateway.</para> + + <para>Follow the instructions in this Guide for enabling Bugzilla e-mail + integration. Ensure that your check-in script sends an email to your + Bugzilla e-mail gateway with the subject of + <quote>[Bug XXXX]</quote>, + and you can have CVS check-in comments append to your Bugzilla bug. If + you want to have the bug be closed automatically, you'll have to modify + the <filename>contrib/bugzilla_email_append.pl</filename> script. + </para> + + <para>There is also a CVSZilla project, based upon somewhat dated + Bugzilla code, to integrate CVS and Bugzilla through CVS' ability to + email. Check it out at: <ulink url="http://www.cvszilla.org/"/>. + </para> + + <para>Another system capable of CVS integration with Bugzilla is + Scmbug. This system provides generic integration of Source code + Configuration Management with Bugtracking. Check it out at: <ulink + url="http://freshmeat.net/projects/scmbug/"/>. + </para> + + </section> + + <section id="scm" + xreflabel="Perforce SCM (Fast Software Configuration Management System, a powerful commercial alternative to CVS"> + + <title>Perforce SCM</title> + + <para>You can find the project page for Bugzilla and Teamtrack Perforce + integration (p4dti) at: + <ulink url="http://www.ravenbrook.com/project/p4dti/"/> + + . + <quote>p4dti</quote> + + is now an officially supported product from Perforce, and you can find + the "Perforce Public Depot" p4dti page at + <ulink url="http://public.perforce.com/public/perforce/p4dti/index.html"/> + + .</para> + + <para>Integration of Perforce with Bugzilla, once patches are applied, is + seamless. Perforce replication information will appear below the comments + of each bug. Be certain you have a matching set of patches for the + Bugzilla version you are installing. p4dti is designed to support + multiple defect trackers, and maintains its own documentation for it. + Please consult the pages linked above for further information.</para> + </section> + + <section id="svn" + xreflabel="Subversion, a compelling replacement for CVS"> + <title>Subversion</title> + <para>Subversion is a free/open-source version control system, + designed to overcome various limitations of CVS. Integration of + Subversion with Bugzilla is possible using Scmbug, a system + providing generic integration of Source Code Configuration + Management with Bugtracking. Scmbug is available at <ulink + url="http://freshmeat.net/projects/scmbug/"/>.</para> + </section> + + <section id="tinderbox" + xreflabel="Tinderbox, the Mozilla automated build management system"> + <title>Tinderbox/Tinderbox2</title> + + <para>Tinderbox is a continuous-build system which can integrate with + Bugzilla - see + <ulink url="http://www.mozilla.org/projects/tinderbox"/> for details + of Tinderbox, and + <ulink url="http://tinderbox.mozilla.org/showbuilds.cgi"/> to see it + in action.</para> + </section> +</section> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/introduction.xml b/docs/en/xml/introduction.xml new file mode 100644 index 000000000..3968702c6 --- /dev/null +++ b/docs/en/xml/introduction.xml @@ -0,0 +1,121 @@ +<chapter id="introduction"> + <title>Introduction</title> + + <section id="what-is-bugzilla"> + <title>What is Bugzilla?</title> + + <para> + Bugzilla is a bug- or issue-tracking system. Bug-tracking + systems allow individual or groups of developers effectively to keep track + of outstanding problems with their products. + </para> + + <para><emphasis>Do we need more here?</emphasis></para> + + </section> + + <section id="why-tracking"> + <title>Why use a bug-tracking system?</title> + + <para>Those who do not use a bug-tracking system tend to rely on + shared lists, email, spreadsheets and/or Post-It notes to monitor the + status of defects. This procedure + is usually error-prone and tends to cause those bugs judged least + significant by developers to be dropped or ignored.</para> + + <para>Integrated defect-tracking systems make sure that nothing gets + swept under the carpet; they provide a method of creating, storing, + arranging and processing defect reports and enhancement requests.</para> + + </section> + + <section id="why-bugzilla"> + <title>Why use Bugzilla?</title> + + <para>Bugzilla is the leading open-source/free software bug tracking + system. It boasts many advanced features, including: + <itemizedlist> + <listitem> + <para>Powerful searching</para> + </listitem> + + <listitem> + <para>User-configurable email notifications of bug changes</para> + </listitem> + + <listitem> + <para>Full change history</para> + </listitem> + + <listitem> + <para>Inter-bug dependency tracking and graphing</para> + </listitem> + + <listitem> + <para>Excellent attachment management</para> + </listitem> + + <listitem> + <para>Integrated, product-based, granular security schema</para> + </listitem> + + <listitem> + <para>Fully security-audited, and runs under Perl's taint mode</para> + </listitem> + + <listitem> + <para>A robust, stable RDBMS back-end</para> + </listitem> + + <listitem> + <para>Completely customizable and/or localizable web user + interface</para> + </listitem> + + <listitem> + <para>Additional XML, email and console interfaces</para> + </listitem> + + <listitem> + <para>Extensive configurability</para> + </listitem> + + <listitem> + <para>Smooth upgrade pathway between versions</para> + </listitem> + </itemizedlist> + </para> + + <para>Bugzilla is very adaptable to various situations. Known uses + currently include IT support queues, Systems Administration deployment + management, chip design and development problem tracking (both + pre-and-post fabrication), and software and hardware bug tracking for + luminaries such as Redhat, NASA, Linux-Mandrake, and VA Systems. + Combined with systems such as + <ulink url="http://www.cvshome.org">CVS</ulink>, + <ulink url="http://www.mozilla.org/bonsai.html">Bonsai</ulink>, or + <ulink url="http://www.perforce.com">Perforce SCM</ulink>, Bugzilla + provides a powerful, easy-to-use configuration management solution.</para> + </section> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml new file mode 100644 index 000000000..3d4f6e556 --- /dev/null +++ b/docs/en/xml/modules.xml @@ -0,0 +1,193 @@ +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<appendix id="install-perlmodules-manual"> + <title>Manual Installation of Perl Modules</title> + + <section id="modules-manual-instructions"> + <title>Instructions</title> + <para> + If you need to install Perl modules manually, here's how it's done. + Download the module using the link given in the next section, and then + apply this magic incantation, as root: + </para> + + <para> + <screen><prompt>bash#</prompt> tar -xzvf <module>.tar.gz +<prompt>bash#</prompt> cd <module> +<prompt>bash#</prompt> perl Makefile.PL +<prompt>bash#</prompt> make +<prompt>bash#</prompt> make test +<prompt>bash#</prompt> make install</screen> + </para> + <note> + <para> + In order to compile source code under Windows you will need to obtain + a 'make' utility. The <command>nmake</command> utility provided with + Microsoft Visual C++ may be used. As an alternative, there is a + utility called <command>dmake</command> available from CPAN which is + written entirely in Perl. + </para> + <para> + As described in <xref linkend="modules-manual-download" />, however, most + packages already exist and are available from ActiveState or theory58S. + We highly recommend that you install them using the ppm GUI available with + ActiveState and to add the theory58S repository to your list of repositories. + </para> + </note> + </section> + + <section id="modules-manual-download"> + <title>Download Locations</title> + + <note> + <para> + Running Bugzilla on Windows requires the use of ActiveState + Perl 5.8.1 or higher. Many modules already exist in the core + distribution of ActiveState Perl. Additional modules can be downloaded + from <ulink url="http://theoryx5.uwinnipeg.ca/ppms/" /> if you use + Perl 5.8.x or from <ulink url="http://cpan.uwinnipeg.ca/PPMPackages/10xx/" /> + if you use Perl 5.10.x. + </para> + </note> + + <para> + CGI: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/> + Documentation: <ulink url="http://perldoc.perl.org/CGI.html"/> + </literallayout> + </para> + + <para> + Data-Dumper: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/> + Documentation: <ulink url="http://search.cpan.org/dist/Data-Dumper/Dumper.pm"/> + </literallayout> + </para> + + <para> + Date::Format (part of TimeDate): + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/> + Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/> + </literallayout> + </para> + + <para> + DBI: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/> + Documentation: <ulink url="http://dbi.perl.org/docs/"/> + </literallayout> + </para> + + <para> + DBD::mysql: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/> + Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm"/> + </literallayout> + </para> + + <para> + DBD::Pg: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-Pg/"/> + Documentation: <ulink url="http://search.cpan.org/dist/DBD-Pg/Pg.pm"/> + </literallayout> + </para> + + <para> + File::Spec: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/> + Documentation: <ulink url="http://perldoc.perl.org/File/Spec.html"/> + </literallayout> + </para> + + <para> + Template-Toolkit: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/> + Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/> + </literallayout> + </para> + + <para> + GD: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/> + Documentation: <ulink url="http://search.cpan.org/dist/GD/GD.pm"/> + </literallayout> + </para> + + <para> + Template::Plugin::GD: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-GD/" /> + Documentation: <ulink url="http://www.template-toolkit.org/docs/aqua/Modules/index.html" /> + </literallayout> + </para> + + <para> + MIME::Parser (part of MIME-tools): + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/> + Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/> + </literallayout> + </para> + + </section> + + <section id="modules-manual-optional"> + <title>Optional Modules</title> + + <para> + Chart::Base: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/> + Documentation: <ulink url="http://search.cpan.org/dist/Chart/Chart.pod"/> + </literallayout> + </para> + + <para> + GD::Graph: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/> + Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/> + </literallayout> + </para> + + <para> + GD::Text::Align (part of GD::Text::Util): + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/> + Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/> + </literallayout> + </para> + + <para> + XML::Twig: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Twig/"/> + Documentation: <ulink url="http://standards.ieee.org/resources/spasystem/twig/twig_stable.html"/> + </literallayout> + </para> + + <para> + PatchReader: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/> + Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/> + </literallayout> + </para> + + <para> + Image::Magick: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/PerlMagick/"/> + Documentation: <ulink url="http://www.imagemagick.org/script/resources.php"/> + </literallayout> + </para> + </section> +</appendix> diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml new file mode 100644 index 000000000..12efb0ca4 --- /dev/null +++ b/docs/en/xml/patches.xml @@ -0,0 +1,131 @@ +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla"> + <title>Contrib</title> + + <para> + There are a number of unofficial Bugzilla add-ons in the + <filename class="directory">$BUGZILLA_ROOT/contrib/</filename> + directory. This section documents them. + </para> + + <section id="cmdline"> + <title>Command-line Search Interface</title> + + <para> + There are a suite of Unix utilities for searching Bugzilla from the + command line. They live in the + <filename class="directory">contrib/cmdline</filename> directory. + There are three files - <filename>query.conf</filename>, + <filename>buglist</filename> and <filename>bugs</filename>. + </para> + + <warning> + <para> + These files pre-date the templatization work done as part of the + 2.16 release, and have not been updated. + </para> + </warning> + + <para> + <filename>query.conf</filename> contains the mapping from + options to field names and comparison types. Quoted option names + are <quote>grepped</quote> for, so it should be easy to edit this + file. Comments (#) have no effect; you must make sure these lines + do not contain any quoted <quote>option</quote>. + </para> + + <para> + <filename>buglist</filename> is a shell script that submits a + Bugzilla query and writes the resulting HTML page to stdout. + It supports both short options, (such as <quote>-Afoo</quote> + or <quote>-Rbar</quote>) and long options (such + as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>). + If the first character of an option is not <quote>-</quote>, it is + treated as if it were prefixed with <quote>--default=</quote>. + </para> + + <para> + The column list is taken from the COLUMNLIST environment variable. + This is equivalent to the <quote>Change Columns</quote> option + that is available when you list bugs in buglist.cgi. If you have + already used Bugzilla, grep for COLUMNLIST in your cookies file + to see your current COLUMNLIST setting. + </para> + + <para> + <filename>bugs</filename> is a simple shell script which calls + <filename>buglist</filename> and extracts the + bug numbers from the output. Adding the prefix + <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote> + turns the bug list into a working link if any bugs are found. + Counting bugs is easy. Pipe the results through + <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command> + </para> + + <para> + Akkana Peck says she has good results piping + <filename>buglist</filename> output through + <command>w3m -T text/html -dump</command> + </para> + + </section> + + <section id="cmdline-bugmail"> + <title>Command-line 'Send Unsent Bug-mail' tool</title> + + <para> + Within the <filename class="directory">contrib</filename> directory + exists a utility with the descriptive (if compact) name + of <filename>sendunsentbugmail.pl</filename>. The purpose of this + script is, simply, to send out any bug-related mail that should + have been sent by now, but for one reason or another has not. + </para> + + <para> + To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses + the same mechanism as the <filename>sanitycheck.cgi</filename> script; + it scans through the entire database looking for bugs with changes that + were made more than 30 minutes ago, but where there is no record of + anyone related to that bug having been sent mail. Having compiled a list, + it then uses the standard rules to determine who gets mail, and sends it + out. + </para> + + <para> + As the script runs, it indicates the bug for which it is currently + sending mail; when it has finished, it gives a numerical count of how + many mails were sent and how many people were excluded. (Individual + user names are not recorded or displayed.) If the script produces + no output, that means no unsent mail was detected. + </para> + + <para> + <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script + up into the main directory, ensure it has execute permission, and run it + from the command line (or from a cron job) with no parameters. + </para> + </section> + +</appendix> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/requiredsoftware.xml b/docs/en/xml/requiredsoftware.xml new file mode 100644 index 000000000..4a751c0c7 --- /dev/null +++ b/docs/en/xml/requiredsoftware.xml @@ -0,0 +1,77 @@ +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<appendix id="downloadlinks"> + <title>Software Download Links</title> + + <para>All of these sites are current as of April, 2001. Hopefully they'll + stay current for a while.</para> + + <para>Apache Web Server: + <ulink url="http://www.apache.org/"/> + + Optional web server for Bugzilla, but recommended because of broad user + base and support.</para> + + <para>Bugzilla: + <ulink url="http://www.bugzilla.org/"/> + </para> + + <para>MySQL: + <ulink url="http://www.mysql.com/"/> + </para> + + <para>Perl: + <ulink url="http://www.perl.org/"/> + </para> + + <para>CPAN: + <ulink url="http://www.cpan.org/"/> + </para> + + <para>DBI Perl module: + <ulink url="http://www.cpan.org/modules/by-module/DBI/"/> + </para> + + <para>MySQL related Perl modules: + <ulink url="http://www.cpan.org/modules/by-module/Mysql/"/> + </para> + + <para>TimeDate Perl module collection: + <ulink url="http://www.cpan.org/modules/by-module/Date/"/> + </para> + + <para>GD Perl module: + <ulink url="http://www.cpan.org/modules/by-module/GD/"/> + + Alternately, you should be able to find the latest version of GD at + <ulink url="http://www.boutell.com/gd/"/> + </para> + + <para>Chart::Base module: + <ulink url="http://www.cpan.org/modules/by-module/Chart/"/> + </para> + + <para>(But remember, Bundle::Bugzilla will install all the modules for you.) + </para> +</appendix> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-always-quote-attributes:t +sgml-auto-insert-required-elements:t +sgml-balanced-tag-edit:t +sgml-exposed-tags:nil +sgml-general-insert-case:lower +sgml-indent-data:t +sgml-indent-step:2 +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +sgml-minimize-attributes:nil +sgml-namecase-general:t +sgml-omittag:t +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-shorttag:t +sgml-tag-region-if-active:t +End: +--> + diff --git a/docs/en/xml/security.xml b/docs/en/xml/security.xml new file mode 100644 index 000000000..c0ac03d30 --- /dev/null +++ b/docs/en/xml/security.xml @@ -0,0 +1,367 @@ +<!-- <!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: --> + diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml new file mode 100644 index 000000000..13a756a3b --- /dev/null +++ b/docs/en/xml/troubleshooting.xml @@ -0,0 +1,307 @@ +<!-- <!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: --> + + diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml new file mode 100644 index 000000000..101a9d131 --- /dev/null +++ b/docs/en/xml/using.xml @@ -0,0 +1,1957 @@ +<!-- <!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: +--> + |
