diff options
| author | jake%bugzilla.org <> | 2003-04-23 09:04:01 +0000 |
|---|---|---|
| committer | jake%bugzilla.org <> | 2003-04-23 09:04:01 +0000 |
| commit | 78e29c8900fa96d67163a34a0c02c7cecb31b55f (patch) | |
| tree | f4e97e5b99809faa9f3bc1c48f7a6adaefb6bbb7 /docs/sgml | |
| parent | 58ab63119c6de5dbdfa74d268196da734e5c5fc2 (diff) | |
| download | bugs-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar bugs-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar.gz bugs-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar.bz2 bugs-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar.xz bugs-78e29c8900fa96d67163a34a0c02c7cecb31b55f.zip | |
The source files for the Bugzilla Guide have long been using the XML version of DocBook but still residing in the sgml/ directory with an extension of .sgml.
In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension.
Diffstat (limited to 'docs/sgml')
| -rw-r--r-- | docs/sgml/Bugzilla-Guide.sgml | 205 | ||||
| -rw-r--r-- | docs/sgml/about.sgml | 227 | ||||
| -rw-r--r-- | docs/sgml/administration.sgml | 1640 | ||||
| -rw-r--r-- | docs/sgml/conventions.sgml | 179 | ||||
| -rw-r--r-- | docs/sgml/database.sgml | 394 | ||||
| -rw-r--r-- | docs/sgml/dbschema.mysql | 1 | ||||
| -rw-r--r-- | docs/sgml/faq.sgml | 1321 | ||||
| -rw-r--r-- | docs/sgml/filetemp.patch | 18 | ||||
| -rw-r--r-- | docs/sgml/gd-makefile.patch | 22 | ||||
| -rw-r--r-- | docs/sgml/gfdl.sgml | 448 | ||||
| -rw-r--r-- | docs/sgml/glossary.sgml | 482 | ||||
| -rw-r--r-- | docs/sgml/index.sgml | 21 | ||||
| -rw-r--r-- | docs/sgml/installation.sgml | 1615 | ||||
| -rw-r--r-- | docs/sgml/integration.sgml | 101 | ||||
| -rw-r--r-- | docs/sgml/introduction.sgml | 149 | ||||
| -rw-r--r-- | docs/sgml/patches.sgml | 113 | ||||
| -rw-r--r-- | docs/sgml/requiredsoftware.sgml | 88 | ||||
| -rw-r--r-- | docs/sgml/using.sgml | 580 | ||||
| -rw-r--r-- | docs/sgml/variants.sgml | 123 |
19 files changed, 0 insertions, 7727 deletions
diff --git a/docs/sgml/Bugzilla-Guide.sgml b/docs/sgml/Bugzilla-Guide.sgml deleted file mode 100644 index a9fcf097a..000000000 --- a/docs/sgml/Bugzilla-Guide.sgml +++ /dev/null @@ -1,205 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [ - -<!-- Include macros --> -<!ENTITY about SYSTEM "about.sgml"> -<!ENTITY conventions SYSTEM "conventions.sgml"> -<!ENTITY doc-index SYSTEM "index.sgml"> -<!ENTITY faq SYSTEM "faq.sgml"> -<!ENTITY gfdl SYSTEM "gfdl.sgml"> -<!ENTITY glossary SYSTEM "glossary.sgml"> -<!ENTITY installation SYSTEM "installation.sgml"> -<!ENTITY administration SYSTEM "administration.sgml"> -<!ENTITY using SYSTEM "using.sgml"> -<!ENTITY integration SYSTEM "integration.sgml"> -<!ENTITY future SYSTEM "future.sgml"> -<!ENTITY index SYSTEM "index.sgml"> -<!ENTITY database SYSTEM "database.sgml"> -<!ENTITY patches SYSTEM "patches.sgml"> -<!ENTITY variants SYSTEM "variants.sgml"> -<!ENTITY introduction SYSTEM "introduction.sgml"> -<!ENTITY revhistory SYSTEM "revhistory.sgml"> - -<!-- Things to change for a stable release: - * bz-ver to current stable - * bz-nexver to next stable - * bz-date to the release date - * bz-devel to "IGNORE" - - COMPILE DOCS AND CHECKIN - - Also, tag and tarball before completing - * bz-ver to devel version - * bz-devel to "INCLUDE" - - For a devel release, simple bump bz-ver and bz-date ---> - -<!ENTITY bz-ver "2.17.4"> -<!ENTITY bz-nextver "2.18"> -<!ENTITY bz-date "2003-02-16"> -<!ENTITY % bz-devel "INCLUDE"> - -<!ENTITY bz "http://www.bugzilla.org/"> -<!ENTITY bzg-auth "The Bugzilla Team"> -<!ENTITY bzg-bugs "<ulink url='http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation'>Bugzilla Documentation</ulink>"> -<!ENTITY mysql "http://www.mysql.com/"> -<!ENTITY newest-perl-ver "5.8"> - -<!-- For minimum versions --> -<!ENTITY min-mysql-ver "3.23.41"> -<!ENTITY min-perl-ver "5.6"> -<!ENTITY min-template-ver "2.08"> -<!ENTITY min-file-temp-ver "1.804"> -<!ENTITY min-appconfig-ver "1.52"> -<!ENTITY min-text-wrap-ver "2001.0131"> -<!ENTITY min-file-spec-ver "0.82"> -<!ENTITY min-data-dumper-ver "any"> -<!ENTITY min-dbd-mysql-ver "2.1010"> -<!ENTITY min-dbi-ver "1.32"> -<!ENTITY min-date-format-ver "2.21"> -<!ENTITY min-cgi-ver "2.88"> -<!-- Optional modules --> -<!ENTITY min-gd-ver "1.20"> -<!ENTITY min-gd-graph-ver "any"> -<!ENTITY min-gd-text-align-ver "any"> -<!ENTITY min-chart-base-ver "0.99c"> -<!ENTITY min-xml-parser-ver "any"> -<!ENTITY min-mime-parser-ver "any"> - -]> - - -<!-- 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.sgml. -* 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 (needsfix) -* 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 ]]>Release</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - <othername>P.</othername> - <surname>Barnson</surname> - </author> - <author> - <firstname>Jacob</firstname> - <surname>Steenhagen</surname> - </author> - <corpauthor>The Bugzilla Team</corpauthor> - </authorgroup> - - <pubdate>&bz-date;</pubdate> - - <abstract> - <para> - This is the documentation for Bugzilla, the mozilla.org - bug-tracking system. - Bugzilla is an enterprise-class piece of software - that powers issue-tracking for hundreds of - organizations around the world, tracking millions of bugs. - </para> - - <para> - This documentation is maintained in DocBook 4.1.2 XML format. - Changes are best submitted as plain text or SGML diffs, attached - to a bug filed in the &bzg-bugs; compontent. - </para> - <![%bz-devel;[ - <para>This is a development version of this guide. Information in it - is subject to change before the &bz-nextver; release of this guide - (which will correspond with the &bz-nextver; release of Bugzilla). - </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; - -<!-- Introduction --> -&introduction; - -<!-- Using Bugzilla --> -&using; - -<!-- Installing Bugzilla --> -&installation; - -<!-- Administering Bugzilla --> -&administration; - -<!-- Appendix: The Frequently Asked Questions --> -&faq; - -<!-- Appendix: The Database Schema --> -&database; - -<!-- Appendix: Custom Patches --> -&patches; - -<!-- Appendix: Major Bugzilla Variants --> -&variants; - -<!-- 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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/sgml/about.sgml b/docs/sgml/about.sgml deleted file mode 100644 index ccfcdd23e..000000000 --- a/docs/sgml/about.sgml +++ /dev/null @@ -1,227 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ -<!ENTITY conventions SYSTEM "conventions.sgml"> ] > --> - -<chapter id="about"> -<title>About This Guide</title> - - <section id="copyright"> - <title>Copyright Information</title> - <blockquote> - <attribution>Copyright (c) 2000-2003 Matthew P. Barnson and &bzg-auth;</attribution> - <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 &bzg-auth;. - </para> - </section> - - <section id="disclaimer"> - <title>Disclaimer</title> - <para> - No liability for the contents of this document can be accepted. - Use the concepts, examples, and other content 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> - All copyrights are held by their respective owners, unless - specifically noted otherwise. Use of a term in this document - should not be regarded as affecting the validity of any - trademark or service mark. - </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 in every situation - where it is appropriate. It is an extremely versatile, stable, - and robust operating system that offers an ideal operating - environment for Bugzilla. - </para> - <para> - You are strongly recommended to make a backup of your system - before installing Bugzilla and at regular intervals thereafter. - If you implement any suggestion in this Guide, implement this one! - </para> - <para> - Although the Bugzilla development team has taken great care to - ensure that all easily-exploitable bugs or options are - documented or fixed in the code, security holes surely exist. - Great care should be taken both in the installation and usage of - this software. Carefully consider the implications of installing - other network services with Bugzilla. The Bugzilla development - team members, Netscape Communications, America Online Inc., and - any affiliated developers or sponsors assume no liability for - your use of this product. You have the source code to this - product, 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. Information is subject to change between now and - when &bz-nextver; is released. - ]]> - If you are - reading this from any source other than those below, please - check one of these mirrors to make sure you are reading an - up-to-date version of the Guide. - </para> - <para> - The newest version of this guide can always be found at <ulink - url="http://www.bugzilla.org">bugzilla.org</ulink>; including - documentation for past releases and the current development version. - </para> - <para> - The documentation for the most recent stable release of Bugzilla can also - be found at - <ulink url="http://www.tldp.org">The Linux Documentation Project</ulink>. - </para> - <para> - The latest version of this document can always be checked out via CVS. - Please follow the instructions available at - <ulink url="http://www.mozilla.org/cvs.html">the Mozilla CVS page</ulink>, - and check out the <filename>mozilla/webtools/bugzilla/docs/</filename> - subtree. - </para> - <para> - The Bugzilla Guide is currently only available in English. - If you would like to volunteer to translate it, please contact - <ulink url="mailto:justdave@syndicomm.com">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 Herculaean 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, and being largely responsible for - <xref linkend="variant-redhat"/>. - </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> - - </variablelist> - - <para> - Last but not least, all the members of the - <ulink url="news://news.mozilla.org/netscape/public/mozilla/webtools"/> - newsgroup. Without your discussions, insight, suggestions, and patches, - this could never have happened. - </para> - <para> - Thanks also go to the following people for significant contributions - to this documentation (in alphabetical order): - <simplelist type="inline"> - <member>Andrew Pearson</member> - <member>Ben FrantzDale</member> - <member>Eric Hanson</member> - <member>Gervase Markham</member> - <member>Joe Robins</member> - <member>Kevin Brannen</member> - <member>Ron Teitelbaum</member> - <member>Spencer Smith</member> - <member>Zach Liption</member> - </simplelist> - . - </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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: --> diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml deleted file mode 100644 index f04e2b5ce..000000000 --- a/docs/sgml/administration.sgml +++ /dev/null @@ -1,1640 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<chapter id="administration"> - <title>Administering Bugzilla</title> - - <section id="parameters"> - <title>Bugzilla Configuration</title> - - <para>Bugzilla is configured by changing various parameters, accessed - from the "Edit parameters" link in the page footer. Here are - some of the key parameters on that page. You should run down this - list and set them appropriately after installing Bugzilla.</para> - - <indexterm> - <primary>checklist</primary> - </indexterm> - - <procedure> - <step> - <para> - <command>maintainer</command>: - The maintainer parameter is the email address of the person - responsible for maintaining this - Bugzilla installation. The address need not be that of a valid Bugzilla - account.</para> - </step> - - <step> - <para> - <command>urlbase</command>: - This parameter defines the fully qualified domain name and web - server path to your Bugzilla installation.</para> - - <para>For example, if your Bugzilla query page is - <filename>http://www.foo.com/bugzilla/query.cgi</filename>, - set your <quote>urlbase</quote> - to <filename>http://www.foo.com/bugzilla/</filename>.</para> - </step> - - <step> - <para> - <command>makeproductgroups</command>: - This dictates whether or not to automatically create groups - when new products are created. - </para> - </step> - - <step> - <para> - <command>useentrygroupdefault</command>: - 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> - </step> - - <step> - <para> - <command>shadowdb</command>: - You run into an interesting problem when Bugzilla reaches a - high level of continuous activity. MySQL supports only table-level - write locking. What this means is that if someone needs to make a - change to a bug, they will lock the entire table until the operation - is complete. Locking for write also blocks reads until the write is - complete. Note that more recent versions of mysql support row level - locking using different table types. These types are slower than the - standard type, and Bugzilla does not yet take advantage of features - such as transactions which would justify this speed decrease. The - Bugzilla team are, however, happy to hear about any experiences with - row level locking and Bugzilla</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. - Although your database size will double, a shadow database can cause - an enormous performance improvement when implemented on extremely - high-traffic Bugzilla databases.</para> - - <para> - As a guide, mozilla.org began needing - <quote>shadowdb</quote> - when they reached around 40,000 Bugzilla users with several hundred - Bugzilla bug changes and comments per day.</para> - - <para>The value of the parameter defines the name of the - shadow bug database. You will need to set the host and port settings - from the params page, and set up replication in your database server - so that updates reach this readonly mirror. Consult your database - documentation for more detail.</para> - </step> - - <step> - <para> - <command>shutdownhtml</command>: - - If you need to shut down Bugzilla to perform administration, enter - some descriptive HTML here and anyone who tries to use Bugzilla will - receive a page to that effect. Obviously, editparams.cgi will - still be accessible so you can remove the HTML and re-enable Bugzilla. - :-) - </para> - </step> - - <step> - <para> - <command>passwordmail</command>: - - Every time a user creates an account, the text of - this parameter (with substitutions) is sent to the new user along with - their password message.</para> - - <para>Add any text you wish to the "passwordmail" parameter box. For - instance, many people choose to use this box to give a quick training - blurb about how to use Bugzilla at your site.</para> - </step> - - - <step> - <para> - <command>movebugs</command>: - - This option is an undocumented feature to allow moving bugs - between separate Bugzilla installations. You will need to understand - the source code in order to use this feature. Please consult - <filename>movebugs.pl</filename> in your Bugzilla source tree for - further documentation, such as it is. - </para> - </step> - - <step> - <para> - <command>useqacontact</command>: - - This allows you to define an email address for each component, in - addition - to that of the default owner, who will be sent carbon copies of - incoming bugs.</para> - </step> - <step> - <para> - <command>usestatuswhiteboard</command>: - 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> - </step> - - <step> - <para> - <command>whinedays</command>: - 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> - </step> - - <step> - <para> - <command>commenton*</command>: - 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. - <note> - <para>It is generally far better to require a developer comment - when resolving bugs than not. Few things are more annoying to bug - database users than having a developer mark a bug "fixed" without - any comment as to what the fix was (or even that it was truly - fixed!)</para> - </note> - </para> - </step> - - <step> - <para> - <command>supportwatchers</command>: - - Turning on this option allows users to ask to receive copies of - all a particular other user's bug email. This is, of - course, subject to the groupset restrictions on the bug; if the - <quote>watcher</quote> - would not normally be allowed to view a bug, the watcher cannot get - around the system by setting herself up to watch the bugs of someone - with bugs outside her privileges. They would still only receive email - updates for those bugs she could normally view.</para> - </step> - </procedure> - </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, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. - </para> - </tip> - </section> - - <section id="manageusers"> - <title>Managing Other Users</title> - - <section id="createnewusers"> - <title>Creating new users</title> - - <para>Your users can create their own user accounts by clicking the - "New Account" link at the bottom of each page (assuming they - aren't logged in as someone else already.) However, should you - desire to create user accounts ahead of time, here is how you do - it.</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 id="modifyusers"> - <title>Modifying Users</title> - - <para>To see a specific user, search for their login name - in the box provided on the "Edit Users" page. To see all users, - leave the box blank.</para> - - <para>You can search in different ways the listbox to the right - of the text entry box. You can match by - case-insensitive substring (the default), - regular expression, or a - <emphasis>reverse</emphasis> - regular expression match, which finds every user name which does NOT - match the regular expression. (Please see - the <command>man regexp</command> - manual page for details on regular expression syntax.) - </para> - - <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 emailsuffix Param, this may just be the user's - login name. Note that users can now change their login names - themselves (to any valid email address.) - </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>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. - <warning> - <para>Don't disable the administrator account!</para> - </warning> - - <note> - <para>The user can still submit bugs via - the e-mail gateway, if you set it up, even if the disabled text - field is filled in. The e-mail gateway should - <emphasis>not</emphasis> - be enabled for secure installations of Bugzilla.</para> - </note> - </para> - </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. The user must still have the - "editbugs" privilege to edit bugs in these products.</para> - </listitem> - </itemizedlist> - </section> - </section> - </section> - - <section id="programadmin"> - <title>Product, Component, Milestone, and Version Administration</title> - - <section id="products"> - <title>Products</title> - - <para> - <glossterm linkend="gloss-product" baseform="product"> - Products</glossterm> - - are the broadest category in Bugzilla, and tend to represent real-world - shipping products. E.g. if your company makes computer games, - you should have one product per game, perhaps a "Common" product for - units of technology used in multiple games, and maybe a few special - products (Website, Administration...)</para> - - <para>Many of Bugzilla's settings are configurable on a per-product - basis. The number of "votes" available to users is set per-product, - as is the number of votes - required to move a bug automatically from the UNCONFIRMED status to the - NEW status.</para> - - <para>To create a new product:</para> - - <orderedlist> - <listitem> - <para>Select "products" from the footer</para> - - </listitem> - - <listitem> - <para>Select the "Add" 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> - </orderedlist> - - <para>Don't worry about the "Closed for bug entry", "Maximum Votes - per person", "Maximum votes a person can put on a single bug", - "Number of votes a bug in this Product needs to automatically get out - of the UNCOMFIRMED state", and "Version" options yet. We'll cover - those in a few moments. - </para> - </section> - - <section id="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 owner and (if you turned it on in the parameters), - a QA Contact. The owner should be the primary person who fixes bugs in - that component. The QA Contact should be the person who will ensure - these bugs are completely fixed. The Owner, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Owner and Default QA Contact fields only - dictate the - <emphasis>default assignments</emphasis>; - 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 "Edit components" link from the "Edit product" - page</para> - </listitem> - - <listitem> - <para>Select the "Add" link in the bottom right.</para> - </listitem> - - <listitem> - <para>Fill out the "Component" field, a short "Description", - the "Initial Owner" and "Initial QA Contact" (if enabled.) - The Component and Description fields may contain HTML; - the "Initial Owner" field must be a login name - already existing in the database. - </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 most recent version with - 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 (-255 to 255) that defines where in the list this particular - milestone appears. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add".</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> - - <tip> - <para>If you want your milestone document to be restricted so - that it can only be viewed by people in a particular Bugzilla - group, the best way is to attach the document to a bug in that - group, and make the URL the URL of that attachment.</para> - </tip> - </listitem> - </orderedlist> - </section> - </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="groups"> - <title>Groups and Group Security</title> - - <para>Groups allow the administrator - to isolate bugs or products that should only be seen by certain people. - The association between products and groups is controlled from - the product edit page under <quote>Edit Group Controls.</quote> - </para> - - <para> - If the makeproductgroups param is on, a new group will be automatically - created for every new product. - </para> - - <para> - On the product edit page, there is a page to edit the - <quote>Group Controls</quote> - for a product and determine which groups are applicable, default, - and mandatory for each product as well as controlling entry - for each product and being able to set bugs in a product to be - totally read-only unless some group restrictions are met. - </para> - - <para> - For each group, it is possible to specify if membership in that - group is... - </para> - <orderedlist> - <listitem> - <para> - required for bug entry, - </para> - </listitem> - <listitem> - <para> - Not applicable to this product(NA), - a possible restriction for a member of the - group to place on a bug in this product(Shown), - a default restriction for a member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product(Mandatory). - </para> - </listitem> - <listitem> - <para> - Not applicable by non-members to this product(NA), - a possible restriction for a non-member of the - group to place on a bug in this product(Shown), - a default restriction for a non-member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product when entered by a non-member(Mandatory). - </para> - </listitem> - <listitem> - <para> - required in order to make <emphasis>any</emphasis> change - to bugs in this product <emphasis>including comments.</emphasis> - </para> - </listitem> - </orderedlist> - - <para>To create Groups:</para> - - <orderedlist> - <listitem> - <para>Select the <quote>groups</quote> - link in the footer.</para> - </listitem> - - <listitem> - <para>Take a moment to understand the instructions on the <quote>Edit - Groups</quote> screen, then select the <quote>Add Group</quote> link.</para> - </listitem> - - <listitem> - <para>Fill out the <quote>Group</quote>, <quote>Description</quote>, - and <quote>User RegExp</quote> fields. - <quote>User RegExp</quote> allows you to automatically - place all users who fulfill the Regular Expression into the new group. - When you have finished, click <quote>Add</quote>.</para> - <warning> - <para>The User Regexp is a perl regexp and, if not anchored, will match - any part of an address. So, if you do not want to grant access - into 'mycompany.com' to 'badperson@mycompany.com.hacker.net', use - '@mycompany\.com$' as the regexp.</para> - </warning> - </listitem> - <listitem> - <para>After you add your new group, edit the new group. On the - edit page, you can specify other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group.</para> - </listitem> - </orderedlist> - - <para> - Note that group permissions are such that you need to be a member - of <emphasis>all</emphasis> the groups a bug is in, for whatever - reason, to see that bug. Similarly, you must be a member - of <emphasis>all</emphasis> of the entry groups for a product - to add bugs to a product and you must be a member - of <emphasis>all</emphasis> of the canedit groups for a product - in order to make <emphasis>any</emphasis> change to bugs in that - product. - </para> - </section> - - - <section id="security"> - <title>Bugzilla Security</title> - - <warning> - <para>Poorly-configured MySQL and Bugzilla installations have - given attackers full access to systems in the past. Please take these - guidelines seriously, even for Bugzilla machines hidden away behind - your firewall. 80% of all computer trespassers are insiders, not - anonymous crackers.</para> - </warning> - - <note> - <para>These instructions must, of necessity, be somewhat vague since - Bugzilla runs on so many different platforms. If you have refinements - of these directions, please submit a bug to &bzg-bugs;. - </para> - </note> - - <warning> - <para>This is not meant to be a comprehensive list of every possible - security issue regarding the tools mentioned in this section. There is - no subsitute for reading the information written by the authors of any - software running on your system. - </para> - </warning> - - <section id="security-networking"> - <title>TCP/IP Ports</title> - - <!-- TODO: Make this make sense (TCP/IP) --> - <para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla - only needs 1... 2 if you need to use features that require e-mail such - as bug moving or the e-mail interface from contrib. You should audit - your server and make sure that you aren't listening on any ports you - don't need to be. You may also wish to use some kind of firewall - software to be sure that trafic can only be recieved on ports you - specify. - </para> - </section> - - <section id="security-mysql"> - <title>MySQL</title> - - <para>MySQL ships by default with many settings that should be changed. - By defaults it allows anybody to connect from localhost without a - password and have full administrative capabilities. It also defaults to - not have a root password (this is <emphasis>not</emphasis> the same as - the system root). Also, many installations default to running - <application>mysqld</application> as the system root. - </para> - - <orderedlist> - <listitem> - <para>Consult the documentation that came with your system for - information on making <application>mysqld</application> run as an - unprivleged user. - </para> - </listitem> - - <listitem> - <para>You should also be sure to disable the anonymous user account - and set a password for the root user. This is accomplished using the - following commands: - </para> - <programlisting> -<prompt>bash$</prompt> mysql mysql -<prompt>mysql></prompt> DELETE FROM user WHERE user = ''; -<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root'; -<prompt>mysql></prompt> FLUSH PRIVILEGES; - </programlisting> - <para>From this point forward you will need to use - <command>mysql -u root -p</command> and enter - <replaceable>new_password</replaceable> when prompted when using the - mysql client. - </para> - </listitem> - - <listitem> - <para>If you run MySQL on the same machine as your httpd server, you - should consider disabling networking from within MySQL by adding - the following to your <filename>/etc/my.conf</filename>: - </para> - <programlisting> -[myslqd] -# Prevent network access to MySQL. -skip-networking - </programlisting> - </listitem> - - <listitem> - <para>You may also consider running MySQL, or even all of Bugzilla - in a chroot jail; however, instructions for doing that are beyond - the scope of this document. - </para> - </listitem> - - </orderedlist> - - </section> - - <section id="security-daemon"> - <title>Daemon Accounts</title> - - <para>Many daemons, such as Apache's httpd and MySQL's mysqld default to - running as either <quote>root</quote> or <quote>nobody</quote>. Running - as <quote>root</quote> introduces obvious security problems, but the - problems introduced by running everything as <quote>nobody</quote> may - not be so obvious. Basically, if you're running every daemon as - <quote>nobody</quote> and one of them gets comprimised, they all get - comprimised. For this reason it is recommended that you create a user - account for each daemon. - </para> - - <note> - <para>You will need to set the <varname>webservergroup</varname> to - the group you created for your webserver to run as in - <filename>localconfig</filename>. This will allow - <command>./checksetup.pl</command> to better adjust the file - permissions on your Bugzilla install so as to not require making - anything world-writable. - </para> - </note> - - </section> - - <section id="security-access"> - <title>Web Server Access Controls</title> - - <para>There are many files that are placed in the Bugzilla directory - area that should not be accessable from the web. Because of the way - Bugzilla is currently layed out, the list of what should and should - not be accessible is rather complicated. A new installation method - is currently in the works which should solve this by allowing files - that shouldn't be accessible from the web to be placed in directory - outside the webroot. See - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug - 44659</ulink> for more information. - </para> - - <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> - <member><filename>runtests.sh</filename></member> - </simplelist> - </para> - </listitem> - <listitem> - <para>But allow: - <simplelist type="inline"> - <member><filename>localconfig.js</filename></member> - <member><filename>localconfig.rdf</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> - - <tip> - <para>Bugzilla ships with the ability to generate - <filename>.htaccess</filename> files instructing - <glossterm linkend="gloss-apache">Apache</glossterm> which files - should and should not be accessible. For more information, see - <xref linkend="http-apache"/>. - </para> - </tip> - - <para>You should test to make sure that the files mentioned above are - not accessible from the Internet, especially your - <filename>localconfig</filename> file which contains your database - password. To test, simply point your web browser at the file; for - example, to test mozilla.org's installation, we'd try to access - <ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should - get a <errorcode>403</errorcode> <errorname>Forbidden</errorname> - error. - </para> - - <caution> - <para>Not following the instructions in this section, including - testing, may result in sensitive information being globally - accessible. - </para> - </caution> - - <tip> - <para>You should check <xref linkend="http"/> to see if instructions - have been included for your web server. You should also compare those - instructions with this list to make sure everything is properly - accounted for. - </para> - </tip> - - </section> - - </section> - - <section id="cust-templates"> - <title>Template Customization</title> - - <para> - One of the large changes for 2.16 was the templatization of the - entire user-facing UI, using the - <ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>. - Administrators can now 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. In the future, a Bugzilla installation may - have templates installed for multiple localizations, and select - which ones to use based on the user's browser language setting. - </para> - - <section> - <title>What to Edit</title> - <para> - There are two different ways of editing of Bugzilla's templates, - and which you use depends mainly on how you upgrade Bugzilla. The - template directory structure is that there's a top level directory, - <filename>template</filename>, which contains a directory for - each installed localization. The default English templates are - therefore in <filename>en</filename>. Underneath that, there - is the <filename>default</filename> directory and optionally the - <filename>custom</filename> directory. The <filename>default</filename> - directory contains all the templates shipped with Bugzilla, whereas - the <filename>custom</filename> directory does not exist at first and - must be created if you want to use it. - </para> - - <para> - The first method of making customizations is to directly edit the - templates in <filename>template/en/default</filename>. This is - probably the best method for small changes if you are going to use - the CVS method of upgrading, because if you then execute a - <command>cvs update</command>, any template fixes will get - automagically merged into your modified versions. - </para> - - <para> - If you use this method, your installation will break if CVS conflicts - occur. - </para> - - <para> - The other method is to copy the templates into a mirrored directory - structure under <filename>template/en/custom</filename>. The templates - in this directory automatically override those in default. - This is the technique you - need to use if you use the overwriting method of upgrade, because - otherwise your changes will be lost. This method is also better if - you are using the CVS method of upgrading and are going to make major - changes, because it is guaranteed that the contents of this directory - will not be touched during an upgrade, and you can then decide whether - to continue using your own templates, or make the effort to merge your - changes into the new versions by hand. - </para> - - <para> - If you use this method, your installation may break if incompatible - changes are made to the template interface. If such changes are made - they will be documented in the release notes, provided you are using a - stable release of Bugzilla. If you use using unstable code, you will - need to deal with this one yourself, although if possible the changes - will be mentioned before they occur in the deprecations section of the - previous stable release's release notes. - </para> - - <note> - <para> - Don't directly edit the compiled templates in - <filename class="directory">data/template/*</filename> - your - changes will be lost when Template Toolkit recompiles them. - </para> - </note> - </section> - - <section> - <title>How To Edit Templates</title> - - <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>. However, you should particularly remember (for security - reasons) to always HTML filter things which come from the database or - user input, to prevent cross-site scripting attacks. - </para> - - <para> - However, one thing you should take particular care about is the need - to properly HTML filter data that has been passed into the template. - This means that if the data can possibly contain special HTML characters - such as <, and the data was not intended to be HTML, they need to be - converted to entity form, ie &lt;. You use the 'html' filter in the - Template Toolkit to do this. If you fail to do this, 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, ie %26. This actually encodes most - characters (but not the common ones such as letters and numbers and so - on), including the HTML-special characters, so there's never a need to - HTML filter afterwards. - </para> - - <para> - Editing templates is a good way of doing a "poor man's custom fields". - For example, if you don't use the Status Whiteboard, but want to have - a free-form text entry box for "Build Identifier", then you can just - edit the templates to change the field labels. It's still be called - status_whiteboard internally, but your users don't need to know that. - </para> - - <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/developerguide.html">Developers' - Guide</ulink>. - </para> - </note> - </section> - - - <section> - <title>Template Formats</title> - - <para> - Some CGIs have the ability to use more than one template. For - example, buglist.cgi can output bug lists as RDF or two - different forms of HTML (complex and simple). (Try this out - by appending <filename>&format=simple</filename> to a buglist.cgi - URL on your Bugzilla installation.) This - mechanism, called template 'formats', is extensible. - </para> - - <para> - To see if a CGI supports multiple output formats, grep the - CGI for "ValidateOutputFormat". If it's not present, adding - multiple format support isn't too hard - see how it's done in - other CGIs. - </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. Open up the <filename>localconfig</filename> file and find the - <filename>$contenttypes</filename> - variable. If your content type is not there, add it. Remember - the three- or four-letter tag assigned to you content type. - This tag will be part of the template filename. - </para> - - <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></filename> . - </para> - </section> - - - <section> - <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 "banner", the part of the header that appears - at the top of all Bugzilla pages. The default banner is reasonably - barren, so you'll probably want to customize this to give your - installation a distinctive look and feel. It is recommended you - preserve the Bugzilla version number in some form so the version - you are running can be determined, and users know what docs to read. - </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>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 wish to get bug submitters to give certain bits of structured - information, each in a separate input widget, for which there is not a - field in the database. The bug entry system has been designed in an - extensible fashion to enable you to define arbitrary fields and widgets, - and have their values appear formatted in the initial - Description, rather than in database fields. An example of this - is the mozilla.org - <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided - bug submission form</ulink>. - </para> - - <para> - To make this work, create a custom template for - <filename>enter_bug.cgi</filename> (the default template, on which you - could base it, is <filename>create.html.tmpl</filename>), - and either call it <filename>create.html.tmpl</filename> or use a format and - call it <filename>create-<formatname>.html.tmpl</filename>. - Put it in the <filename class="directory">custom/bug/create</filename> - directory. In it, add widgets for each piece of information you'd like - collected - such as a build number, or set of steps to reproduce. - </para> - - <para> - Then, create a template like - <filename>custom/bug/create/comment.txt.tmpl</filename>, also named - after your format if you are using one, which - references the form fields you have created. When a bug report is - submitted, the initial comment attached to the bug report will be - formatted according to the layout of this template. - </para> - - <para> - For example, if your 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 - <programlisting>BuildID: 20020303</programlisting> - would appear in the initial checkin comment. - </para> - </section> - - </section> - - <section id="cust-change-permissions"> - <title>Change Permission Customization</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 to it, you may have - to re-make them or port them if Bugzilla changes internally between - versions. - </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> - For maximum flexibility, customizing this means editing Bugzilla's Perl - code. This gives the administrator complete control over exactly who is - allowed to do what. The relevant function is called - <filename>CheckCanChangeField()</filename>, - and is found in <filename>process_bug.cgi</filename> in your - Bugzilla directory. If you open that file and grep for - "sub CheckCanChangeField", 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 "plumbing" which - makes the rest of the function work. In between those sections, you'll - find snippets of code like: - <programlisting> # Allow the owner 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 be removing pieces - for example, if you wanted to - prevent any user adding a comment to a bug, just remove the lines marked - "Allow anyone to change comments." And if you want the reporter to have - no special rights on bugs they have filed, just remove the entire section - which refers to him. - </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 (UserInGroup("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. Getting more weird: - <programlisting> if (($field eq "priority") && - ($vars->{'user'}{'login'} =~ /.*\@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> - - <para> - For a list of possible field names, look in - <filename>data/versioncache</filename> for the list called - <filename>@::log_columns</filename>. If you need help writing custom - rules for your organization, ask in the newsgroup. - </para> - </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, if any, local changes have been made</para> - </listitem> - </itemizedlist> - - <para>There are also three different methods 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>Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - </para> - - <para>Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.2 was released, it was a revision to 2.16.1. - </para> - - <para>Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.16.2 is a newer point - release than 2.14.5. - </para> - - <para>The examples in this section are written as if you were updating - to version 2.16.2. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - </para> - - <para>These examples also assume that your Bugzilla installation is at - <filename>/var/www/html/bugzilla</filename>. If that is not the case, - simply substitute the proper paths where appropriate. - </para> - - <example id="upgrade-cvs"> - <title>Upgrading using CVS</title> - - <para>Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. - - <tip> - <para>If you can do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. - </para> - </tip> - </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: <command>anonymous</command> -bash$ <command>cvs -q update -r BUGZILLA-2_16_2 -dP</command> -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - </programlisting> - - <para> - <caution> - <para>If a line in the output from <command>cvs update</command> - begins with a <computeroutput>C</computeroutput> 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> - - <note> - <para>You also need to run <command>./checksetup.pl</command> - before your Bugzilla upgrade will be complete. - </para> - </note> - </para> - </example> - - <example 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 download the latest tarball. This is the most - difficult option to use, especially if you have local changes. - </para> - - <programlisting> -bash$ <command>cd /var/www/html</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>tar xzvf bugzilla-2.16.2.tar.gz</command> -bugzilla-2.16.2/ -bugzilla-2.16.2/.cvsignore -bugzilla-2.16.2/1x1.gif -<emphasis>Output truncated</emphasis> -bash$ <command>cd bugzilla-2.16.2</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.16.2 bugzilla</command> -bash$ <command>cd bugzilla</command> -bash$ <command>./checksetup.pl</command> -<emphasis>Output omitted</emphasis> - </programlisting> - - <para> - <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. Also, the period at the - beginning of the <command>./checksetup.pl</command> is important and - can not be omitted. - </para> - </warning> - - <note> - <para>You will now have to reapply any changes you have made to your - local installation manually. - </para> - </note> - </para> - </example> - - <example id="upgrade-patches"> - <title>Upgrading using patches</title> - - <para>The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in (for minor - spelling fixes and the like). It is also theorectically possible to - scour the fixed bug list and pick and choose which patches to apply - from a point release, but this is not recommended either as what you'll - end up with is a hodge podge Bugzilla that isn't really any version. - This would also make it more difficult to upgrade in the future. - </para> - - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>gunzip bugzilla-2.16.1-to-2.16.2.diff.gz</command> -bash$ <command>patch -p1 < bugzilla-2.16.1-to-2.16.2.diff</command> -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - </programlisting> - - <para> - <caution> - <para>If you do this, beware that this doesn't change the entires in - your <filename id="dir">CVS</filename> directory so it may make - updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the - future. - </para> - </caution> - </para> - </example> - - </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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/conventions.sgml b/docs/sgml/conventions.sgml deleted file mode 100644 index 5e761d9f4..000000000 --- a/docs/sgml/conventions.sgml +++ /dev/null @@ -1,179 +0,0 @@ -<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<section id="conventions"> - <title>Document Conventions</title> - - <indexterm zone="conventions"> - <primary>conventions</primary> - </indexterm> - - <para>This document uses the following conventions:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Descriptions</entry> - - <entry>Appearance</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Warnings</entry> - - <entry> - <caution> - <para>Don't run with scissors!</para> - </caution> - </entry> - </row> - - <row> - <entry>Hint</entry> - - <entry> - <tip> - <para>Would you like a breath mint?</para> - </tip> - </entry> - </row> - - <row> - <entry>Notes</entry> - - <entry> - <note> - <para>Dear John...</para> - </note> - </entry> - </row> - - <row> - <entry>Information requiring special attention</entry> - - <entry> - <warning> - <para>Read this or the cat gets it.</para> - </warning> - </entry> - </row> - - <row> - <entry>File Names</entry> - - <entry> - <filename>filename</filename> - </entry> - </row> - - <row> - <entry>Directory Names</entry> - - <entry> - <filename class="directory">directory</filename> - </entry> - </row> - - <row> - <entry>Commands to be typed</entry> - - <entry> - <command>command</command> - </entry> - </row> - - <row> - <entry>Applications Names</entry> - - <entry> - <application>application</application> - </entry> - </row> - - <row> - <entry> - <foreignphrase>Prompt</foreignphrase> - - of users command under bash shell</entry> - - <entry>bash$</entry> - </row> - - <row> - <entry> - <foreignphrase>Prompt</foreignphrase> - - of root users command under bash shell</entry> - - <entry>bash#</entry> - </row> - - <row> - <entry> - <foreignphrase>Prompt</foreignphrase> - - of user command under tcsh shell</entry> - - <entry>tcsh$</entry> - </row> - - <row> - <entry>Environment Variables</entry> - - <entry> - <envar>VARIABLE</envar> - </entry> - </row> - - <row> - <entry>Emphasized word</entry> - - <entry> - <emphasis>word</emphasis> - </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> -</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/database.sgml b/docs/sgml/database.sgml deleted file mode 100644 index d32bb57cc..000000000 --- a/docs/sgml/database.sgml +++ /dev/null @@ -1,394 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="database"> - <title>The Bugzilla Database</title> - - <note> - <para>This document really needs to be updated with more fleshed out - information about primary keys, interrelationships, and maybe some nifty - tables to document dependencies. Any takers?</para> - </note> - - <section id="dbmodify"> - <title>Modifying Your Running System</title> - - <para>Bugzilla optimizes database lookups by storing all relatively - static information in the - <filename>versioncache</filename> file, located in the - <filename class="directory">data/</filename> - subdirectory under your installation directory.</para> - - <para>If you make a change to the structural data in your database (the - versions table for example), or to the - <quote>constants</quote> - - encoded in <filename>defparams.pl</filename>, you will need to remove - the cached content from the data directory (by doing a - <quote>rm data/versioncache</quote> - - ), or your changes won't show up.</para> - - <para> <filename>versioncache</filename> - gets automatically regenerated whenever it's more than - an hour old, so Bugzilla will eventually notice your changes by itself, - but generally you want it to notice right away, so that you can test - things.</para> - </section> - - <section id="dbdoc"> - <title>MySQL Bugzilla Database Introduction</title> - - <para>This information comes straight from my life. I was forced to learn - how Bugzilla organizes database because of nitpicky requests from users - for tiny changes in wording, rather than having people re-educate - themselves or figure out how to work our procedures around the tool. It - sucks, but it can and will happen to you, so learn how the schema works - and deal with it when it comes.</para> - - <para>So, here you are with your brand-new installation of Bugzilla. - You've got MySQL set up, Apache working right, Perl DBI and DBD talking - to the database flawlessly. Maybe you've even entered a few test bugs to - make sure email's working; people seem to be notified of new bugs and - changes, and you can enter and edit bugs to your heart's content. Perhaps - you've gone through the trouble of setting up a gateway for people to - submit bugs to your database via email, have had a few people test it, - and received rave reviews from your beta testers.</para> - - <para>What's the next thing you do? Outline a training strategy for your - development team, of course, and bring them up to speed on the new tool - you've labored over for hours.</para> - - <para>Your first training session starts off very well! You have a - captive audience which seems enraptured by the efficiency embodied in - this thing called "Bugzilla". You are caught up describing the nifty - features, how people can save favorite queries in the database, set them - up as headers and footers on their pages, customize their layouts, - generate reports, track status with greater efficiency than ever before, - leap tall buildings with a single bound and rescue Jane from the clutches - of Certain Death!</para> - - <para>But Certain Death speaks up -- a tiny voice, from the dark corners - of the conference room. "I have a concern," the voice hisses from the - darkness, "about the use of the word 'verified'.</para> - - <para>The room, previously filled with happy chatter, lapses into - reverential silence as Certain Death (better known as the Vice President - of Software Engineering) continues. "You see, for two years we've used - the word 'verified' to indicate that a developer or quality assurance - engineer has confirmed that, in fact, a bug is valid. I don't want to - lose two years of training to a new software product. You need to change - the bug status of 'verified' to 'approved' as soon as possible. To avoid - confusion, of course."</para> - - <para>Oh no! Terror strikes your heart, as you find yourself mumbling - "yes, yes, I don't think that would be a problem," You review the changes - with Certain Death, and continue to jabber on, "no, it's not too big a - change. I mean, we have the source code, right? You know, 'Use the - Source, Luke' and all that... no problem," All the while you quiver - inside like a beached jellyfish bubbling, burbling, and boiling on a hot - Jamaican sand dune...</para> - - <para>Thus begins your adventure into the heart of Bugzilla. You've been - forced to learn about non-portable enum() fields, varchar columns, and - tinyint definitions. The Adventure Awaits You!</para> - - <section> - <title>Bugzilla Database Basics</title> - - <para>If you were like me, at this point you're totally clueless about - the internals of MySQL, and if it weren't for this executive order from - the Vice President you couldn't care less about the difference between - a - <quote>bigint</quote> - - and a - <quote>tinyint</quote> - - entry in MySQL. I recommend you refer to the MySQL documentation, - available at - <ulink url="http://www.mysql.com/doc.html">MySQL.com</ulink> - - . Below are the basics you need to know about the Bugzilla database. - Check the chart above for more details.</para> - - <para> - <orderedlist> - <listitem> - <para>To connect to your database:</para> - - <para> - <prompt>bash#</prompt> - - <command>mysql</command> - - <parameter>-u root</parameter> - </para> - - <para>If this works without asking you for a password, - <emphasis>shame on you</emphasis> - - ! You should have locked your security down like the installation - instructions told you to. You can find details on locking down - your database in the Bugzilla FAQ in this directory (under - "Security"), or more robust security generalities in the - <ulink url="http://www.mysql.com/php/manual.php3?section=Privilege_system">MySQL - searchable documentation</ulink>. - </para> - </listitem> - - <listitem> - <para>You should now be at a prompt that looks like this:</para> - - <para> - <prompt>mysql></prompt> - </para> - - <para>At the prompt, if - <quote>bugs</quote> - - is the name you chose in the - <filename>localconfig</filename> - - file for your Bugzilla database, type:</para> - - <para> - <prompt>mysql</prompt> - - <command>use bugs;</command> - </para> - - </listitem> - </orderedlist> - </para> - - <section> - <title>Bugzilla Database Tables</title> - - <para>Imagine your MySQL database as a series of spreadsheets, and - you won't be too far off. If you use this command:</para> - - <para> - <prompt>mysql></prompt> - <command>show tables from bugs;</command> - </para> - - <para>you'll be able to see the names of all the - <quote>spreadsheets</quote> - (tables) in your database.</para> - - <para>From the command issued above, ou should have some - output that looks like this: -<programlisting> -+-------------------+ -| Tables in bugs | -+-------------------+ -| attachments | -| bugs | -| bugs_activity | -| cc | -| components | -| dependencies | -| fielddefs | -| groups | -| keyworddefs | -| keywords | -| logincookies | -| longdescs | -| milestones | -| namedqueries | -| products | -| profiles | -| profiles_activity | -| tokens | -| versions | -| votes | -| watch | -+-------------------+ -</programlisting> -</para> - -<literallayout> - Here's an overview of what each table does. Most columns in each table have -descriptive names that make it fairly trivial to figure out their jobs. - -attachments: This table stores all attachments to bugs. It tends to be your -largest table, yet also generally has the fewest entries because file -attachments are so (relatively) large. - -bugs: This is the core of your system. The bugs table stores most of the -current information about a bug, with the exception of the info stored in the -other tables. - -bugs_activity: This stores information regarding what changes are made to bugs -when -- a history file. - -cc: This tiny table simply stores all the CC information for any bug which has -any entries in the CC field of the bug. Note that, like most other tables in -Bugzilla, it does not refer to users by their user names, but by their unique -userid, stored as a primary key in the profiles table. - -components: This stores the programs and components (or products and -components, in newer Bugzilla parlance) for Bugzilla. Curiously, the "program" -(product) field is the full name of the product, rather than some other unique -identifier, like bug_id and user_id are elsewhere in the database. - -dependencies: Stores data about those cool dependency trees. - -fielddefs: A nifty table that defines other tables. For instance, when you -submit a form that changes the value of "AssignedTo" this table allows -translation to the actual field name "assigned_to" for entry into MySQL. - -groups: defines bitmasks for groups. A bitmask is a number that can uniquely -identify group memberships. For instance, say the group that is allowed to -tweak parameters is assigned a value of "1", the group that is allowed to edit -users is assigned a "2", and the group that is allowed to create new groups is -assigned the bitmask of "4". By uniquely combining the group bitmasks (much -like the chmod command in UNIX,) you can identify a user is allowed to tweak -parameters and create groups, but not edit users, by giving him a bitmask of -"5", or a user allowed to edit users and create groups, but not tweak -parameters, by giving him a bitmask of "6" Simple, huh? - If this makes no sense to you, try this at the mysql prompt: -mysql> select * from groups; - You'll see the list, it makes much more sense that way. - -keyworddefs: Definitions of keywords to be used - -keywords: Unlike what you'd think, this table holds which keywords are -associated with which bug id's. - -logincookies: This stores every login cookie ever assigned to you for every -machine you've ever logged into Bugzilla from. Curiously, it never does any -housecleaning -- I see cookies in this file I've not used for months. However, -since Bugzilla never expires your cookie (for convenience' sake), it makes -sense. - -longdescs: The meat of bugzilla -- here is where all user comments are stored! -You've only got 2^24 bytes per comment (it's a mediumtext field), so speak -sparingly -- that's only the amount of space the Old Testament from the Bible -would take (uncompressed, 16 megabytes). Each comment is keyed to the -bug_id to which it's attached, so the order is necessarily chronological, for -comments are played back in the order in which they are received. - -milestones: Interesting that milestones are associated with a specific product -in this table, but Bugzilla does not yet support differing milestones by -product through the standard configuration interfaces. - -namedqueries: This is where everybody stores their "custom queries". Very -cool feature; it beats the tar out of having to bookmark each cool query you -construct. - -products: What products you have, whether new bug entries are allowed for the -product, what milestone you're working toward on that product, votes, etc. It -will be nice when the components table supports these same features, so you -could close a particular component for bug entry without having to close an -entire product... - -profiles: Ahh, so you were wondering where your precious user information was -stored? Here it is! With the passwords in plain text for all to see! (but -sshh... don't tell your users!) - -profiles_activity: Need to know who did what when to who's profile? This'll -tell you, it's a pretty complete history. - -versions: Version information for every product - -votes: Who voted for what when - -watch: Who (according to userid) is watching who's bugs (according to their -userid). - - -=== -THE DETAILS -=== - - Ahh, so you're wondering just what to do with the information above? At the -mysql prompt, you can view any information about the columns in a table with -this command (where "table" is the name of the table you wish to view): - -mysql> show columns from table; - - You can also view all the data in a table with this command: - -mysql> select * from table; - - -- note: this is a very bad idea to do on, for instance, the "bugs" table if -you have 50,000 bugs. You'll be sitting there a while until you ctrl-c or -50,000 bugs play across your screen. - - You can limit the display from above a little with the command, where -"column" is the name of the column for which you wish to restrict information: - -mysql> select * from table where (column = "some info"); - - -- or the reverse of this - -mysql> select * from table where (column != "some info"); - - Let's take our example from the introduction, and assume you need to change -the word "verified" to "approved" in the resolution field. We know from the -above information that the resolution is likely to be stored in the "bugs" -table. Note we'll need to change a little perl code as well as this database -change, but I won't plunge into that in this document. Let's verify the -information is stored in the "bugs" table: - -mysql> show columns from bugs - - (exceedingly long output truncated here) -| bug_status| enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED','VERIFIED','CLOSED')||MUL | UNCONFIRMED|| - - Sorry about that long line. We see from this that the "bug status" column is -an "enum field", which is a MySQL peculiarity where a string type field can -only have certain types of entries. While I think this is very cool, it's not -standard SQL. Anyway, we need to add the possible enum field entry -'APPROVED' by altering the "bugs" table. - -mysql> ALTER table bugs CHANGE bug_status bug_status - -> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED", - -> "VERIFIED", "APPROVED", "CLOSED") not null; - - (note we can take three lines or more -- whatever you put in before the -semicolon is evaluated as a single expression) - -Now if you do this: - -mysql> show columns from bugs; - - you'll see that the bug_status field has an extra "APPROVED" enum that's -available! Cool thing, too, is that this is reflected on your query page as -well -- you can query by the new status. But how's it fit into the existing -scheme of things? - Looks like you need to go back and look for instances of the word "verified" -in the perl code for Bugzilla -- wherever you find "verified", change it to -"approved" and you're in business (make sure that's a case-insensitive search). -Although you can query by the enum field, you can't give something a status -of "APPROVED" until you make the perl changes. Note that this change I -mentioned can also be done by editing checksetup.pl, which automates a lot of -this. But you need to know this stuff anyway, right? - </literallayout> - </section> - </section> - </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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/dbschema.mysql b/docs/sgml/dbschema.mysql deleted file mode 100644 index 8b1378917..000000000 --- a/docs/sgml/dbschema.mysql +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/sgml/faq.sgml b/docs/sgml/faq.sgml deleted file mode 100644 index ef5f23123..000000000 --- a/docs/sgml/faq.sgml +++ /dev/null @@ -1,1321 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> - -<appendix id="faq"> - <title>The Bugzilla FAQ</title> - - <para> - This FAQ includes questions not covered elsewhere in the Guide. - </para> - - <qandaset> - - - <qandadiv id="faq-general"> - <title>General Questions</title> - - <qandaentry> - <question id="faq-general-information"> - <para> - Where can I find information about Bugzilla?</para> - </question> - <answer> - <para> - You can stay up-to-date with the latest Bugzilla - information at <ulink url="http://www.bugzilla.org/"> - http://www.bugzilla.org/</ulink> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-license"> - <para> - What license is Bugzilla distributed under? - </para> - </question> - <answer> - <para> - Bugzilla is covered by the Mozilla Public License. - See details at <ulink url="http://www.mozilla.org/MPL/"> - http://www.mozilla.org/MPL/</ulink> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-support"> - <para> - How do I get commercial support for Bugzilla? - </para> - </question> - <answer> - <para> - <ulink url="http://bugzilla.org/consulting.html">http://bugzilla.org/consulting.html</ulink> - is a list of people and companies who have asked us to list them - as consultants for Bugzilla. - </para> - <para> - <ulink url="http://www.collab.net/">www.collab.net</ulink> offers - Bugzilla as part of their standard offering to large projects. - They do have some minimum fees that are pretty hefty, and generally - aren't interested in small projects. - </para> - <para> - There are several experienced - Bugzilla hackers on the mailing list/newsgroup who are willing - to make themselves available for generous compensation. - Try sending a message to the mailing list asking for a volunteer. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-companies"> - <para> - What major companies or projects are currently using Bugzilla - for bug-tracking? - </para> - </question> - <answer> - <para> - There are <emphasis>dozens</emphasis> of major companies with public - Bugzilla sites to track bugs in their products. A few include: - <simplelist> - <member>Netscape/AOL</member> - <member>Mozilla.org</member> - <member>NASA</member> - <member>Red Hat Software</member> - <member>SuSe Corp</member> - <member>The Horde Project</member> - <member>AbiSource</member> - <member>Real Time Enterprises, Inc</member> - <member>Eggheads.org</member> - <member>Strata Software</member> - <member>RockLinux</member> - <member>Creative Labs (makers of SoundBlaster)</member> - <member>The Apache Foundation</member> - <member>The Gnome Foundation</member> - <member>Ximian</member> - <member>Linux-Mandrake</member> - </simplelist> - </para> - <para> - Suffice to say, there are more than enough huge projects using Bugzilla - that we can safely say it's extremely popular. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-maintainers"> - <para> - Who maintains Bugzilla? - </para> - </question> - <answer> - <para> - A - <ulink url="http://www.bugzilla.org/who_we_are.html">core team</ulink>, - led by Dave Miller (justdave@netscape.com). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-compare"> - <para> - How does Bugzilla stack up against other bug-tracking databases? - </para> - </question> - <answer> - <para> - We can't find any head-to-head comparisons of Bugzilla against - other defect-tracking software. If you know of one, please - get in touch. However, from the author's personal - experience with other bug-trackers, Bugzilla offers - superior performance on commodity hardware, better price - (free!), more developer- friendly features (such as stored - queries, email integration, and platform independence), - improved scalability, open source code, greater - flexibility, and superior ease-of-use. - </para> - <para> - If you happen to be a commercial bug-tracker vendor, please - step forward with a list of advantages your product has over - Bugzilla. We'd be happy to include it in the "Competitors" - section. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-bzmissing"> - <para> - Why doesn't Bugzilla offer this or that feature or compatibility - with this other tracking software? - </para> - </question> - <answer> - <para> - It may be that the support has not been built yet, or that you - have not yet found it. Bugzilla is making tremendous strides in - usability, customizability, scalability, and user interface. It - is widely considered the most complete and popular open-source - bug-tracking software in existence. - </para> - <para> - That doesn't mean it can't use improvement! - You can help the project along by either hacking a patch yourself - that supports the functionality you require, or else submitting a - "Request for Enhancement" (RFE) using the bug submission interface - at <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">bugzilla.mozilla.org</ulink>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-mysql"> - <para> - Why MySQL? I'm interested in seeing Bugzilla run on - Oracle/Sybase/Msql/PostgreSQL/MSSQL. - </para> - </question> - <answer> - <para> - MySQL was originally chosen because it is free, easy to install, - and was available for the hardware Netscape intended to run it on. - </para> - <para> - There is currently work in progress to make Bugzilla work on - PostgreSQL and Sybase in the default distribution. You can track - the progress of these initiatives in bugs <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=98304">98304</ulink> - and <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=173130">173130</ulink> - respectively. - </para> - <para> - Once both of these are done, adding support for additional - database servers should be trivial. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-bonsaitools"> - <para> - What is <filename>/usr/bonsaitools/bin/perl</filename>? - </para> - </question> - <answer> - <para> - Bugzilla used to have the path to perl on the shebang line set to - <filename>/usr/bonsaitools/bin/perl</filename> because when - Terry first started writing the code for mozilla.org he needed a - version of Perl and other tools that were completely under his - control. This location was abandoned for the 2.18 release in favor - of the more sensible <filename>/usr/bin/perl</filename>. If you - installed an older verion of Bugzilla and created the symlink we - suggested, you can remove it now (provided that you don't have - anything else, such as Bonsai, using it and you don't intend to - reinstall an older version of Bugzilla). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-perlpath"> - <para> - My perl is not located at <filename>/usr/bin/perl</filename>, is - there an easy way to change it everywhere it needs to be changed? - </para> - </question> - <answer> - <para> - Yes, the following bit of perl magic will change all the shebang - lines. Be sure to change <filename>/usr/local/bin/perl</filename> - to your path to the perl binary. - </para> - <programlisting> -perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl - </programlisting> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-general-cookie"> - <para> - Is there an easy way to change the Bugzilla cookie name? - </para> - </question> - <answer> - <para> - At present, no. - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-phb"> - <title>Managerial Questions</title> - <para> - <note> - <para> - Questions likely to be asked by managers. :-) - </para> - </note> - </para> - - <qandaentry> - <question id="faq-phb-client"> - <para> - Is Bugzilla web-based, or do you have to have specific software or - a specific operating system on your machine? - </para> - </question> - <answer> - <para> - It is web and e-mail based. You can edit bugs by sending specially - formatted email to a properly configured Bugzilla, or control via the web. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-integration"> - <para> - Can Bugzilla integrate with - Perforce (SCM software)? - </para> - </question> - <answer> - <para> - Yes! You can find more information elsewhere in "The Bugzilla - Guide" in the "Integration with Third-Party Products" section. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-projects"> - <para> - Does Bugzilla allow the user to track multiple projects? - </para> - </question> - <answer> - <para> - Absolutely! You can track any number of Products that can each be - composed of any number of Components. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-sorting"> - <para> - If I am on many projects, and search for all bugs assigned to me, will - Bugzilla list them for me and allow me to sort by project, severity etc? - </para> - </question> - <answer> - <para> - Yes. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-attachments"> - <para> - Does Bugzilla allow attachments (text, screenshots, URLs etc)? If yes, - are there any that are NOT allowed? - </para> - </question> - <answer> - <para> - Yes - any sort of attachment is allowed, although administrators can - configure a maximum size. - Bugzilla gives the user the option of either using the MIME-type - supplied by the browser, choosing from a pre-defined list or - manually typing any arbitrary MIME-type. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-priorities"> - <para> - Does Bugzilla allow us to define our own priorities and levels? Do we - have complete freedom to change the labels of fields and format of them, and - the choice of acceptable values? - </para> - </question> - <answer> - <para> - Yes. However, modifying some fields, notably those related to bug - progression states, also require adjusting the program logic to - compensate for the change. - </para> - <para> - There is no GUI for adding fields to Bugzilla at this - time. You can follow development of this feature at - <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=91037">http://bugzilla.mozilla.org/show_bug.cgi?id=91037</ulink> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-reporting"> - <para> - Does Bugzilla provide any reporting features, metrics, graphs, etc? You - know, the type of stuff that management likes to see. :) - </para> - </question> - <answer> - <para> - Yes. Look at <ulink url="http://bugzilla.mozilla.org/report.cgi"> - http://bugzilla.mozilla.org/report.cgi</ulink> for samples of what - Bugzilla can do in reporting and graphing. - </para> - <para> - If you can not get the reports you want from the included reporting - scripts, it is possible to hook up a professional reporting package - such as Crystal Reports using ODBC. If you choose to do this, - beware that giving direct access to the database does contain some - security implications. Even if you give read-only access to the - bugs database it will bypass the secure bugs features of Bugzilla. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-email"> - <para> - Is there email notification and if so, what do you see when you get an - email? - </para> - </question> - <answer> - <para> - Email notification is user-configurable. By default, the bug id and - Summary of the bug report accompany each email notification, along with - a list of the changes made. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-cclist"> - <para> - Can email notification be set up to send to multiple - people, some on the To List, CC List, BCC List etc? - </para> - </question> - <answer> - <para> - Yes. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-emailapp"> - <para> - Do users have to have any particular - type of email application? - </para> - </question> - <answer> - <para> - Bugzilla email is sent in plain text, the most compatible mail format - on the planet. - <note> - <para> - If you decide to use the bugzilla_email integration features - to allow Bugzilla to record responses to mail with the associated bug, - you may need to caution your users to set their mailer to "respond - to messages in the format in which they were sent". For security reasons - Bugzilla ignores HTML tags in comments, and if a user sends HTML-based - email into Bugzilla the resulting comment looks downright awful. - </para> - </note> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-data"> - <para> - Does Bugzilla allow data to be imported and exported? If I had outsiders - write up a bug report using a MS Word bug template, could that template be - imported into "matching" fields? If I wanted to take the results of a query - and export that data to MS Excel, could I do that? - </para> - </question> - <answer> - <para> - Bugzilla can output buglists as HTML (the default), CSV or RDF. - The link for CSV can be found at the bottom of the buglist in HTML - format. This CSV format can easily be imported into MS Excel or - other spread-sheet applications. - </para> - <para> - To use the RDF format of the buglist it is necessary to append a - <computeroutput>&ctype=rdf</computeroutput> to the URL. RDF - is meant to be machine readable and thus it is assumed that the - URL would be generated progmatically so there is no user visible - link to this format. - </para> - <para> - Currently the only script included with Bugzilla that can import - data is <filename>importxml.pl</filename> which is intended to be - used for importing the data generated by the XML ctype of - <filename>show_bug.cgi</filename> in association with bug moving. - Any other use is left as an exercise for the user. - </para> - <para> - There are also scripts included in the <filename>contrib/</filename> - directory for using e-mail to import information into Bugzilla, - but these scripts are not currently supported and included for - educational purposes. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-l10n"> - <para> - Has anyone converted Bugzilla to another language to be used in other - countries? Is it localizable? - </para> - </question> - <answer> - <para> - Yes. For more information including available translated templates, - see <ulink - url="http://www.bugzilla.org/download.html#localizations"/>. - The admin interfaces are still not included in these translated - templates and is therefore still English only. Also, there may be - issues with the charset not being declared. See <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=126266">bug 126226</ulink> - for more information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-reports"> - <para> - Can a user create and save reports? Can they do this in Word format? - Excel format? - </para> - </question> - <answer> - <para> - Yes. No. Yes (using the CSV format). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-searching"> - <para> - Does Bugzilla have the ability to search by word, phrase, compound - search? - </para> - </question> - <answer> - <para> - You have no idea. Bugzilla's query interface, particularly with the - advanced Boolean operators, is incredibly versatile. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-midair"> - <para> - Does Bugzilla provide record locking when there is simultaneous access - to the same bug? Does the second person get a notice that the bug is in use - or how are they notified? - </para> - </question> - <answer> - <para> - Bugzilla does not lock records. It provides mid-air collision detection, - and offers the offending user a choice of options to deal with the conflict. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-backup"> - <para> - Are there any backup features provided? - </para> - </question> - <answer> - <para> - MySQL, the database back-end for Bugzilla, allows hot-backup of data. - You can find strategies for dealing with backup considerations - at <ulink url="http://www.mysql.com/doc/B/a/Backup.html"> - http://www.mysql.com/doc/B/a/Backup.html</ulink> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-livebackup"> - <para> - Can users be on the system while a backup is in progress? - </para> - </question> - <answer> - <para> - Yes. However, commits to the database must wait - until the tables are unlocked. Bugzilla databases are typically - very small, and backups routinely take less than a minute. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-maintenance"> - <para> - What type of human resources are needed to be on staff to install and - maintain Bugzilla? Specifically, what type of skills does the person need to - have? I need to find out if we were to go with Bugzilla, what types of - individuals would we need to hire and how much would that cost vs buying an - "Out-of-the-Box" solution. - </para> - </question> - <answer> - <para> - If Bugzilla is set up correctly from the start, continuing maintenance - needs are minimal and can be done easily using the web interface. - </para> - <para> - Commercial Bug-tracking software typically costs somewhere upwards - of $20,000 or more for 5-10 floating licenses. Bugzilla consultation - is available from skilled members of the newsgroup. Simple questions - are answered there and then. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-installtime"> - <para> - What time frame are we looking at if we decide to hire people to install - and maintain the Bugzilla? Is this something that takes hours or weeks to - install and a couple of hours per week to maintain and customize or is this - a multi-week install process, plus a full time job for 1 person, 2 people, - etc? - </para> - </question> - <answer> - <para> - It all depends on your level of commitment. Someone with much Bugzilla - experience can get you up and running in less than a day, and - your Bugzilla install can run untended for years. If your - Bugzilla strategy is critical to your business workflow, hire somebody - with reasonable UNIX or Perl skills to handle your process management and - bug-tracking maintenance & customization. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-phb-cost"> - <para> - Is there any licensing fee or other fees for using Bugzilla? Any - out-of-pocket cost other than the bodies needed as identified above? - </para> - </question> - <answer> - <para> - No. MySQL asks, if you find their product valuable, that you purchase - a support contract from them that suits your needs. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-security"> - <title>Bugzilla Security</title> - - <qandaentry> - <question id="faq-security-mysql"> - <para> - How do I completely disable MySQL security if it's giving me problems - (I've followed the instructions in the installation section of this guide)? - </para> - </question> - <answer> - <para> - Run MySQL like this: "mysqld --skip-grant-tables". Please remember <emphasis>this - makes MySQL as secure as taping a $100 to the floor of a football stadium - bathroom for safekeeping.</emphasis> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-security-knownproblems"> - <para> - Are there any security problems with Bugzilla? - </para> - </question> - <answer> - <para> - The Bugzilla code has undergone a reasonably complete security audit, - and user-facing CGIs run under Perl's taint mode. However, - it is recommended that you closely examine permissions on your Bugzilla - installation, and follow the recommended security guidelines found - in The Bugzilla Guide. - </para> - </answer> - </qandaentry> - - - <qandaentry> - <question id="faq-security-mysqluser"> - <para> - I've implemented the security fixes mentioned in Chris Yeh's security - advisory of 5/10/2000 advising not to run MySQL as root, and am running into - problems with MySQL no longer working correctly. - </para> - </question> - <answer> - <para> - This is a common problem, related to running out of file descriptors. - Simply add "ulimit -n unlimited" to the script which starts - mysqld. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-email"> - <title>Bugzilla Email</title> - - <qandaentry> - <question id="faq-email-nomail"> - <para> - I have a user who doesn't want to receive any more email from Bugzilla. - How do I stop it entirely for this user? - </para> - </question> - <answer> - <para> - The user should be able to set - this in user email preferences (uncheck all boxes) or you can add - their email address to the <filename>data/nomail</filename> file. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-testing"> - <para> - I'm evaluating/testing Bugzilla, and don't want it to send email to - anyone but me. How do I do it? - </para> - </question> - <answer> - <para> - Edit the "newchangedmail" Param. Replace "To:" with "X-Real-To:", - replace "Cc:" with "X-Real-CC:", and add a "To: <youremailaddress>". - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-whine"> - <para> - I want whineatnews.pl to whine at something more, or other than, only new - bugs. How do I do it? - </para> - </question> - <answer> - <para> - Try Klaas Freitag's excellent patch for "whineatassigned" functionality. - You can find it at <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=6679"/>. This - patch is against an older version of Bugzilla, so you must apply - the diffs manually. - <!-- TODO: Mention Joel's "Fine Whine" patch" --> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-procmail"> - <para> - I don't like/want to use Procmail to hand mail off to bug_email.pl. - What alternatives do I have? - </para> - </question> - <answer> - <para> - You can call bug_email.pl directly from your aliases file, with - an entry like this: - <blockquote> - <para> - bugzilla-daemon: "|/usr/local/bin/bugzilla/contrib/bug_email.pl" - </para> - </blockquote> - However, this is fairly nasty and subject to problems; you also - need to set up your smrsh (sendmail restricted shell) to allow - it. In a pinch, though, it can work. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-mailif"> - <para> - How do I set up the email interface to submit/change bugs via email? - </para> - </question> - <answer> - <para> - You can find an updated README.mailif file in the contrib/ directory - of your Bugzilla distribution that walks you through the setup. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-sendmailnow"> - <para> - Email takes FOREVER to reach me from Bugzilla -- it's extremely slow. - What gives? - </para> - </question> - <answer> - <para> - If you are using an alternate <glossterm linkend="gloss-mta">MTA</glossterm>, - make sure the options given in <filename>Bugzilla/BugMail.pm</filename> - and any other place where <application>sendmail</application> is called from - are correct for your MTA. You should also ensure that the - <option>sendmailnow</option> param is set to <literal>on</literal>. - </para> - <para> - If you are using <application>sendmail</application>, try enabling - <option>sendmailnow</option> in <filename>editparams.cgi</filename>. - <!-- TODO provide more info about this, possibly a link to admin --> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-email-nonreceived"> - <para> - How come email from Bugzilla changes never reaches me? - </para> - </question> - <answer> - <para> - Double-check that you have not turned off email in your user preferences. - Confirm that Bugzilla is able to send email by visiting the "Log In" - link of your Bugzilla installation and clicking the "Email me a password" - button after entering your email address. - </para> - <para> - If you never receive mail from Bugzilla, chances you do not have - sendmail in "/usr/lib/sendmail". Ensure sendmail lives in, or is symlinked - to, "/usr/lib/sendmail". - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-db"> - <title>Bugzilla Database</title> - - <qandaentry> - <question id="faq-db-oracle"> - <para> - I've heard Bugzilla can be used with Oracle? - </para> - </question> - <answer> - <para> - Red Hat's old version of Bugzilla (based on 2.8) worked on Oracle. - Red Hat's newer version (based on 2.17.1 and soon to be merged into - the main distribution) runs on PostgreSQL. At this time we know of - no recent ports of Bugzilla to Oracle but do intend to support it - in the future (possibly the 2.20 time-frame). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-corrupted"> - <para> - I think my database might be corrupted, or contain invalid entries. What - do I do? - </para> - </question> - <answer> - <para> - Run the <quote>sanity check</quote> utility - (<filename>./sanitycheck.cgi</filename> in the - Bugzilla_home directory) from your web browser to see! If - it finishes without errors, you're - <emphasis>probably</emphasis> OK. If it doesn't come back - OK (i.e. any red letters), there are certain things - Bugzilla can recover from and certain things it can't. If - it can't auto-recover, I hope you're familiar with - mysqladmin commands or have installed another way to - manage your database. Sanity Check, although it is a good - basic check on your database integrity, by no means is a - substitute for competent database administration and - avoiding deletion of data. It is not exhaustive, and was - created to do a basic check for the most common problems - in Bugzilla databases. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-manualedit"> - <para> - I want to manually edit some entries in my database. How? - </para> - </question> - <answer> - <para> - There is no facility in Bugzilla itself to do this. It's also generally - not a smart thing to do if you don't know exactly what you're doing. - However, if you understand SQL you can use the <command>mysql</command> - command line utility to manually insert, delete and modify table - information. There are also more intuitive GUI clients available. - Personal favorites of the Bugzilla team are <ulink - url="http://www.phpmyadmin.net/">phpMyAdmin</ulink> and <ulink - url="http://www.mysql.com/downloads/gui-mycc.html">MySQL Control - Center</ulink>. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-permissions"> - <para> - I think I've set up MySQL permissions correctly, but Bugzilla still can't - connect. - </para> - </question> - <answer> - <para> - Try running MySQL from its binary: "mysqld --skip-grant-tables". This - will allow you to completely rule out grant tables as the cause of your - frustration. If this Bugzilla is able to connect at this point then - you need to check that you have granted proper permission to the user - password combo defined in <filename>localconfig</filename>. - </para> - <warning> - <para> - Running MySQL with this command line option is very insecure and - should only be done when not connected to the external network - as a troubleshooting step. - </para> - </warning> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-db-synchronize"> - <para> - How do I synchronize bug information among multiple different Bugzilla - databases? - </para> - </question> - <answer> - <para> - Well, you can synchronize or you can move bugs. Synchronization will - only work one way -- you can create a read-only copy of the database - at one site, and have it regularly updated at intervals from the main - database. - </para> - <para> - MySQL has some synchronization features builtin to the latest releases. - It would be great if someone looked into the possibilities there - and provided a report to the newsgroup on how to effectively - synchronize two Bugzilla installations. - </para> - <para> - If you simply need to transfer bugs from one Bugzilla to another, - checkout the "move.pl" script in the Bugzilla distribution. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv id="faq-nt"> - <title>Bugzilla and Win32</title> - - <qandaentry> - <question id="faq-nt-easiest"> - <para> - What is the easiest way to run Bugzilla on Win32 (Win98+/NT/2K)? - </para> - </question> - <answer> - <para> - Remove Windows. Install Linux. Install Bugzilla. - The boss will never know the difference. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-bundle"> - <para> - Is there a "Bundle::Bugzilla" equivalent for Win32? - </para> - </question> - <answer> - <para> - Not currently. Bundle::Bugzilla enormously simplifies Bugzilla - installation on UNIX systems. If someone can volunteer to - create a suitable PPM bundle for Win32, it would be appreciated. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-mappings"> - <para> - CGI's are failing with a "something.cgi is not a valid Windows NT - application" error. Why? - </para> - </question> - <answer> - <para> - Depending on what Web server you are using, you will have to configure - the Web server to treat *.cgi files as CGI scripts. In IIS, you do this by - adding *.cgi to the App Mappings with the <path>\perl.exe %s %s as the - executable. - </para> - <para> - Microsoft has some advice on this matter, as well: - <blockquote> - <para> - "Set application mappings. In the ISM, map the extension for the script - file(s) to the executable for the script interpreter. For example, you might - map the extension .py to Python.exe, the executable for the Python script - interpreter. Note For the ActiveState Perl script interpreter, the extension - .pl is associated with PerlIS.dll by default. If you want to change the - association of .pl to perl.exe, you need to change the application mapping. - In the mapping, you must add two percent (%) characters to the end of the - pathname for perl.exe, as shown in this example: c:\perl\bin\perl.exe %s %s" - </para> - </blockquote> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-nt-dbi"> - <para> - I'm having trouble with the perl modules for NT not being able to talk to - to the database. - </para> - </question> - <answer> - <para> - Your modules may be outdated or inaccurate. Try: - <orderedlist> - <listitem> - <para> - Hitting http://www.activestate.com/ActivePerl - </para> - </listitem> - <listitem> - <para> - Download ActivePerl - </para> - </listitem> - <listitem> - <para> - Go to your prompt - </para> - </listitem> - <listitem> - <para> - Type 'ppm' - </para> - </listitem> - <listitem> - <para> - <prompt>PPM></prompt> <command>install DBI DBD-mysql GD</command> - </para> - </listitem> - </orderedlist> - I reckon TimeDate and Data::Dumper come with the activeperl. You can check - the ActiveState site for packages for installation through PPM. - <ulink url=" http://www.activestate.com/Packages/"> - http://www.activestate.com/Packages/</ulink> - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-use"> - <title>Bugzilla Usage</title> - - <qandaentry> - <question id="faq-use-changeaddress"> - <para> - How do I change my user name (email address) in Bugzilla? - </para> - </question> - <answer> - <para> - New in 2.16 - go to the Account section of the Preferences. You will - be emailed at both addresses for confirmation. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-query"> - <para> - The query page is very confusing. Isn't there a simpler way to query? - </para> - </question> - <answer> - <para> - The interface was simplified by a UI designer for 2.16. Further - suggestions for improvement are welcome, but we won't sacrifice power for - simplicity. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-accept"> - <para> - I'm confused by the behavior of the "accept" button in the Show Bug form. - Why doesn't it assign the bug to me when I accept it? - </para> - </question> - <answer> - <para> - The current behavior is acceptable to bugzilla.mozilla.org and most - users. You have your choice of patches - to change this behavior, however. - <simplelist> - <member><ulink url="http://bugzilla.mozilla.org/showattachment.cgi?attach_id=8029"> - Add a "and accept bug" radio button</ulink></member> - <member><ulink url="http://bugzilla.mozilla.org/showattachment.cgi?attach_id=8153"> - "Accept" button automatically assigns to you</ulink></member> - </simplelist> - Note that these patches are somewhat dated. You will need to apply - them manually. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-attachment"> - <para> - I can't upload anything into the database via the "Create Attachment" - link. What am I doing wrong? - </para> - </question> - <answer> - <para> - The most likely cause is a very old browser or a browser that is - incompatible with file upload via POST. Download the latest Netscape, - Microsoft, or Mozilla browser to handle uploads correctly. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-use-keyword"> - <para> - How do I change a keyword in Bugzilla, once some bugs are using it? - </para> - </question> - <answer> - <para> - In the Bugzilla administrator UI, edit the keyword and it will let you - replace the old keyword name with a new one. This will cause a problem - with the keyword cache. Run sanitycheck.cgi to fix it. - </para> - </answer> - </qandaentry> - - </qandadiv> - - <qandadiv id="faq-hacking"> - <title>Bugzilla Hacking</title> - - <qandaentry> - <question id="faq-hacking-templatestyle"> - <para> - What kind of style should I use for templatization? - </para> - </question> - <answer> - <para> - Gerv and Myk suggest a 2-space indent, with embedded code sections on - their own line, in line with outer tags. Like this:</para> - <programlisting><![CDATA[ -<fred> -[% IF foo %] - <bar> - [% FOREACH x = barney %] - <tr> - <td> - [% x %] - </td> - <tr> - [% END %] -[% END %] -</fred> -]]></programlisting> - - <para> Myk also recommends you turn on PRE_CHOMP in the template - initialization to prevent bloating of HTML with unnecessary whitespace. - </para> - - <para>Please note that many have differing opinions on this subject, - and the existing templates in Bugzilla espouse both this and a 4-space - style. Either is acceptable; the above is preferred.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-bugzillabugs"> - <para> - What bugs are in Bugzilla right now? - </para> - </question> - <answer> - <para> - Try <ulink url="http://bugzilla.mozilla.org/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=Bugzilla"> - this link</ulink> to view current bugs or requests for - enhancement for Bugzilla. - </para> - <para> - You can view bugs marked for &bz-nextver; release - <ulink url="http://bugzilla.mozilla.org/buglist.cgi?product=Bugzilla&target_milestone=Bugzilla+&bz-nextver;">here</ulink>. - This list includes bugs for the &bz-nextver; release that have already - been fixed and checked into CVS. Please consult the - <ulink url="http://www.bugzilla.org/"> - Bugzilla Project Page</ulink> for details on how to - check current sources out of CVS so you can have these - bug fixes early! - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-priority"> - <para> - How can I change the default priority to a null value? For instance, have the default - priority be "---" instead of "P2"? - </para> - </question> - <answer> - <para> - This is well-documented here: <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=49862"> - http://bugzilla.mozilla.org/show_bug.cgi?id=49862</ulink>. Ultimately, it's as easy - as adding the "---" priority field to your localconfig file in the appropriate area, - re-running checksetup.pl, and then changing the default priority in your browser using - "editparams.cgi". - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="faq-hacking-patches"> - <para> - What's the best way to submit patches? What guidelines should I follow? - </para> - </question> - <answer> - <blockquote> - <orderedlist> - <listitem> - <para> - Enter a bug into bugzilla.mozilla.org for the <quote><ulink - url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">Bugzilla</ulink></quote> - product. - </para> - </listitem> - <listitem> - <para> - Upload your patch as a unified diff (having used "diff -u" against - the <emphasis>current sources</emphasis> checked out of CVS), - or new source file by clicking - "Create a new attachment" link on the bug page you've just created, and - include any descriptions of database changes you may make, into the bug - ID you submitted in step #1. Be sure and click the "Patch" checkbox - to indicate the text you are sending is a patch! - </para> - </listitem> - <listitem> - <para> - Announce your patch and the associated URL - (http://bugzilla.mozilla.org/show_bug.cgi?id=XXXXXX) for discussion in - the newsgroup (netscape.public.mozilla.webtools). You'll get a really - good, fairly immediate reaction to the implications of your patch, - which will also give us an idea how well-received the change would - be. - </para> - </listitem> - <listitem> - <para> - If it passes muster with minimal modification, the person to whom - the bug is assigned in Bugzilla is responsible for seeing the patch - is checked into CVS. - </para> - </listitem> - <listitem> - <para> - Bask in the glory of the fact that you helped write the most successful - open-source bug-tracking software on the planet :) - </para> - </listitem> - </orderedlist> - </blockquote> - </answer> - </qandaentry> - - - </qandadiv> - - </qandaset> - -</appendix> - - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/sgml/filetemp.patch b/docs/sgml/filetemp.patch deleted file mode 100644 index 9fb70adce..000000000 --- a/docs/sgml/filetemp.patch +++ /dev/null @@ -1,18 +0,0 @@ ---- File/Temp.pm.orig Thu Feb 6 16:26:00 2003 -+++ File/Temp.pm Thu Feb 6 16:26:23 2003 -@@ -205,6 +205,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; -@@ -226,6 +227,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; diff --git a/docs/sgml/gd-makefile.patch b/docs/sgml/gd-makefile.patch deleted file mode 100644 index 8ec35a23a..000000000 --- a/docs/sgml/gd-makefile.patch +++ /dev/null @@ -1,22 +0,0 @@ ---- GD-1.33/Makefile.PL Fri Aug 4 16:59:22 2000 -+++ GD-1.33-darwin/Makefile.PL Tue Jun 26 01:29:32 2001 -@@ -3,8 +3,8 @@ - warn "NOTICE: This module requires libgd 1.8.3 or higher (shared library version 4.X).\n"; - - # =====> PATHS: CHECK AND ADJUST <===== --my @INC = qw(-I/usr/local/include -I/usr/local/include/gd); --my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/usr/local/lib ); -+my @INC = qw(-I/sw/include -I/sw/include/gd -I/usr/local/include -I/usr/local/include/gd); -+my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/sw/lib -L/usr/local/lib); - my @LIBS = qw(-lgd -lpng -lz); - - # FEATURE FLAGS -@@ -23,7 +23,7 @@ - - push @LIBS,'-lttf' if $TTF; - push @LIBS,'-ljpeg' if $JPEG; --push @LIBS, '-lm' unless $^O eq 'MSWin32'; -+push @LIBS, '-lm' unless ($^O =~ /^MSWin32|darwin$/); - - # FreeBSD 3.3 with libgd built from ports croaks if -lXpm is specified - if ($^O ne 'freebsd' && $^O ne 'MSWin32') { diff --git a/docs/sgml/gfdl.sgml b/docs/sgml/gfdl.sgml deleted file mode 100644 index fdfdb4bc5..000000000 --- a/docs/sgml/gfdl.sgml +++ /dev/null @@ -1,448 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="gfdl"> - <title>GNU Free Documentation License</title> - -<!-- - GNU Project - Free Software Foundation (FSF) --> -<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" --> -<!-- section> - <title>GNU Free Documentation License</title --> - <para>Version 1.1, March 2000</para> - - <blockquote> - <para>Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, - Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and - distribute verbatim copies of this license document, but changing it is - not allowed.</para> - </blockquote> - - <section label="0" id="gfdl-0"> - <title>PREAMBLE</title> - - <para>The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone the - effective freedom to copy and redistribute it, with or without modifying - it, either commercially or noncommercially. Secondarily, this License - preserves for the author and publisher a way to get credit for their - work, while not being considered responsible for modifications made by - others.</para> - - <para>This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. It - complements the GNU General Public License, which is a copyleft license - designed for free software.</para> - - <para>We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a free - program should come with manuals providing the same freedoms that the - software does. But this License is not limited to software manuals; it - can be used for any textual work, regardless of subject matter or whether - it is published as a printed book. We recommend this License principally - for works whose purpose is instruction or reference.</para> - </section> - - <section label="1" id="gfdl-1"> - <title>APPLICABILITY AND DEFINITIONS</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/"> - http://www.gnu.org/copyleft/</ulink> - - .</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/glossary.sgml b/docs/sgml/glossary.sgml deleted file mode 100644 index d979505ca..000000000 --- a/docs/sgml/glossary.sgml +++ /dev/null @@ -1,482 +0,0 @@ -<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> -<glossary id="glossary"> - <glossdiv> - <title>0-9, high ascii</title> - - <glossentry> - <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> - <acronym>CPAN</acronym> - </glossterm> - - <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> - </glossdiv> - - <glossdiv id="gloss-d"> - <title>D</title> - - <glossentry> - <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> - </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. Many unix based systems use - <ulink url="http://www.sendmail.org">sendmail</ulink> which is what - Bugzilla expects to find by default at <filename>/usr/sbin/sendmail</filename>. - Many other MTA's will work, but they all 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> - <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 Managment 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> - </glossdiv> - - <glossdiv id="gloss-s"> - <title>S</title> - - <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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/index.sgml b/docs/sgml/index.sgml deleted file mode 100644 index 3b3516e14..000000000 --- a/docs/sgml/index.sgml +++ /dev/null @@ -1,21 +0,0 @@ -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml deleted file mode 100644 index b9fee2cc8..000000000 --- a/docs/sgml/installation.sgml +++ /dev/null @@ -1,1615 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<chapter id="installation" xreflabel="Bugzilla Installation"> - <title>Installation</title> - - <section id="stepbystep" xreflabel="Bugzilla Installation Step-by-step"> - <title>Step-by-step Install</title> - - <section id="intstall-into"> - <title>Introduction</title> - - <para>Bugzilla has been successfully installed under Solaris, Linux, - and Win32. Win32 is not yet officially supported, but many people - have got it working fine. - Please see - <xref linkend="os-win32" /> - for further advice on getting Bugzilla to work on Microsoft - Windows.</para> - - </section> - - <section id="install-package-list"> - <title>Package List</title> - - <note> - <para> If you are running the very most recent - version of Perl and MySQL (both the executables and development - libraries) on your system, you can skip these manual installation - steps for the Perl modules by using Bundle::Bugzilla; see - <xref linkend="bundlebugzilla" />. - </para> - </note> - - <para>The software packages necessary for the proper running of - Bugzilla (with download links) are: - <orderedlist> - - -<listitem> - <para> - <ulink url="http://www.mysql.com/">MySQL database server</ulink> - (&min-mysql-ver; or greater) - </para> -</listitem> - -<listitem> - <para> - <ulink url="http://www.perl.org">Perl</ulink> - (&min-perl-ver;, 5.6.1 is recommended if you wish to - use Bundle::Bugzilla) - </para> -</listitem> - -<listitem> - <para>Perl Modules (minimum version): - <orderedlist> - - <listitem> - <para> - <ulink url="http://www.template-toolkit.org">Template</ulink> - (v&min-template-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.perldoc.com/perl5.6/lib/File/Temp.html"> - File::Temp</ulink> - (&min-file-temp-ver;) (Prerequisite for Template) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig - </ulink> - (&min-appconfig-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink> - (&min-text-wrap-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec - </ulink> - (&min-file-spec-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper - </ulink> - (&min-data-dumper-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql - </ulink> - (&min-dbd-mysql-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink> - (&min-dbi-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse - </ulink> - (&min-date-format-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/CGI/">CGI - </ulink> - (&min-cgi-ver;) - </para> - </listitem> - - </orderedlist> - and, optionally: - <orderedlist> - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink> - (&min-gd-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - GD::Graph - (&min-gd-graph-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - GD::Text::Align - (&min-gd-text-align-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base - </ulink> - (&min-chart-base-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - XML::Parser - (&min-xml-parser-ver;) for the XML interface - </para> - </listitem> - - <listitem> - <para> - MIME::Parser - (&min-mime-parser-ver;) for the email interface - </para> - </listitem> - </orderedlist> - </para> -</listitem> - - -<listitem> - <para> - The web server of your choice. - <ulink url="http://www.apache.org/">Apache</ulink> - is highly recommended. - </para> -</listitem> - - - </orderedlist> - - <warning> - <para>It is a good idea, while installing Bugzilla, to ensure that there - is some kind of firewall between you and the rest of the Internet, - because your machine may be insecure for periods during the install. - Many - installation steps require an active Internet connection to complete, - but you must take care to ensure that at no point is your machine - vulnerable to an attack.</para> - </warning> - - </para> - </section> - - <section id="install-mysql"> - <title>MySQL</title> - - <para>Visit the MySQL homepage at - <ulink url="http://www.mysql.com">www.mysql.com</ulink> - to grab and install the latest stable release of the server. - </para> - - <note> - <para> Many of the binary - versions of MySQL store their data files in - <filename>/var</filename>. - On some Unix systems, this is part of a smaller root partition, - and may not have room for your bug database. You can set the data - directory as an option to <filename>configure</filename> - if you build MySQL from source yourself.</para> - </note> - - <para>If you install from something other than an RPM or Debian - package, you will need to add <filename>mysqld</filename> - to your init scripts so the server daemon will come back up whenever - your machine reboots. Further discussion of UNIX init sequences are - beyond the scope of this guide. - </para> - - <para>Change your init script to start - <filename>mysqld</filename> - with the ability to accept large packets. By default, - <filename>mysqld</filename> - only accepts packets up to 64K long. This limits the size of - attachments you may put on bugs. If you add - <option>-O max_allowed_packet=1M</option> - to the command that starts - <filename>mysqld</filename> - (or <filename>safe_mysqld</filename>), - then you will be able to have attachments up to about 1 megabyte. - There is a Bugzilla parameter for maximum attachment size; - you should configure it to match the value you choose here.</para> - - <para>If you plan on running Bugzilla and MySQL on the same machine, - consider using the - <option>--skip-networking</option> - option in the init script. This enhances security by preventing - network access to MySQL.</para> - - </section> - - <section id="install-perl"> - <title>Perl</title> - - <para>Any machine that doesn't have Perl on it is a sad machine indeed. - Perl can be got in source form from - <ulink url="http://www.perl.com">perl.com</ulink> for the rare - *nix systems which don't have it. - Although Bugzilla runs with perl &min-perl-ver;, - it's a good idea to be up to the very latest version - if you can when running Bugzilla. As of this writing, that is Perl - version &newest-perl-ver;.</para> - - <tip id="bundlebugzilla" - xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules"> - - <para>You can skip the following Perl module installation steps by - installing - <productname>Bundle::Bugzilla</productname> - - from - <glossterm linkend="gloss-cpan">CPAN</glossterm>, - which installs all required modules for you.</para> - - <para> - <computeroutput> - <prompt>bash#</prompt> - - <command>perl -MCPAN -e 'install "Bundle::Bugzilla"'</command> - </computeroutput> - </para> - - <para>Bundle::Bugzilla doesn't include GD, Chart::Base, or - MIME::Parser, which are not essential to a basic Bugzilla install. If - installing this bundle fails, you should install each module - individually to isolate the problem.</para> - </tip> - </section> - - <section id="perl-modules"> - <title>Perl Modules</title> - - <para> - All Perl modules can be found on the - <ulink url="http://www.cpan.org">Comprehensive Perl - Archive Network</ulink> (CPAN). The - CPAN servers have a real tendency to bog down, so please use mirrors. - </para> - - <para>Quality, general Perl module installation instructions can be - found on the CPAN website, but the easy thing to do is to just use the - CPAN shell which does all the hard work for you. - To use the CPAN shell to install a module: - </para> - - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>perl -MCPAN -e 'install "<modulename>"'</command> - </computeroutput> - </para> - - <para> - To do it the hard way: - </para> - - <para>Untar the module tarball -- it should create its own - directory</para> - - <para>CD to the directory just created, and enter the following - commands: - <orderedlist> - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - - <command>perl Makefile.PL</command> - </computeroutput> - </para> - </listitem> - - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - - <command>make</command> - </computeroutput> - </para> - </listitem> - - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - - <command>make test</command> - </computeroutput> - </para> - </listitem> - - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - - <command>make install</command> - </computeroutput> - </para> - </listitem> - </orderedlist> - </para> - - <warning> - <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> - </warning> - - - <section> - <title>DBI</title> - - <para>The DBI module is a generic Perl module used the - MySQL-related modules. As long as your Perl installation was done - correctly the DBI module should be a breeze. It's a mixed Perl/C - module, but Perl's MakeMaker system simplifies the C compilation - greatly.</para> - </section> - - <section> - <title>Data::Dumper</title> - - <para>The Data::Dumper module provides data structure persistence for - Perl (similar to Java's serialization). It comes with later - sub-releases of Perl 5.004, but a re-installation just to be sure it's - available won't hurt anything.</para> - </section> - - <section> - <title>MySQL-related modules</title> - - <para>The Perl/MySQL interface requires a few mutually-dependent Perl - modules. These modules are grouped together into the the - Msql-Mysql-modules package.</para> - - <para>The MakeMaker 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 and a testing user of 'test' - with a null password should find itself with sufficient access to run - tests on the 'test' database which MySQL created upon installation. - </para> - </section> - - <section> - <title>TimeDate modules</title> - - <para>Many of the more common date/time/calendar related Perl modules - have been grouped into a bundle similar to the MySQL modules bundle. - This bundle is stored on the CPAN under the name TimeDate. - The component module we're most interested in is the Date::Format - module, but installing all of them is probably a good idea anyway. - </para> - </section> - - <section> - <title>GD (optional)</title> - - <para>The GD library was written by Thomas Boutell a long while ago to - programatically generate images in C. Since then it's become the - defacto standard for programmatic image construction. The Perl bindings - to it found in the GD library are used on millions of web pages to - generate graphs on the fly. That's what Bugzilla will be using it for - so you must install it if you want any of the graphing to work.</para> - - <note> - <para>The Perl GD library 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 library README. - If compiling GD fails, it's probably because you're - missing a required library.</para> - </note> - </section> - - <section> - <title>Chart::Base (optional)</title> - - <para>The Chart module provides Bugzilla with on-the-fly charting - abilities. It can be installed in the usual fashion after it has been - fetched from CPAN. - Note that earlier versions that 0.99c used GIFs, which are no longer - supported by the latest versions of GD.</para> - </section> - - <section> - <title>Template Toolkit</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> - - <section id="sbs-http"> - <title>HTTP Server</title> - - <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. <xref linkend="http"/> has more information about - configuring web servers to work with Bugzilla. - </para> - - <note> - <para>We strongly recommend Apache as the web server to use. The - Bugzilla Guide installation instructions, in general, assume you are - using Apache. If you have got Bugzilla working using another webserver, - please share your experiences with us.</para> - </note> - - </section> - - <section> - <title>Bugzilla</title> - - <para>You should untar the Bugzilla files into a directory that you're - willing to make writable by the default web server user (probably - <quote>nobody</quote>). - You may decide to put the files in the main web space for your - web server or perhaps in - <filename>/usr/local</filename> - with a symbolic link in the web space that points to the Bugzilla - directory.</para> - - <tip> - <para>If you symlink the bugzilla directory into your Apache's HTML - hierarchy, you may receive - <errorname>Forbidden</errorname> - errors unless you add the - <quote>FollowSymLinks</quote> - directive to the <Directory> entry for the HTML root - in httpd.conf.</para> - </tip> - - <para>Once all the files are in a web accessible directory, make that - directory writable by your webserver's user. This is a temporary step - until you run the post-install - <filename>checksetup.pl</filename> - script, which locks down your installation.</para> - </section> - - <section> - <title>Setting Up the MySQL Database</title> - - <para>After you've gotten all the software installed and working you're - ready to start preparing the database for its life as the back end to - a high quality bug tracker.</para> - - <para>First, you'll want to fix MySQL permissions to allow access from - Bugzilla. For the purpose of this Installation section, the Bugzilla - username will be - <quote>bugs</quote>, and will have minimal permissions. - </para> - - <para>Begin by giving the MySQL root user a password. MySQL passwords are limited - to 16 characters. - <simplelist> - <member> - <computeroutput> - <prompt>bash#</prompt> - - <command>mysql -u root mysql</command> - </computeroutput> - </member> - - <member> - <computeroutput> - <prompt>mysql></prompt> - - <command>UPDATE user SET Password=PASSWORD('<new_password'>) - WHERE user='root';</command> - </computeroutput> - </member> - - <member> - <computeroutput> - <prompt>mysql></prompt> - - <command>FLUSH PRIVILEGES;</command> - </computeroutput> - </member> - </simplelist> - - From this point on, if you need to access MySQL as the MySQL root user, - you will need to use - <command>mysql -u root -p</command> - - and enter <new_password>. Remember that MySQL user names have - nothing to do with Unix user names (login names).</para> - - <para>Next, we use an SQL <command>GRANT</command> command to create a - <quote>bugs</quote> - - user, and grant sufficient permissions for checksetup.pl, which we'll - use later, to work its magic. 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>Remember to set <bugs_password> to some unique password. - <simplelist> - <member> - <computeroutput> - <prompt>mysql></prompt> - - <command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, - ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost - IDENTIFIED BY '<bugs_password>';</command> - </computeroutput> - </member> - - <member> - <computeroutput> - <prompt>mysql></prompt> - - <command>FLUSH PRIVILEGES;</command> - </computeroutput> - </member> - </simplelist> - </para> - - <note> - <para>If you are using MySQL 4, the bugs user also needs to be granted - the LOCK TABLES and CREATE TEMPORARY TABLES permissions. - </para> - </note> - </section> - - <section> - <title> - <filename>checksetup.pl</filename> - </title> - - <para>Next, run the magic checksetup.pl script. (Many thanks to - <ulink url="mailto:holgerschurig@nikocity.de">Holger Schurig </ulink> - for writing this script!) - This script is designed to make sure your MySQL database and other - configuration options are consistent with the Bugzilla CGI files. - It will make sure Bugzilla files and directories have reasonable - permissions, set up the - <filename>data</filename> - directory, and create all the MySQL tables. - <simplelist> - <member> - <computeroutput> - <prompt>bash#</prompt> - - <command>./checksetup.pl</command> - </computeroutput> - </member> - </simplelist> - - The first time you run it, it will create a file called - <filename>localconfig</filename>.</para> - - <para>This file contains a variety of settings you may need to tweak - including how Bugzilla should connect to the MySQL database.</para> - - <para>The connection settings include: - <orderedlist> - <listitem> - <para>server's host: just use - <quote>localhost</quote> - if the MySQL server is local</para> - </listitem> - - <listitem> - <para>database name: - <quote>bugs</quote> - if you're following these directions</para> - </listitem> - - <listitem> - <para>MySQL username: - <quote>bugs</quote> - if you're following these directions</para> - </listitem> - - <listitem> - <para>Password for the - <quote>bugs</quote> - MySQL account; (<bugs_password>) above</para> - </listitem> - </orderedlist> - </para> - - <para>Once you are happy with the settings, - <filename>su</filename> to the user - your web server runs as, and re-run - <filename>checksetup.pl</filename>. (Note: on some security-conscious - systems, you may need to change the login shell for the webserver - account before you can do this.) - On this second run, it will create the database and an administrator - account for which you will be prompted to provide information.</para> - - <note> - <para>The checksetup.pl script is designed so that you can run it at - any time without causing harm. You should run it after any upgrade to - Bugzilla.</para> - </note> - </section> - - <section> - <title>Configuring Bugzilla</title> - <para> - You should run through the parameters on the Edit Parameters page - (link in the footer) and set them all to appropriate values. - They key parameters are documented in <xref linkend="parameters" />. - </para> - </section> - </section> - - <section id="extraconfig"> - <title>Optional Additional Configuration</title> - - <section> - <title>Dependency Charts</title> - - <para>As well as the text-based dependency graphs, Bugzilla also - supports dependency graphing, using a package called 'dot'. - Exactly how this works is controlled by the 'webdotbase' parameter, - which can have one of three values: - </para> - - <para> - <orderedlist> - <listitem> - <para> - A complete file path to the command 'dot' (part of - <ulink url="http://www.graphviz.org/">GraphViz</ulink>) - will generate the graphs locally - </para> - </listitem> - <listitem> - <para> - A URL prefix pointing to an installation of the webdot package will - generate the graphs remotely - </para> - </listitem> - <listitem> - <para> - A blank value will disable dependency graphing. - </para> - </listitem> - </orderedlist> - </para> - - <para>So, to get this working, install - <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you - do that, you need to - <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable - server-side image maps</ulink> in Apache. - Alternatively, you could set up a webdot server, or use the AT&T - public webdot server (the - default for the webdotbase param). Note that AT&T's server won't work - if Bugzilla is only accessible using HARTS. - </para> - </section> - - <section> - <title>Bug Graphs</title> - - <para>As long as you installed the GD and Graph::Base Perl modules you - might as well turn on the nifty Bugzilla bug reporting graphs.</para> - - <para>Add a cron entry like this to run - <filename>collectstats.pl</filename> - daily at 5 after midnight: - <simplelist> - <member> - <computeroutput> - <prompt>bash#</prompt> - - <command>crontab -e</command> - </computeroutput> - </member> - - <member> - <computeroutput>5 0 * * * cd <your-bugzilla-directory> ; - ./collectstats.pl</computeroutput> - </member> - </simplelist> - </para> - - <para>After two days have passed you'll be able to view bug graphs from - the Bug Reports page.</para> - </section> - - <section> - <title>The Whining Cron</title> - - <para>By now you have a fully functional Bugzilla, but what good are - bugs if they're not annoying? To help make those bugs more annoying you - can set up Bugzilla's automatic whining system to complain at engineers - which leave their bugs in the NEW state without triaging them. - </para> - <para> - This can be done by - adding the following command as a daily crontab entry (for help on that - see that crontab man page): - <simplelist> - <member> - <computeroutput> - <command>cd <your-bugzilla-directory> ; - ./whineatnews.pl</command> - </computeroutput> - </member> - </simplelist> - </para> - - <tip> - <para>Depending on your system, crontab may have several manpages. - The following command should lead you to the most useful page for - this purpose: - <programlisting> -man 5 crontab - </programlisting> - </para> - </tip> - </section> - - <section id="bzldap"> - <title>LDAP Authentication</title> - <para> - <warning> - <para>This information on using the LDAP - authentication options with Bugzilla is old, and the authors do - not know of anyone who has tested it. Approach with caution. - </para> - </warning> - </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 where - you need to deal with user ID (e.g assigning a bug) use the email - address. The LDAP authentication builds on top of this scheme, rather - than replacing it. The initial log in is done with a username and - password for the LDAP directory. This then fetches the email address - from LDAP and authenticates seamlessly in the standard Bugzilla - authentication scheme using this email address. If an account for this - address already exists in your Bugzilla system, it will log in to that - account. If no account for that email address exists, one is created at - the time of login. (In this case, Bugzilla will attempt to use the - "displayName" or "cn" attribute to determine the user's full name.) - After authentication, all other user-related tasks are still handled by - email address, not LDAP username. You still assign bugs by email - address, query on users by email address, etc. - </para> - - <para>Using LDAP for Bugzilla authentication requires the - Mozilla::LDAP (aka PerLDAP) Perl module. The - Mozilla::LDAP module in turn requires Netscape's Directory SDK for C. - After you have installed the SDK, then install the PerLDAP module. - Mozilla::LDAP and the Directory SDK for C are both - <ulink url="http://www.mozilla.org/directory/">available for - download</ulink> from mozilla.org. - </para> - - <para> - Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP - directory for - authentication. Be very careful when setting up this parameter; if you - set LDAP authentication, but do not have a valid LDAP directory set up, - you will not be able to log back in to Bugzilla once you log out. (If - this happens, you can get back in by manually editing the data/params - file, and setting useLDAP back to 0.) - </para> - - <para>If using LDAP, you must set the - three additional parameters: Set LDAPserver to the name (and optionally - port) of your LDAP server. If no port is specified, it defaults to the - default port of 389. (e.g "ldap.mycompany.com" or - "ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching - for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids - must be unique under the DN specified here. Set LDAPmailattribute to - the name of the attribute in your LDAP directory which contains the - primary email address. On most directory servers available, this is - "mail", but you may need to change this. - </para> - - <para>You can also try using <ulink url="http://www.openldap.org/"> - OpenLDAP</ulink> with Bugzilla, using any of a number of administration - tools. You should apply the patch attached this bug: - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=158630"> - http://bugzilla.mozilla.org/show_bug.cgi?id=158630</ulink>, then set - the following object classes for your users: - - <orderedlist> - <listitem><para>objectClass: person</para></listitem> - <listitem><para>objectClass: organizationalPerson</para></listitem> - <listitem><para>objectClass: inetOrgPerson</para></listitem> - <listitem><para>objectClass: top</para></listitem> - <listitem><para>objectClass: posixAccount</para></listitem> - <listitem><para>objectClass: shadowAccount</para></listitem> - </orderedlist> - - Please note that this patch <emphasis>has not</emphasis> yet been - accepted by the Bugzilla team, and so you may need to do some - manual tweaking. That said, it looks like Net::LDAP is probably - the way to go in the future. - </para> - </section> - - <section id="content-type" - xreflabel="Preventing untrusted Bugzilla content from executing malicious Javascript code"> - - <title>Preventing untrusted Bugzilla content from executing malicious - Javascript code</title> - - <para>It is possible for a Bugzilla to execute malicious Javascript - code. Due to internationalization concerns, we are unable to - incorporate the code changes necessary to fulfill the CERT advisory - requirements mentioned in - <ulink - url="http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3"> - http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3</ulink>. - Executing the following code snippet from a UNIX command shell will - rectify the problem if your Bugzilla installation is intended for an - English-speaking audience. As always, be sure your Bugzilla - installation has a good backup before making changes, and I recommend - you understand what the script is doing before executing it.</para> - - <para> - <programlisting> -bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; charset=ISO-8859-1/i" *.cgi *.pl - </programlisting> - </para> - - <para>All this one-liner command does is search for all instances of - <quote>Content-type: text/html</quote> - - and replaces it with - <quote>Content-Type: text/html; charset=ISO-8859-1</quote> - - . This specification prevents possible Javascript attacks on the - browser, and is suggested for all English-speaking sites. For - non-English-speaking Bugzilla sites, I suggest changing - <quote>ISO-8859-1</quote>, above, to - <quote>UTF-8</quote>.</para> - - <note> - <para>Using <meta> tags to set the charset is not - recommended, as there's a bug in Netscape 4.x which causes pages - marked up in this way to load twice. See - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=126266">bug - 126266</ulink> for more information including progress toward making - bugzilla charset aware by default. - </para> - </note> - </section> - - <section id="directoryindex" xreflabel="Modifying the Apache - DirectoryIndex parameter to use index.cgi"> - <title> - <filename>directoryindex</filename> for the Bugzilla default page. - </title> - - <para>You should modify the <DirectoryIndex> parameter for - the Apache virtual host running your Bugzilla installation to - allow <filename>index.cgi</filename> as the index page for a - directory, as well as the usual <filename>index.html</filename>, - <filename>index.htm</filename>, and so forth. </para> - </section> - - <section id="mod_perl" xreflabel="Bugzilla and mod_perl"> - <title> - Bugzilla and <filename>mod_perl</filename> - </title> - <para>Bugzilla is unsupported under mod_perl. Effort is underway - to make it work cleanly in a mod_perl environment, but it is - slow going. - </para> - </section> - - <section id="mod-throttle" - xreflabel="Using mod_throttle to prevent Denial of Service attacks"> - <title> - <filename>mod_throttle</filename> - - and Security</title> - - <para>It is possible for a user, by mistake or on purpose, to access - the database many times in a row which can result in very slow access - speeds for other users. If your Bugzilla installation is experiencing - this problem , you may install the Apache module - <filename>mod_throttle</filename> - - which can limit connections by ip-address. You may download this module - at - <ulink url="http://www.snert.com/Software/Throttle/"> - http://www.snert.com/Software/Throttle/</ulink>. - Follow the instructions to install into your Apache install. - <emphasis>This module only functions with the Apache web - server!</emphasis> - You may use the - <command>ThrottleClientIP</command> - - command provided by this module to accomplish this goal. See the - <ulink url="http://www.snert.com/Software/Throttle/">Module - Instructions</ulink> - for more information.</para> - </section> - </section> - - <section id="os-specific"> - <title>OS Specific Installation Notes</title> - - <para>Many aspects of the Bugzilla installation can be affected by the - the operating system you choose to install it on. Sometimes it can be made - easier and others more difficult. This section will attempt to help you - understand both the difficulties of running on specific operating systems - and the utilities available to make it easier. - </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 still a very painful processes. - The Bugzilla Team is working to make it easier, but that goal is not - considered a top priority. If you wish to run Bugzilla, we still - recommend doing so on a Unix based system such as GNU/Linux. As of this - writing, all members of the Bugzilla team and all known large installations - run on Unix based systems. - </para> - - <para>If after hearing all that, you have enough pain tolerance to attempt - installing Bugzilla on Win32, here are some pointers. - <![%bz-devel;[ - Because this is a development version of the guide, these instructions - are subject to change without notice. In fact, the Bugzilla Team hopes - they do as we would like to have Bugzilla resonabally close to "out of - the box" compatibility by the 2.18 release. - ]]> - </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/">http://aspn.activestate.com/ASPN/Downloads/ActivePerl/</ulink>. - </para> - </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-package-list"/>. The main difference is that - windows uses <command>ppm</command> instead of CPAN. - </para> - - <programlisting> -C:\perl> <command>ppm <module name></command> - </programlisting> - - <note> - <para>The above syntax should work for all modules with the exception - of Template Toolkit. The <ulink - url="http://tt2.org/download.html#win32">Template Toolkit website</ulink> - suggests using the instructions on <ulink - url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>. - </para> - </note> - - <tip> - <para>A complete list of modules that can be installed using ppm can - be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus">http://www.activestate.com/PPMPackages/5.6plus</ulink>. - </para> - </tip> - </section> - - <section id="win32-code-changes"> - <title>Code changes required to run on win32</title> - - <para>Unfortunately, Bugzilla still doesn't run "out of the box" on - Windows. There is work in progress to make this easier, but until that - happens code will have to be modified. This section is an attempt to - list the required changes. It is an attempt to be all inclusive, but - there may be other changes required. If you find something is missing, - please file a bug in &bzg-bugs;. - </para> - - <section id="win32-code-checksetup"> - <title>Changes to <filename>checksetup.pl</filename></title> - - <para>In <filename>checksetup.pl</filename>, the line reading:</para> - - <programlisting> -my $mysql_binaries = `which mysql`; - </programlisting> - <para>to</para> - <programlisting> -my $mysql_binaries = "D:\\mysql\\bin\\mysql"; - </programlisting> - - <para>And you'll also need to change:</para> - - <programlisting> -my $webservergid = getgrnam($my_webservergroup) - </programlisting> - <para>to</para> - <programlisting> -my $webservergid = '8' - </programlisting> - </section> - - </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-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, if you don't do this, you'll have - to modify the first line of every script to contain your path to - perl instead of <filename>/usr/bin/perl</filename>. - </para> - </note> - - </section> - - </section> - - <section id="os-macosx"> - <title><productname>Mac OS X</productname></title> - - <!-- TODO: Clean me up... (Mac OS X) --> - <para>There are a lot of common libraries and utilities out there that - Apple did not include with Mac OS X, but which run perfectly well on it. - The GD library, which Bugzilla needs to do bug graphs, is one of - these.</para> - - <para>The easiest way to get a lot of these is with a program called - Fink, which is similar in nature to the CPAN installer, but installs - common GNU utilities. Fink is available from - <ulink url="http://sourceforge.net/projects/fink/"/>.</para> - - <para>Follow the instructions for setting up Fink. Once it's installed, - you'll want to run the following as root: - <command>fink install gd</command> - </para> - - <para>It will prompt you for a number of dependencies, type 'y' and hit - enter to install all of the dependencies. Then watch it work.</para> - - <para>To prevent creating conflicts with the software that Apple installs - by default, Fink creates its own directory tree at /sw where it installs - most of the software that it installs. This means your libraries and - headers for libgd will be at /sw/lib and /sw/include instead of /usr/lib - and /usr/local/include. Because of these changed locations for the - libraries, the Perl GD module will not install directly via CPAN, because it - looks for the specific paths instead of getting them from your - environment. But there's a way around that :-)</para> - - <para>Instead of typing - <quote>install GD</quote> - at the - <prompt>cpan></prompt> - prompt, type - <command>look GD</command>. - This should go through the motions of downloading the latest version of - the GD module, then it will open a shell and drop you into the build - directory. Apply <ulink url="../sgml/gd-makefile.patch">this patch</ulink> - to the Makefile.PL file (save the - patch into a file and use the command - <command>patch < patchfile</command>.) - </para> - - <para>Then, run these commands to finish the installation of the GD - module: - <simplelist> - <member> - <command>perl Makefile.PL</command> - </member> - - <member> - <command>make</command> - </member> - - <member> - <command>make test</command> - </member> - - <member> - <command>make install</command> - </member> - - <member>And don't forget to run - <command>exit</command> - - to get back to CPAN.</member> - </simplelist> - </para> - - </section> - - <section id="os-mandrake"> - <title>Linux-Mandrake 8.0</title> - - <para>Linux-Mandrake 8.0 includes every required and optional library - for Bugzilla. The easiest way to install them is by using the - <command>urpmi</command> utility. If you follow these commands, you - should have everything you need for Bugzilla, and - <command>./checksetup.pl</command> should not complain about any - missing libraries. You may already have some of these installed. - </para> - - <screen> -<prompt>bash#</prompt> <command>urpmi perl-mysql</command> -<prompt>bash#</prompt> <command>urpmi perl-chart</command> -<prompt>bash#</prompt> <command>urpmi perl-gd</command> -<prompt>bash#</prompt> <command>urpmi perl-MailTools</command> <co id="test-mailtools"/> -<prompt>bash#</prompt> <command>urpmi apache-modules</command> - </screen> - <calloutlist> - <callout arearefs="test-mailtools"> - <para>for Bugzilla e-mail integration</para> - </callout> - </calloutlist> - - </section> - - </section> - - <section id="http"> - <title>HTTP Server Configuration</title> - - <para>The Bugzilla Team recommends Apache when using Bugzilla, however, any web server - that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts - should be able to handle Bugzilla. No matter what web server you choose, but - especially if you choose something other than Apache, you should be sure to read - <xref linkend="security-access"/>. - </para> - - <para>The plan for this section is to eventually document the specifics of how to lock - down permissions on individual web servers. - </para> - - <section id="http-apache"> - <title>Apache <productname>httpd</productname></title> - - <para>As mentioned above, the Bugzilla Team recommends Apache for use - with Bugzilla. You will have to make sure that Apache is properly - configured to run the Bugzilla CGI scripts. You also need to make sure - that the <filename>.htaccess</filename> files created by - <command>./checksetup.pl</command> (shown in <xref linkend="http-apache-htaccess"/> - for the curious) are allowed to override Apache's normal access - permissions or else important password information may be exposed to the - Internet. - </para> - - <para>Many Apache installations are not configured to run scripts - anywhere but in the <filename class="directory">cgi-bin</filename> - directory; however, we recommend that Bugzilla not be installed in the - <filename class="directory">cgi-bin</filename>, otherwise the static - files such as images and <xref linkend="gloss-javascript"/> - will not work correctly. To allow scripts to run in the normal - web space, the following changes should be made to your - <filename>httpd.conf</filename> file. - </para> - - <para>To allow files with a .cgi extension to be run, make sure the - following line exists and is uncommented:</para> - <programlisting> -AddHandler cgi-script .cgi - </programlisting> - - <para>To allow <filename>.htaccess</filename> files to override - permissions and .cgi files to run in the Bugzilla directory, make sure - the following two lines are in a <computeroutput>Directory</computeroutput> - directive that applies to the Bugzilla directory on your system - (either the Bugzilla directory or one of its parents). - </para> - <programlisting> -Options +ExecCGI -AllowOverride Limit - </programlisting> - - <note> - <para>For more information on Apache and its directives, see the - glossary entry on <xref linkend="gloss-apache"/>. - </para> - </note> - - <example id="http-apache-htaccess"> - <title><filename>.htaccess</filename> files for Apache</title> - - <para><filename>$BUGZILLA_HOME/.htaccess</filename> - <programlisting><![CDATA[ -# don't allow people to retrieve non-cgi executable files or our private data -<FilesMatch ^(.*\.pl|.*localconfig.*|runtests.sh)$> - deny from all -</FilesMatch> -<FilesMatch ^(localconfig.js|localconfig.rdf)$> - allow from all -</FilesMatch> - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/data/.htaccess</filename> - <programlisting><![CDATA[ -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory; the only exception is duplicates.rdf, which is used by -# duplicates.xul and must be loadable over the web -deny from all -<Files duplicates.rdf> - allow from all -</Files> - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/data/webdot</filename> - <programlisting><![CDATA[ -# Restrict access to .dot files to the public webdot server at research.att.com -# if research.att.com ever changed their IP, or if you use a different -# webdot server, you'll need to edit this -<FilesMatch ^[0-9]+\.dot$> - Allow from 192.20.225.10 - Deny from all -</FilesMatch> - -# Allow access by a local copy of 'dot' to .png, .gif, .jpg, and -# .map files -<FilesMatch ^[0-9]+\.(png|gif|jpg|map)$> - Allow from all -</FilesMatch> - -# And no directory listings, either. -Deny from all - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/Bugzilla/.htaccess</filename> - <programlisting> -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all - </programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/template/.htaccess</filename> - <programlisting> -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all - </programlisting> - </para> - - </example> - - </section> - - <section id="http-iis"> - <title>Microsoft <productname>Internet Information Services</productname></title> - - <para>If you need, or for some reason even want, to use Microsoft's - <productname>Internet Information Services</productname> or - <productname>Personal Web Server</productname> you should be able - to. You will need to configure them to know how to run CGI scripts, - however. This is described in Microsoft Knowledge Base article - <ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225 </ulink> - for <productname>Internet Information Services</productname> and - <ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink> - for <productname>Personal Web Server</productname>. - </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-access"/>. - </para> - - </section> - - <section id="http-aol"> - <title>AOL Server</title> - - <para>Ben FrantzDale reported success using AOL Server with Bugzilla. He - reported his experience and what appears below is based on that. - </para> - - <para>AOL Server will have to be configured to run - <glossterm linkend="gloss-cgi">CGI</glossterm> scripts, please consult - the documentation that came with your server for more information on - how to do this. - </para> - - <para>Because AOL Server doesn't support <filename>.htaccess</filename> - files, you'll have to create a <glossterm linkend="gloss-tcl">TCL</glossterm> - script. You should create an <filename>aolserver/modules/tcl/filter.tcl</filename> - file (the filename shouldn't matter) with the following contents (change - <computeroutput>/bugzilla/</computeroutput> to the web-based path to - your Bugzilla installation): - </para> - - <programlisting> -ns_register_filter preauth GET /bugzilla/localconfig filter_deny -ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny -ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny -ns_register_filter preauth GET /bugzilla/*.pl filter_deny -ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny -ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny -ns_register_filter preauth GET /bugzilla/data/* filter_deny -ns_register_filter preauth GET /bugzilla/template/* filter_deny - -proc filter_deny { why } { - ns_log Notice "filter_deny" - return "filter_return" -} - </programlisting> - - <warning> - <para>This probably doesn't account for all possible editor backup - files so you may wish to add some additional variations of - <filename>localconfig</filename>. 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>. - </para> - </warning> - - <note> - <para>If you are using webdot from research.att.com (the default - configuration for the <option>webdotbase</option> paramater), you - will need to allow access to <filename>data/webdot/*.dot</filename> - for the reasearch.att.com machine. - </para> - <para>If you are using a local installation of <ulink - url="http://www.graphviz.org">GraphViz</ulink>, you will need to allow - everybody to access <filename>*.png</filename>, - <filename>*.gif</filename>, <filename>*.jpg</filename>, and - <filename>*.map</filename> in the - <filename class="directory">data/webdot</filename> directory. - </para> - </note> - </section> - </section> - - <section id="troubleshooting"> - <title>Troubleshooting</title> - - <para>This section gives solutions to common Bugzilla installation - problems. - </para> - - <section> - <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title> - - <para> - Try executing <command>perl -MCPAN -e 'install CPAN'</command> - and then continuing. - </para> - - <para> - Certain older versions of the CPAN toolset were somewhat naive about how - to upgrade Perl modules. When a couple of modules got rolled into the core - Perl distribution for 5.6.1, CPAN thought that the best way to get those - modules up to date was to haul down the Perl distribution itself and - build it. Needless to say, this has caused headaches for just about - everybody. Upgrading to a newer version of CPAN with the - commandline above should fix things. - </para> - </section> - - - <section> - <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> - by - </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 - <quote>drwx------</quote>. Type - <command>chmod 755 - <filename>/var/spool/mqueue</filename> - </command> - as root to fix this problem. - </para> - </section> - - <section id="trouble-filetemp"> - <title>Your vendor has not defined Fcntl macro O_NOINHERIT</title> - - <para>This is caused by a bug in the version of - <productname>File::Temp</productname> that is distributed with perl - 5.6.0. Many minor variations of this error have been reported. Examples - can be found in <xref linkend="trouble-filetemp-errors"/>. - </para> - - <figure id="trouble-filetemp-errors"> - <title>Other File::Temp error messages</title> - - <programlisting> -Your vendor has not defined Fcntl macro O_NOINHERIT, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208. - -Your vendor has not defined Fcntl macro O_EXLOCK, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210. - -Your vendor has not defined Fcntl macro O_TEMPORARY, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. - </programlisting> - </figure> - - <para>Numerous people have reported that upgrading to version 5.6.1 - or higher solved the problem for them. A less involved fix is to apply - the patch in <xref linkend="trouble-filetemp-patch"/>. The patch is also - available as a <ulink url="../sgml/filetemp.patch">patch file</ulink>. - </para> - - <figure id="trouble-filetemp-patch"> - <title>Patch for File::Temp in Perl 5.6.0</title> - - <programlisting><![CDATA[ ---- File/Temp.pm.orig Thu Feb 6 16:26:00 2003 -+++ File/Temp.pm Thu Feb 6 16:26:23 2003 -@@ -205,6 +205,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; -@@ -226,6 +227,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; - ]]></programlisting> - </figure> - </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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/integration.sgml b/docs/sgml/integration.sgml deleted file mode 100644 index 1b0489fd9..000000000 --- a/docs/sgml/integration.sgml +++ /dev/null @@ -1,101 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > --> -<!-- Keep these tools listings in alphabetical order please. -MPB --> -<section id="integration"> - <title>Integrating Bugzilla with Third-Party Tools</title> - - <section id="bonsai" - xreflabel="Bonsai, the Mozilla automated CVS management system"> - <title>Bonsai</title> - - <para>Bonsai is a web-based tool for managing - <xref linkend="cvs" /> - - . Using Bonsai, administrators can control open/closed status of trees, - query a fast relational database back-end for change, branch, and comment - information, and view changes made since the last time the tree was - closed. Bonsai - also integrates with - <xref linkend="tinderbox" />. - </para> - </section> - - <section id="cvs" xreflabel="CVS, the Concurrent Versioning System"> - <title>CVS</title> - - <para>CVS integration is best accomplished, at this point, using the - Bugzilla Email Gateway.</para> - - <para>Follow the instructions in this Guide for enabling Bugzilla e-mail - integration. Ensure that your check-in script sends an email to your - Bugzilla e-mail gateway with the subject of - <quote>[Bug XXXX]</quote>, - and you can have CVS check-in comments append to your Bugzilla bug. If - you want to have the bug be closed automatically, you'll have to modify - the <filename>contrib/bugzilla_email_append.pl</filename> script. - </para> - - <para>There is also a CVSZilla project, based upon somewhat dated - Bugzilla code, to integrate CVS and Bugzilla through CVS' ability to - email. Check it out at: - <ulink url="http://homepages.kcbbs.gen.nz/~tonyg/"> - http://homepages.kcbbs.gen.nz/~tonyg/</ulink>. - </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/"> - http://www.ravenbrook.com/project/p4dti</ulink> - - . - <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"> - http://public.perforce.com/public/perforce/p4dti/index.html</ulink> - - .</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="tinderbox" - xreflabel="Tinderbox, the Mozilla automated build management system"> - <title>Tinderbox/Tinderbox2</title> - - <para>We need Tinderbox integration information.</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/introduction.sgml b/docs/sgml/introduction.sgml deleted file mode 100644 index 33907552b..000000000 --- a/docs/sgml/introduction.sgml +++ /dev/null @@ -1,149 +0,0 @@ -<chapter id="introduction"> - <title>Introduction</title> - - <section id="whatis"> - <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 product. - Bugzilla was originally - written by Terry Weissman in a programming language called TCL, to - replace a rudimentary bug-tracking database used internally by Netscape - Communications. Terry later ported Bugzilla to Perl from TCL, and in Perl - it remains to this day. Most commercial defect-tracking software vendors - at the time charged enormous licensing fees, and Bugzilla quickly became - a favorite of the open-source crowd (with its genesis in the open-source - browser project, Mozilla). It is now the de-facto standard - defect-tracking system against which all others are measured. - </para> - - <para>Bugzilla boasts many advanced features. These include: - <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>Web, XML, email and console interfaces</para> - </listitem> - - <listitem> - <para>Completely customisable and/or localisable web user - interface</para> - </listitem> - - <listitem> - <para>Extensive configurability</para> - </listitem> - - <listitem> - <para>Smooth upgrade pathway between versions</para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="why"> - <title>Why Should We Use Bugzilla?</title> - - <para>For many years, defect-tracking software has remained principally - the domain of large software development houses. Even then, most shops - never bothered with bug-tracking software, and instead simply relied on - shared lists and email to monitor the status of defects. This procedure - is error-prone and tends to cause those bugs judged least significant by - developers to be dropped or ignored.</para> - - <para>These days, many companies are finding that integrated - defect-tracking systems reduce downtime, increase productivity, and raise - customer satisfaction with their systems. Along with full disclosure, an - open bug-tracker allows manufacturers to keep in touch with their clients - and resellers, to communicate about problems effectively throughout the - data management chain. Many corporations have also discovered that - defect-tracking helps reduce costs by providing IT support - accountability, telephone support knowledge bases, and a common, - well-understood system for accounting for unusual system or software - issues.</para> - - <para>But why should - <emphasis>you</emphasis> - - use Bugzilla?</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 solution to configuration management and - replication problems.</para> - - <para>Bugzilla can dramatically increase the productivity and - accountability of individual employees by providing a documented workflow - and positive feedback for good performance. How many times do you wake up - in the morning, remembering that you were supposed to do - <emphasis>something</emphasis> - today, but you just can't quite remember? Put it in Bugzilla, and you - have a record of it from which you can extrapolate milestones, predict - product versions for integration, and follow the discussion trail - that led to critical decisions.</para> - - <para>Ultimately, Bugzilla puts the power in your hands to improve your - value to your employer or business while providing a usable framework for - your natural attention to detail and knowledge store to flourish.</para> - </section> -</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> diff --git a/docs/sgml/patches.sgml b/docs/sgml/patches.sgml deleted file mode 100644 index 43f816758..000000000 --- a/docs/sgml/patches.sgml +++ /dev/null @@ -1,113 +0,0 @@ -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla"> - <title>Useful Patches and Utilities for Bugzilla</title> - - <para>Are you looking for a way to put your Bugzilla into overdrive? Catch - some of the niftiest tricks here in this section.</para> - - <section id="rewrite" xreflabel="Apache mod_rewrite magic"> - <title>Apache - <filename>mod_rewrite</filename> - - magic</title> - - <para>Apache's - <filename>mod_rewrite</filename> - - module lets you do some truly amazing things with URL rewriting. Here are - a couple of examples of what you can do.</para> - - <orderedlist> - <listitem> - <para>Make it so if someone types - <computeroutput>http://www.foo.com/12345</computeroutput> - - , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try - setting up your VirtualHost section for Bugzilla with a rule like - this:</para> - - <programlisting><![CDATA[ -<VirtualHost 12.34.56.78> -RewriteEngine On -RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R] -</VirtualHost> -]]></programlisting> - </listitem> - - <listitem> - <para>There are many, many more things you can do with mod_rewrite. - Please refer to the mod_rewrite documentation at - <ulink url="http://www.apache.org">http://www.apache.org</ulink>. - </para> - </listitem> - </orderedlist> - </section> - - <section id="cmdline"> - <title>Command-line Bugzilla Queries</title> - - <para>There are a suite of Unix utilities for querying Bugzilla from the - command line. They live in the - <filename class="directory">contrib/cmdline</filename> - directory. However, they - have not yet been updated to work with 2.16 (post-templatisation.). - There are three files - <filename>query.conf</filename>, - <filename>buglist</filename> and <filename>bugs</filename>.</para> - - <para><filename>query.conf</filename> - contains the mapping from options to field - names and comparison types. Quoted option names are "grepped" for, so it - should be easy to edit this file. Comments (#) have no effect; you must - make sure these lines do not contain any quoted "option".</para> - - <para><filename>buglist</filename> - is a shell script which submits a Bugzilla query and writes - the resulting HTML page to stdout. It supports both short options, (such - as "-Afoo" or "-Rbar") and long options (such as "--assignedto=foo" or - "--reporter=bar"). If the first character of an option is not "-", it is - treated as if it were prefixed with "--default=".</para> - - <para>The column list is taken from the COLUMNLIST environment variable. - This is equivalent to the "Change Columns" option when you list bugs in - buglist.cgi. If you have already used Bugzilla, grep for COLUMNLIST - in your cookies file to see your current COLUMNLIST setting.</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 - "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list into - a working link if any bugs are found. Counting bugs is easy. Pipe the - results through - <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> - -</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/requiredsoftware.sgml b/docs/sgml/requiredsoftware.sgml deleted file mode 100644 index f32f0dc2f..000000000 --- a/docs/sgml/requiredsoftware.sgml +++ /dev/null @@ -1,88 +0,0 @@ -<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<appendix id="downloadlinks"> - <title>Software Download Links</title> - - <para>All of these sites are current as of April, 2001. Hopefully they'll - stay current for a while.</para> - - <para>Apache Web Server: - <ulink url="http://www.apache.org/">http://www.apache.org</ulink> - - Optional web server for Bugzilla, but recommended because of broad user - base and support.</para> - - <para>Bugzilla: - <ulink url="http://www.bugzilla.org/"> - http://www.bugzilla.org/</ulink> - </para> - - <para>MySQL: - <ulink url="http://www.mysql.com/">http://www.mysql.com/</ulink> - </para> - - <para>Perl: - <ulink url="http://www.perl.org">http://www.perl.org/</ulink> - </para> - - <para>CPAN: - <ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink> - </para> - - <para>DBI Perl module: - <ulink url="http://www.cpan.org/modules/by-module/DBI/"> - http://www.cpan.org/modules/by-module/DBI/</ulink> - </para> - - <para>Data::Dumper module: - <ulink url="http://www.cpan.org/modules/by-module/Data/"> - http://www.cpan.org/modules/by-module/Data/</ulink> - </para> - - <para>MySQL related Perl modules: - <ulink url="http://www.cpan.org/modules/by-module/Mysql/"> - http://www.cpan.org/modules/by-module/Mysql/</ulink> - </para> - - <para>TimeDate Perl module collection: - <ulink url="http://www.cpan.org/modules/by-module/Date/"> - http://www.cpan.org/modules/by-module/Date/</ulink> - </para> - - <para>GD Perl module: - <ulink url="http://www.cpan.org/modules/by-module/GD/"> - http://www.cpan.org/modules/by-module/GD/</ulink> - - Alternately, you should be able to find the latest version of GD at - <ulink url="http://www.boutell.com/gd/">http://www.boutell.com/gd/</ulink> - </para> - - <para>Chart::Base module: - <ulink url="http://www.cpan.org/modules/by-module/Chart/"> - http://www.cpan.org/modules/by-module/Chart/</ulink> - </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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/using.sgml b/docs/sgml/using.sgml deleted file mode 100644 index a3986c27d..000000000 --- a/docs/sgml/using.sgml +++ /dev/null @@ -1,580 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> - -<chapter id="using"> - <title>Using Bugzilla</title> - - <section id="how"> - <title>How do I use Bugzilla?</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, it does not necessarily - have all Bugzilla features enabled, and often runs cutting-edge versions - of Bugzilla for testing, so some things may work slightly differently - than mentioned here.</para> - - <section id="myaccount"> - <title>Create a Bugzilla Account</title> - - <para>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="http://landfill.bugzilla.org/bugzilla-tip/"> - http://landfill.bugzilla.org/bugzilla-tip/</ulink> - </para> - - <orderedlist> - <listitem> - <para>Click the - <quote>Open a new Bugzilla account</quote> - - link, enter your email address and, optionally, your name in the - spaces provided, then click - <quote>Create Account</quote> - - .</para> - </listitem> - - <listitem> - <para>Within moments, you should receive an email to the address - you provided above, which contains your login name (generally the - same as the email address), and a password you can use to access - your account. This password is randomly generated, and can be - changed to something more memorable.</para> - </listitem> - - <listitem> - <para>Click the - <quote>Log In</quote> - link in the yellow area at the bottom of the page in your browser, - enter your email address and password into the spaces provided, and - click - <quote>Login</quote>. - </para> - - </listitem> - </orderedlist> - - <para>You are now logged in. Bugzilla uses cookies for authentication - so, unless your IP address changes, you should not have to log in - again.</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="http://landfill.bugzilla.org/bugzilla-tip/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>*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 prioritise 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>Attachments:</emphasis> - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section.</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="query"> - <title>Searching for Bugs</title> - - <para>The Bugzilla Search page is is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - <ulink url="http://landfill.bugzilla.org/bugzilla-tip/query.cgi"> - landfill.bugzilla.org/bugzilla-tip/query.cgi</ulink> - - .</para> - - <para>The Search page has controls for selecting different possible - values for all of the fields in a bug, as described above. Once you've - defined a search, you can either run it, or save it as a Remembered - Query, which can optionally appear in the footer of your pages.</para> - - <para>Highly advanced querying is done using Boolean Charts, which have - their own - <ulink - url="http://landfill.bugzilla.org/bugzilla-tip/booleanchart.html"> - context-sensitive help</ulink> - - .</para> - </section> - - <section id="list"> - <title>Bug Lists</title> - - <para>If you run a search, a list of matching bugs will be returned. - The default search is to return all open bugs on the system - don't try - running this search on a Bugzilla installation with a lot of - bugs!</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>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, you can make the same - change to all the bugs in the list - for example, changing their - owner.</member> - - <member> - <emphasis>Send mail to bug owners:</emphasis> - - Sends mail to the owners of all bugs on the list.</member> - - <member> - <emphasis>Edit this query:</emphasis> - - If you didn't get exactly the results you were looking for, you can - return to the Query page through this link and make small revisions - to the query you just made so you get more accurate results.</member> - </simplelist> - </para> - </section> - - <section id="bugreports"> - <title>Filing Bugs</title> - - <para>Years of bug writing experience has been distilled for your - reading pleasure into the - <ulink - url="http://landfill.bugzilla.org/bugzilla-tip/bugwritinghelp.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 test bug is as follows:</para> - - <orderedlist> - <listitem> - <para>Go to - <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"> - Landfill</ulink> - in your browser and click - <ulink - url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi"> - Enter a new bug report</ulink>. - </para> - </listitem> - - <listitem> - <para>Select a product - any one will do.</para> - </listitem> - - <listitem> - <para>Fill in the fields. Bugzilla should have made reasonable - guesses, based upon your browser, for the "Platform" and "OS" - drop-down boxes. If they are wrong, change them.</para> - </listitem> - - <listitem> - <para>Select "Commit" and send in your bug report.</para> - </listitem> - </orderedlist> - </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 posting HTML will result - in literal HTML tags rather than being interpreted by a browser. - 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 - <ulink url="http://www.bugzilla.org">http://www.bugzilla.org</ulink>. - Other strings which get linkified in the obvious manner are: - <simplelist> - <member>bug 12345</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="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 - "<filename>foo|bar</filename>" - into Quicksearch would search for "foo" or "bar" in the - summary and status whiteboard of a bug; adding - "<filename>:BazProduct</filename>" would - search only in that product. - </para> - - <para>You'll find the Quicksearch box on Bugzilla's - front page, along with a - <ulink url="../../quicksearch.html">Help</ulink> - link which details how to use it.</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, - particularly if you do it out of habit, but full mail/news-style - four line ASCII art creations are not. - </para> - </section> - - <section id="attachments"> - <title>Attachments</title> - - <para> - 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>Trim screenshots. There's no need to show the whole screen if - you are pointing out a single-pixel problem. - </para> - - <para>Don't attach simple test cases (e.g. one HTML file, one - CSS file and an image) as a ZIP file. Instead, upload them in - reverse order and edit the referring file so that they point to the - attached files. This way, the test case works immediately - out of the bug. - </para> - </section> - - <section> - <title>Filing Bugs</title> - - <para>Try to make sure that everything said in the summary is also - said in the first comment. Summaries are often updated and this will - ensure your original information is easily accessible. - </para> - - <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> - - <section id="userpreferences"> - <title>User Preferences</title> - - <para>Once you have logged in, you can customise various aspects of - Bugzilla via the "Edit prefs" link in the page footer. - The preferences are split into four tabs:</para> - - <section id="accountsettings" xreflabel="Account Settings"> - <title>Account Settings</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="emailsettings"> - <title>Email Settings</title> - - <para>On this tab you can reduce or increase the amount of email sent - you from Bugzilla, opting in our out depending on your relationship to - the bug and the change that was made to it. (Note that you can also do - client-side filtering using the X-Bugzilla-Reason header which Bugzilla - adds to all bugmail.)</para> - - <para>By entering user email names, delineated by commas, into the - "Users to watch" text entry box you can receive a copy of all the - bugmail of other users (security settings permitting.) This powerful - functionality enables seamless transitions as developers change - projects or users go on holiday.</para> - - <note> - <para>The ability to watch other users may not be available in all - Bugzilla installations. If you can't see it, ask your - administrator.</para> - </note> - </section> - - <section id="footersettings"> - <title>Page Footer</title> - - <para>On the Search page, you can store queries in Bugzilla, so if you - regularly run a particular query it is just a drop-down menu away. - Once you have a stored query, you can come - here to request that it also be displayed in your page footer.</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 - what product groups you - are in, and whether you can edit bugs or perform various administration - functions.</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - diff --git a/docs/sgml/variants.sgml b/docs/sgml/variants.sgml deleted file mode 100644 index 3a7fd6743..000000000 --- a/docs/sgml/variants.sgml +++ /dev/null @@ -1,123 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">--> -<appendix id="variants" xreflabel="Bugzilla Variants and Competitors"> - <title>Bugzilla Variants and Competitors</title> - - <para>I created this section to answer questions about Bugzilla competitors - and variants, then found a wonderful site which covers an awful lot of what - I wanted to discuss. Rather than quote it in its entirety, I'll simply - refer you here: - <ulink url="http://linas.org/linux/pm.html"> - http://linas.org/linux/pm.html</ulink> - </para> - - <section id="variant-redhat"> - <title>Red Hat Bugzilla</title> - - <para>Red Hat's old fork of Bugzilla which was based on version 2.8 is now - obsolete. The newest version in use is based on version 2.17.1 and is in - the process of being integrated into the main Bugzilla source tree. The - back-end is modified to work with PostgreSQL instead of MySQL and they have - custom templates to get their desired look and feel, but other than that it - is Bugzilla 2.17.1. Dave Lawrence of Red Hat put forth a great deal of - effort to make sure that the changes he made could be integrated back into - the main tree. - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=98304">Bug - 98304</ulink> exists to track this integration. - </para> - - <para>URL: - <ulink url="http://bugzilla.redhat.com/bugzilla/"> - http://bugzilla.redhat.com/bugzilla/</ulink> - </para> - - <para>This section last updated 24 Dec 2002</para> - </section> - - <section id="variant-fenris"> - <title>Loki Bugzilla (Fenris)</title> - - <para>Fenris was a fork from Bugzilla made by Loki Games; when - Loki went into receivership, it died. While Loki's other code lives on, - its custodians recommend Bugzilla for future bug-tracker deployments. - </para> - - <para>This section last updated 27 Jul 2002</para> - </section> - - <section id="variant-issuezilla"> - <title>Issuezilla</title> - - <para>Issuezilla was another fork from Bugzilla, made by collab.net and - hosted at tigris.org. It is also dead; the primary focus of bug-tracking - at tigris.org is their Java-based bug-tracker, - <xref linkend="variant-scarab"/>.</para> - - <para>This section last updated 27 Jul 2002</para> - </section> - - <section id="variant-scarab"> - <title>Scarab</title> - - <para>Scarab is a new open source bug-tracking system built using Java - Servlet technology. It is currently at version 1.0 beta 13.</para> - - <para>URL: - <ulink url="http://scarab.tigris.org/">http://scarab.tigris.org</ulink> - </para> - - <para>This section last updated 18 Jan 2003</para> - </section> - - <section id="variant-perforce"> - <title>Perforce SCM</title> - - <para>Although Perforce isn't really a bug tracker, it can be used as - such through the <quote>jobs</quote> - functionality.</para> - - <para>URL: - <ulink url="http://www.perforce.com/perforce/technotes/note052.html"> - http://www.perforce.com/perforce/technotes/note052.html - </ulink> - </para> - - <para>This section last updated 27 Jul 2002</para> - </section> - - <section id="variant-sourceforge"> - <title>SourceForge</title> - - <para>SourceForge is a way of coordinating geographically - distributed free software and open source projects over the Internet. - It has a built-in bug tracker, but it's not highly thought of.</para> - - <para>URL: - <ulink url="http://www.sourceforge.net"> - http://www.sourceforge.net</ulink> - </para> - - <para>This section last updated 27 Jul 2002</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.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - |