From 4105a4885d093295c71dd5d08e160b3e6cc7ee0f Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Fri, 17 Jan 2014 10:15:14 +0000 Subject: Bug 912064 - convert docs to ReStructured Text (.rst) format. r,a=justdave. --- docs/TODO | 12 + docs/bugzilla.ent.tmpl | 7 - docs/definitions.rst.tmpl | 3 + docs/en/Makefile | 153 ++ docs/en/README.docs | 42 - docs/en/historical_rel_notes.txt | 3028 +++++++++++++++++++++++++++++++++++ docs/en/images/callouts/1.gif | Bin 890 -> 0 bytes docs/en/images/callouts/2.gif | Bin 907 -> 0 bytes docs/en/images/callouts/3.gif | Bin 914 -> 0 bytes docs/en/images/caution.gif | Bin 134 -> 0 bytes docs/en/images/note.gif | Bin 226 -> 0 bytes docs/en/images/tip.gif | Bin 1229 -> 0 bytes docs/en/images/warning.gif | Bin 140 -> 0 bytes docs/en/make.bat | 190 +++ docs/en/rel_notes.txt | 3028 ----------------------------------- docs/en/rst/_static/stuff.css | 3 + docs/en/rst/about.rst | 184 +++ docs/en/rst/administration.rst | 2149 +++++++++++++++++++++++++ docs/en/rst/conf.py | 246 +++ docs/en/rst/customization.rst | 481 ++++++ docs/en/rst/gfdl.rst | 408 +++++ docs/en/rst/glossary.rst | 325 ++++ docs/en/rst/index.rst | 32 + docs/en/rst/installation.rst | 1870 ++++++++++++++++++++++ docs/en/rst/modules.rst | 158 ++ docs/en/rst/patches.rst | 88 ++ docs/en/rst/security.rst | 167 ++ docs/en/rst/troubleshooting.rst | 235 +++ docs/en/rst/using.rst | 1375 ++++++++++++++++ docs/en/xml/Bugzilla-Guide.xml | 135 -- docs/en/xml/about.xml | 225 --- docs/en/xml/administration.xml | 3244 -------------------------------------- docs/en/xml/conventions.xml | 91 -- docs/en/xml/customization.xml | 612 ------- docs/en/xml/gfdl.xml | 457 ------ docs/en/xml/glossary.xml | 561 ------- docs/en/xml/index.xml | 27 - docs/en/xml/installation.xml | 2453 ---------------------------- docs/en/xml/modules.xml | 187 --- docs/en/xml/patches.xml | 143 -- docs/en/xml/security.xml | 281 ---- docs/en/xml/troubleshooting.xml | 287 ---- docs/en/xml/using.xml | 2087 ------------------------ docs/makedocs.pl | 83 +- docs/style.css | 4 +- docs/xsl/bugzilla-docs.xsl | 36 - docs/xsl/chunks.xsl | 19 - docs/xsl/nochunks.xsl | 16 - docs/xsl/pdf.xsl | 42 - 49 files changed, 11149 insertions(+), 14025 deletions(-) create mode 100644 docs/TODO delete mode 100644 docs/bugzilla.ent.tmpl create mode 100644 docs/definitions.rst.tmpl create mode 100644 docs/en/Makefile delete mode 100644 docs/en/README.docs create mode 100644 docs/en/historical_rel_notes.txt delete mode 100644 docs/en/images/callouts/1.gif delete mode 100644 docs/en/images/callouts/2.gif delete mode 100644 docs/en/images/callouts/3.gif delete mode 100644 docs/en/images/caution.gif delete mode 100644 docs/en/images/note.gif delete mode 100644 docs/en/images/tip.gif delete mode 100644 docs/en/images/warning.gif create mode 100644 docs/en/make.bat delete mode 100644 docs/en/rel_notes.txt create mode 100644 docs/en/rst/_static/stuff.css create mode 100644 docs/en/rst/about.rst create mode 100644 docs/en/rst/administration.rst create mode 100644 docs/en/rst/conf.py create mode 100644 docs/en/rst/customization.rst create mode 100644 docs/en/rst/gfdl.rst create mode 100644 docs/en/rst/glossary.rst create mode 100644 docs/en/rst/index.rst create mode 100644 docs/en/rst/installation.rst create mode 100644 docs/en/rst/modules.rst create mode 100644 docs/en/rst/patches.rst create mode 100644 docs/en/rst/security.rst create mode 100644 docs/en/rst/troubleshooting.rst create mode 100644 docs/en/rst/using.rst delete mode 100644 docs/en/xml/Bugzilla-Guide.xml delete mode 100644 docs/en/xml/about.xml delete mode 100644 docs/en/xml/administration.xml delete mode 100644 docs/en/xml/conventions.xml delete mode 100644 docs/en/xml/customization.xml delete mode 100644 docs/en/xml/gfdl.xml delete mode 100644 docs/en/xml/glossary.xml delete mode 100644 docs/en/xml/index.xml delete mode 100644 docs/en/xml/installation.xml delete mode 100644 docs/en/xml/modules.xml delete mode 100644 docs/en/xml/patches.xml delete mode 100644 docs/en/xml/security.xml delete mode 100644 docs/en/xml/troubleshooting.xml delete mode 100644 docs/en/xml/using.xml delete mode 100644 docs/xsl/bugzilla-docs.xsl delete mode 100644 docs/xsl/chunks.xsl delete mode 100644 docs/xsl/nochunks.xsl delete mode 100644 docs/xsl/pdf.xsl (limited to 'docs') diff --git a/docs/TODO b/docs/TODO new file mode 100644 index 000000000..4e4afd14f --- /dev/null +++ b/docs/TODO @@ -0,0 +1,12 @@ +RST files: + +* Produce simple style guide and canonicalise usages to follow it +* Get rid of, or use proper Sphinx markup for, glossary + +HTML Output: + +* Styling for Cautions and Tips +* Stop replacement of "--" with em-dash +* Auto-highlighter thinks # in "bash#" is a comment char +* Style definition lists to have the term in bold +* Fix bug lifecycle image original doc link diff --git a/docs/bugzilla.ent.tmpl b/docs/bugzilla.ent.tmpl deleted file mode 100644 index c1076aed8..000000000 --- a/docs/bugzilla.ent.tmpl +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/docs/definitions.rst.tmpl b/docs/definitions.rst.tmpl new file mode 100644 index 000000000..4e6a7288c --- /dev/null +++ b/docs/definitions.rst.tmpl @@ -0,0 +1,3 @@ +.. |min-perl-ver| replace:: 5.10.1 +.. |landfillbase| replace:: http://landfill.bugzilla.org/bugzilla-tip/ +.. |bzg-bugs| replace:: http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation diff --git a/docs/en/Makefile b/docs/en/Makefile new file mode 100644 index 000000000..afbe6ee26 --- /dev/null +++ b/docs/en/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = . + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) rst +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) rst + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Bugzilla.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Bugzilla.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Bugzilla" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Bugzilla" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/txt + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/txt." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/en/README.docs b/docs/en/README.docs deleted file mode 100644 index f041ef044..000000000 --- a/docs/en/README.docs +++ /dev/null @@ -1,42 +0,0 @@ -Welcome to the Bugzilla documentation project! -You'll find these directories and files here: - -README.docs # This README file -html/ # The compiled HTML docs from XML sources (do not edit) -txt/ # The compiled text docs from XML sources (do not edit) -pdf/ # The compiled PDF docs from XML sources (do not edit) -xml/ # The original XML doc sources (edit these) - -A note about the XML: - The documentation is written in DocBook 4.2, and attempts to adhere -to the LinuxDoc standards where applicable (http://www.tldp.org). -If you need to edit the documentation, feel free to use any text editor -to make the changes. XML is not rocket science -- simply make sure your -text appears between appropriate tags (like This is a paragraph) -and we'll be fine. If you are making more extensive changes, please ensure -you at least validate your XML before checking it in by running makedocs.pl. - - Thanks for taking the time to read these notes and consulting the -documentation. Please address comments and questions to the newsgroup: -news://news.mozilla.org/mozilla.support.bugzilla. - -========== -HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT: -========== - -All you need to compile the documentation are the xmlto and dblatex -scripts. All major Linux distributions have these packages and so -it's very easy to install them. If these packages are correctly configured, -all required dependencies such as xsltproc and pdftex will be installed -at the same time, and so you don't have to worry about them. - -Once these applications are installed, all you need to do to compile -the documentation is to run either: - - makedocs.pl - -to compile the documentation in HTML and text formats only, or: - - makedocs.pl --with-pdf - -to also compile the documentation in PDF format. diff --git a/docs/en/historical_rel_notes.txt b/docs/en/historical_rel_notes.txt new file mode 100644 index 000000000..4014951f0 --- /dev/null +++ b/docs/en/historical_rel_notes.txt @@ -0,0 +1,3028 @@ +Release Notes for Bugzilla version 3.0 and higher are available in HTML +format, either on the bugzilla.org website, or in your current installation, +linked from the index page. + +bugzilla.org links for release notes +------------------------------------ +3.0.2: http://www.bugzilla.org/releases/3.0.2/release-notes.html + +*************************************** +*** The Bugzilla 2.22 Release Notes *** +*************************************** + +Table of Contents +***************** + +- Introduction +- Important Updates In This Point Release +- Minimum Requirements + * Perl + * For MySQL Users + * For PostgreSQL Users + * Required Perl Modules + * Optional Perl Modules +- What's New? + * Complete PostgreSQL Support + * Parameters In Sections + * One Codebase, Multiple Databases + * UTF-8 for New Installations + * Admins Can Impersonate Users + * Bug Import and Moving Improvements + * Adding Individual Bugs to Saved Searches + * Attach URLs + * Optional "Strict Isolation" for Groups + * "editcomponents" Change + * "shutdownhtml" Change + * Miscellaneous Improvements + * All Changes +- Deprecated Features +- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) +- How to Upgrade From An Older Bugzilla + * Steps for Upgrading +- Code Changes Which May Affect Customizations + * CGI.pl is Gone + * Other Changes +- Security Fixes In 2.22 Releases +- Release Notes for Previous Versions + +Introduction +************ +Bugzilla 2.22 is one of our most polished releases. We did a lot of +small cleanups to make Bugzilla easier to use and more useful in +many, many small ways, in addition to adding some major new features. + +This document contains the release notes for Bugzilla 2.22. +In this document, recently added, changed, and removed features +of Bugzilla are described. If you are upgrading from an older version, +you will definitely want to read these release notes in detail, so that +you have an idea of what has changed. + +If you are upgrading from a version before 2.20, also read the 2.20 +release notes (lower in this file) and any previous release notes. + +If you are installing a new Bugzilla, you will still want to look over +the release notes to see if there is any particularly important +information that affects your installation. + +If you would like to contribute code to Bugzilla, read our +Contributor's Guide at: + +http://www.bugzilla.org/docs/contributor.html + + +Important Updates In This Point Release +*************************************** + +This section describes bugs fixed in releases after the original 2.22 +release. + +Version 2.22.2 +-------------- + ++ Make Bugzilla compatible with Template Toolkit 2.15 (bug 357374) + ++ Make Bugzilla compatible with versions of MySQL higher than 5.0.25 + (bug 321645) + ++ Sanity Check can now only be run by people with the "admin" privilege. + (bug 91761) + +Version 2.22.1 +-------------- + ++ When sending mail, Bugzilla could throw the error "Insecure dependency in + exec while running with -T switch" (bug 340538). + ++ Using the public webdot server (for dependency graphs) should work + again (bug 351243). + ++ The "I'm added to or removed from this capacity" email preference + wasn't working for new bugs (bug 349852). + ++ The original release of 2.22 incorrectly said it required Template-Toolkit + version 2.08. In actual fact, Bugzilla requires version 2.10 (bug 351478). + ++ votes.cgi would crash if your bug was the one confirming a bug (bug 351300). + ++ checksetup.pl now correctly reports if your Template::Plugin::GD module + is missing. If missing, it could lead to charts and graphs not working + (bug 345389). + ++ The "Keyword" field on buglist.cgi was not sorted alphabetically, so + it wasn't very useful for sorting (bug 342828). + ++ Sendmail will no longer complain about there being a newline in the + email address, when Bugzilla sends mail (bug 331365). + ++ contrib/bzdbcopy.pl would try to insert an invalid value into the + database, unnecessarily (bug 335572). + ++ Deleting a bug now correctly deletes its attachments from the database + (bug 339667). + + +Minimum Requirements +******************** + +Perl +---- + + Perl v5.6.1 (Non-Windows platforms) + ActiveState Perl v5.8.1 (Windows only) + + Note that this is the last release of Bugzilla to support perl 5.6.x-- + future versions will require perl 5.8. + +For MySQL Users +--------------- + + MySQL v4.0.14 (changed from 2.20) + perl module: DBD::mysql v2.9003 (changed from 2.18) + +For PostgreSQL Users +-------------------- + + PostgreSQL 7.3.x + perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+) + + WARNING: DBD::Pg 1.43 has a bug which causes checksetup.pl to fail + and corrupt the database. If you are using DBD::Pg 1.43, either downgrade + to 1.41 or upgrade to 1.45 (1.42 and 1.44 seem broken somehow too). + + Note that this is the last release of Bugzilla to support PostgreSQL 7.x. + Future versions will require PostgreSQL 8.0 and DBD::Pg 1.45. + +Required Perl Modules +--------------------- + + AppConfig v1.52 + CGI v2.93 + Data::Dumper (any) + Date::Format v2.21 + DBI v1.38 + File::Spec v0.84 + File::Temp (any) + Template Toolkit v2.10 (changed from 2.20) + Text::Wrap v2001.0131 + Mail::Mailer v1.67 (changed from 2.20) + MIME::Base64 v3.01 (new in 2.22) + MIME::Parser v5.406 (new in 2.22) + Storable (any) + + Note: The SMTP support in Mail::Mailer 1.73 (the most recent version) + is broken. The last known working version is 1.67. + +Optional Perl Modules +--------------------- + + Chart::Base v1.0 + GD v1.20 + GD::Graph (any) + GD::Text::Align (any) + Net::LDAP (any) + PatchReader v0.9.4 + XML::Twig (any) (new in 2.22) + Image::Magick (new in 2.22) + + +What's New? +*********** + +Complete PostgreSQL Support +--------------------------- +Bugzilla 2.20 contained experimental support for PostgreSQL. +In Bugzilla 2.22, PostgreSQL support is fully complete and stable. Using +PostgreSQL with Bugzilla should be as stable as using MySQL, and if +you experience any problems they will be taken as seriously as if you +were running MySQL. + +There are no known remaining major problems with Bugzilla on PostgreSQL. +All features of Bugzilla have been tested and work. + + +Parameters In Sections +---------------------- +Long-time users of Bugzilla know that over time the parameter list has +grown quite large. It has now been split into sections to make it easier +to use. + + +One Codebase, Multiple Databases +-------------------------------- +There is now limited support for having multiple projects use the +same Bugzilla codebase, but all have separate databases. + +The different projects can have their own templates and their own +bug database, but all use the same set of Bugzilla code in the same +directory. + +To enable this, set an environment variable called PROJECT when +calling the Bugzilla CGIs. Then for each project, you can have +a localconfig.PROJECT (where "PROJECT" is the value of the PROJECT +environment variable) file for the database parameters, and a +template/en/PROJECT directory (where "PROJECT" is the value of the +PROJECT environment variable) + +This feature isn't documented yet, but we hope to have documentation for +it soon. + + +UTF-8 For New Installations +--------------------------- +If this is the first time you're installing Bugzilla, it will now use +UTF-8 encoding for all pages, automatically. It will also send emails +in UTF-8. This eliminates most of the internationalization problems +users have experienced, as one Bugzilla page may now contain any number +of languages simultaneously. + +If you are upgrading and you want to use UTF-8, just turn on the "utf8" +Parameter. However, realize that if you have non-UTF-8 data in your +Bugzilla, it will appear unreadable. (If you just have ASCII in your +database, you're safe to turn on the "utf8" parameter, definitely.) + + +Admins Can Impersonate Users +---------------------------- +User impersonation (think of the su/sudo command on Unix) allows you +to view pages and perform actions as if you are logged in as someone else, +without having to know their password. + +A user in the new "bz_sudoers" group has the option of "becoming" +any user in Bugzilla. Once they "become" that user, they *are* that user +for the rest of the session, until they decide to switch back to being +themselves. + +However, they cannot "become" any user in the "bz_sudo_protect" group. +This group includes everybody in the "admin" and "bz_sudoers" groups by +default. + +Any time a user is impersonated, they will get an email notifying them +who has impersonated them. + + +Bug Import and Moving Improvements +---------------------------------- +The XML Import script, importxml.pl, has been completely re-written. + +It now: + + * Correctly imports the "priority" field + * Understands when the "Reporter" or "CC List" security boxes + are unchecked on the bug. + * Places bugs in the appropriate groups + * Allows attachments to be imported + * Is much more forgiving about small problems in the XML + + +Adding Individual Bugs to Saved Searches (Tagging) +-------------------------------------------------- +Users now have the option of adding an individual bug to any +particular Saved Search. Individual users that disagree with the site +default can add or remove this feature (which appears as an entry box +visible in the footer) by changing the General Preferences setting +called "Enable tags for bugs". + + +Attach URLs +----------- +Instead of attaching a file, you can now also attach a URL to a bug. +This will show up just like an attachment on show_bug.cgi, but when +you click on it, it will take you to the URL. + +To enable this, turn on the "allow_attach_url" parameter. + + +Optional "Strict Isolation" for Groups +-------------------------------------- +If you turn on the "strict_isolation" parameter in Bugzilla, you +will *not* be able to add any user to the CC field (or set them +as an Assignee or QA Contact) unless that user could normally see +the bug. That is, you will no longer be able to "accidentally" +(or intentionally) give somebody access to a bug that they +otherwise couldn't see. + + +"editcomponents" Change +----------------------- +Previously, all users who had "editcomponents" could see every Product, +using the editcomponents.cgi script. Now, users with "editcomponents" +can only see Products that they normally have access to. + +This restriction also affects editversions.cgi, editmilestones.cgi and +editproducts.cgi. + + +"shutdownhtml" Change +--------------------- +All of Bugzilla is now affected by the "shutdownhtml" parameter, +including command-line scripts. checksetup.pl is exempt. Many scripts +(such as collectstats.pl and whine.pl) will just exit silently when +"shutdownhtml" is turned on. + + +Miscellaneous Improvements +-------------------------- + +- Added a frequently-requested user preference for whether or not to go + to the next bug in your list after submitting changes to a bug. + +- The ability to do relative date searches (like "1d" for "1 day" or "1w" + for "1 week") by hour now, in addition to days and other units of time. + +- "Alias" added to the New Bug form, for users with editbugs. + +- Users can now actually see the descriptions of flags that you enter + in editflagtypes.cgi. The description will appear as a tooltip + when a user places their mouse over the flag name on show_bug.cgi. + +- Bugzilla will optionally convert BMP attachments into PNGs for you. + See the "convert_uncompressed_images" in the "Attachments" section + of the Parameters. + +- You can now edit the Status Whiteboard when you are changing multiple + bugs at once. + +- The way that groups work in the database has changed, and large-scale + Bugzilla use with many concurrent users should be much faster, as a + result. (Technical Details: The need for Bugzilla to "derive groups" + has gone away pretty much entirely.) + +- Performance improvements on searching attachment information that's not + the actual content of the attachment (such as searching the Attachment + Description or the Attachment MIME Type) + +- You can now specify multiple email addresses, comma-separated, when + setting the requestee of a flag, and it will set the flag once for each + of those email addresses + +- "Bug Creation Time" is now searchable in the Boolean Charts. + +- When you mark a comment on a bug as private, the background color + of the comment will change immediately. However, in order for + Bugzilla to register that the comment is now private, you still + have to "submit" the changes. + +- Emails sent from Bugzilla now have "X-Bugzilla-Keywords" and + "X-Bugzilla-Severity" by default, containing the information + from the related Bugzilla fields. + +- You can now change the assignee and QA contact on multiple bugs at + once even when those bugs are in different products. + +- contrib/merge-users.pl allows you to merge two user accounts. This is + particulary useful when a user opened several accounts and only one should + be kept. It also lets you merge a deleted account with an existing one. + +All Changes +----------- + +If you'd like to see all the changes between Bugzilla 2.20 and Bugzilla +2.22, see: + +http://tinyurl.com/9p2tm + + +Deprecated Features +******************* + +- This is the last release of Bugzilla to support perl 5.6.x. All future + versions of Bugzilla will require at least perl 5.8. + + This is the last release of Bugzilla to support PostgreSQL 7.x. Future + releases using PostgreSQL will require PostgreSQL 8.0 and DBD::Pg 1.45. + +Outstanding Issues +****************** + +- bug 305836: PostgreSQL users: do not use DBD::Pg version 1.43 with + Bugzilla. It has a bug which can corrupt the database. Version 1.41 + is fine. Version 1.45 or higher is fine too. + +- (No Bug Number) VERY IMPORTANT: If you have customized the values in + your Status/Resolution field, you must edit checksetup.pl BEFORE YOU + RUN IT. Find the line that starts like this: + + bug_status => ["UNCONFIRMED", + + That's where you set the values for the Status field. + + resolution => ["","FIXED", + + And that's where you set values for the Resolution field. + + Those are both near line 1826 in checksetup.pl. + + If you forget to do this, you will have to manually edit the "bug_status" + and "resolution" tables in the database to contain the correct values. + +- bug 276230: The support for restricting access to particular Categories of + New Charts is not complete. You should treat the 'chartgroup' Param as the + only access mechanism available. However, additionally, charts migrated from + Old Charts will be restricted to the groups that are marked MANDATORY for + the corresponding Product. There is currently no way to change this + restriction, and the groupings will not be updated if the group configuration + for the Product changes. + +- bug 37765: If you use the "sendmail" support of Bugzilla, + and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.) + make sure the "sendmailnow" parameter is ON or Bugzilla will not send + e-mail correctly. + +- bug 69621: If you rename or remove a keyword that is in use on bugs, you will + need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing + the option to rebuild the cache when it asks. Otherwise keywords may not show + up properly in search results. + +- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for + example, if you use a translation of Bugzilla), don't enable the XS::Stash + option when you install the Template Toolkit, or your Bugzilla installation + may become slow. This problem is fixed in a not-yet-released version of the + Template Toolkit (after 2.14). + +- Bug 99215: Flags are not protected by "mid-air collision" detection. + Nor are any attachment changes. + +- Bug 89822: When changing multiple bugs at the same time, there is no + "mid-air collision" protection. + +- bug 322955: The email interface (bug_mail.pl) in the contrib/ directory + has not been maintained (as it has no maintainer), and does not work + properly. We hope to have this fixed in our next major release of + Bugzilla; however, any help or contributions in this area are very + welcome. + + +How to Upgrade From An Older Bugzilla +************************************* + +NOTE: Upgrading from a large installation (over 10,000 bugs) running 2.18 + or before may take a significant amount of time. checksetup will + try to let you know how long it will take, but expect downtime + of an hour or more if you have many bugs, many attachments, + or many users. + +Steps for Upgrading +------------------- + +1) Read these entire Release Notes, particularly the "Outstanding Issues" + and "Security Fixes" sections. + +2) View the Sanity Check (sanitycheck.cgi) page on your installation before + upgrading. Attempt to fix all warnings that the page produces before + you go any further, or you may experience problems during your upgrade. + +3) Make a backup of the Bugzilla database before you upgrade, perhaps + by using mysqldump. THIS IS VERY IMPORTANT. If anything goes wrong + during the upgrade, your installation can be corrupted beyond + recovery. Having a backup keeps you safe. + + Example: + + mysqldump -u root -p bugs > bugs-db.sql + +4) Replace the files in your installation with the new version of Bugzilla, + or you can try to use CVS to upgrade. The bugzilla.org website has + instructions on how to do the actual installation. + + You can also use a brand-new Bugzilla directory, as long as you + copy over the old data/ directory and the "localconfig" file to the + new installation. + +5) Run checksetup.pl after you install the new version. + +7) View the Sanity Check page again after you run checksetup.pl. + +8) It is recommended that, if possible, you fix any problems you find + immediately. Failure to do this may mean that Bugzilla will not work + correctly. Be aware that if the sanity check page contains more errors after + an upgrade, it doesn't necessarily mean there are more errors in your + database, as additional tests are added to the sanity check over time, and + it is possible that those errors weren't being checked for in the old + version. + +9) This version of Bugzilla contains improvements to the email that + Bugzilla sends when a bug is changed. The template for that email + is contained in the "newchangedmail" parameter. If you would like + to take advantage of the email enhancements in this version of + Bugzilla, reset that parameter to its default. (You can customize + it after that again, if you want.) + + +Code Changes Which May Affect Customizations +******************************************** + +CGI.pl is Gone +-------------- +The CGI.pl file, which used to contain many global functions, and which +also contained initialization code for every CGI, is gone. The functions +have been moved to various places and sometimes renamed. + +The initialization code that used to happen inside CGI.pl is now inside +of Bugzilla.pm. All CGIs must "use Bugzilla" in one way or another. (Some +CGIs "use Bugzilla" by doing "require globals.pl".) + + +Deriving Groups No Longer Happens +--------------------------------- +Bugzilla no longer needs to "derive groups" in advance. That is, previously +Bugzilla used to flatten the group heirarchy into the user_group_map +table. (That is, show that a user was in every group they were in, +even if they were only in that group because they belonged to *another* +group.) Now the table only contains groups that the user is in directly, +and groups that they are in because of a regexp. + +Instead, The Bugzilla::User->group function determines the groups a user +is in when called. + +We did this because the group derivation was causing a lot of complexity +in the code, and also deriving the groups was a slow process that +frequently had to happen inside of a database lock while sending mail +or viewing a bug list. + +See https://bugzilla.mozilla.org/show_bug.cgi?id=304583 for details. + + +Other Changes +------------- + +- The move.pl script's functionality has been merged into process_bug.cgi. + +- $::template and $::vars are gone from globals.pl. Instead of $::template, + use Bugzilla->template. Every script creates the $vars variable by itself + instead of using a global $::vars variable. + +- $::userid is gone. Instead use Bugzilla->user->id. + +- QuickSearch is now in perl instead of in JavaScript. The code is in + Bugzilla/Search/QuickSearch.pm. This makes it much easier to customize, + and it also fixes some long-standing issues that QuickSearch had. + +- Attachment data is now in the attach_data table. Other information + about attachments is still in the "attachments" table. + +- Much like the 2.20 release, many functions have been removed from + globals.pl and CGI.pl. They were moved elsewhere and renamed. + Search RESOLVED bugs in bugzilla.mozilla.org for the old + version of the function name, and that will usually show you + the bug where we moved the function, allowing you to find out + what the new name and location is. + +- This is the last release that contains the deprecated + SendSQL, SqlQuote, FetchSqlData, MoreSqlData, and FetchOneColumn + functions. Instead, you should use DBI functions. For a very brief + example, see: + + http://www.bugzilla.org/docs/developer.html#sql-sendreceive + + +Security Fixes in 2.22 Releases +******************************* + +A long-standing, well-known security issue is finally resolved in Bugzilla +2.22: Previously, the "Session ID" of each user could be easily guessed, +given enough time. This could have allowed an attacker to take over a +user's account, in certain circumstances. Now, the "Session ID" is totally +random, resolving this issue. See bug 119524 in bugzilla.mozilla.org for +details. + +If you are very concerned about the security of your Bugzilla installation, +it would be a very good idea to run the following command on your +database immediately after upgrading: + +TRUNCATE TABLE logincookies; + +This is actually safe to do at any time--it just forces a logout of +every single user, even those with saved sessions. (It invalidates +every login cookie Bugzilla has ever given out.) + +Version 2.22.2 +-------------- + +A Cross-Site Scripting vulnerability is fixed in Bugzilla 2.22.2. You can +read the details of the fix at: + +http://www.bugzilla.org/security/2.20.3/ + +Version 2.22.1 +-------------- + +The Bugzilla team fixed two Information Leaks and three Cross-Site +Scripting vulnerabilities that existed in versions of Bugzilla +prior to 2.22.1. We strongly recommend that you update any 2.22 +installation to 2.22.1, to be protected from these vulnerabilities. + +In addition, we have made an enhancement to security in this version +of Bugzilla. In previous versions, it was possible for malicious +users to exploit administrators in certain ways. Although this has +never happened (to our knowledge) in the real world, we thought it +was important that we protect administrators from this sort of attack. + +You can see details on all the vulnerabilities and enhancements at: + +http://www.bugzilla.org/security/2.18.5/ + + +Release Notes For Previous Versions +************************************ + +*************************************** +*** The Bugzilla 2.20 Release Notes *** +*************************************** + +Table of Contents +***************** + +- Introduction +- Important Updates in this Point Release + * Version 2.20.1 + * Version 2.20.2 +- Minimum Requirements + * Perl + * For MySQL Users + * For PostgreSQL Users + * Required Perl Modules + * Optional Perl Modules +- What's New? + * Experimental PostgreSQL Support + * New User-Interface Color/Style + * Higher-Level Categorization of Bugs (above "Product") + * Regular Reports by Email of Complex Queries ("Whining") + * "Environment Variable" Authentication Method + * User-List Drop-Down Menus + * Server-Side Comment Wrapping + * UI for Editing Priority, OS, Platform, and Severity + * Bugzilla Queries as RSS + * Choice of E-Mail Sending Methods + * "User Preferences" + * "Large Attachment" Storage + * "User Visibility" Controls + * Miscellaneous Improvements + * All Changes +- Deprecated Features +- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) +- How to Upgrade From An Older Bugzilla + * Steps for Upgrading +- Code Changes Which May Affect Customizations + * The New Database-Compatibility Layer + * If You Customize Your Database... + * Many Functions Renamed + * User Preferences + * Other Changes +- Security Fixes In 2.20 Releases +- Release Notes for Previous Versions + + +Introduction +************ + +This document contains the release notes for Bugzilla 2.20. +In this document, recently added, changed, and removed features +of Bugzilla are described. If you are upgrading from an older version, +you will definitely want to read these release notes in detail, so that +you have an idea of what has changed. + +If you are upgrading from a version before 2.18, also read the 2.18 release +notes (lower in this file) and any previous release notes. + +If you are installing a new Bugzilla, you will still want to look over +the release notes to see if there is any particularly important information +that affects your installation. + +The 2.20 release has had about nine months of development since 2.18, but +they were nearly the most active nine months in Bugzilla's history. We hope +that users will appreciate our many external changes, and that Bugzilla +administators will find that our internal changes make their lives easier. + +If you would like to contribute code to Bugzilla, read our +Contributor's Guide at: + +http://www.bugzilla.org/docs/contributor.html + + +Important Updates In This Point Release +*************************************** + +Version 2.20.1 +-------------- + ++ Many PostgreSQL fixes, including fixing whine.pl on Pg 8 + (bug 301062) and fixing the --regenerate option of collectstats.pl + for all versions of Pg (bug 316971). However, users who want full + PostgreSQL support are encouraged to use the 2.22 series, as + certain PostgreSQL bugs were discovered that will not be fixed + in 2.20 (their fixes were too complex). + ++ In Bugzilla 2.20, the "administrator" user created by checksetup.pl + would not ever be sent email, because their email preferences were + left blank. This has been fixed for 2.20.1. However, if you created + this administrative user with Bugzilla 2.20, make sure to go back + and enable their Email Preferences. (bug 317489) + ++ The bzdbcopy.pl script mentioned in these release notes + has now actually been checked-in to the 2.20 branch, and so + it's included in this release. (bug 291776) + ++ When there's only one Classification, you now won't be required + to pick a Classification on bug entry. (bug 311489) + ++ You can no longer add dependencies on bugs you can't see. + (bug 141593) + ++ The CC list is included in "New" bug emails, again. (bug 313661) + ++ In the original 2.20, certain scripts were not correctly using + the "shadow database," if it was specified. This has been fixed + in 2.20.1. (bug 313695) + ++ "Saved Searches" that were saved before Bugzilla 2.20, would throw + an error if they contained "Days Since Bug Changed." as part of their + criteria. This has been fixed in Bugzilla 2.20.1. (bug 302599) + ++ You can now successfully delete a product even when Target Milestones + are turned off. (bug 317025) + ++ checksetup.pl now correctly pre-compiles templates for languages other + than English. (bug 304417) + ++ The "All Closed" chart that is created by default in New Charts + now actually represents all closed bugs, and not all bugs in the + product. (bug 300473) + ++ CSV bug lists with more than 1000 dates now work properly. (bug 257813) + ++ Various bugs with upgrading from previous versions of Bugzilla + have been fixed. (bug 307662, bug 311047, bug 310108) + ++ Many, many other bug fixes. See http://www.bugzilla.org/status/changes.html + for details on what was fixed between 2.20 and 2.20.1. + + +Version 2.20.2 +-------------- + ++ Adding a new attachment and taking the bug at the same time does not + create a referential integrity problem anymore if the bug was marked as + a duplicate (bug 332705). + ++ Some additional admin links have been added to the sidebar (bug 282613). + ++ A new test has been added to our test suite, named 012throwables.t. + It will now make sure that all tags used in ThrowUserError() and + ThrowCodeError() are defined, and that there are no unused tags (bug 312042). + ++ whine.pl now works correctly on MySQL 4.0. MySQL 4.1 is not affected + (bug 327348). + ++ contrib/merge-users.pl allows you to merge two user accounts. This is + especially useful when a user opened several accounts and only one + should be kept (bug 188264). + ++ The login form on index.cgi again works correctly on a fresh installation + (bug 328108). + ++ Email preferences are now set correctly when creating a new user account + using the ENV method (bug 327355). + + +Minimum Requirements +******************** + +Perl +---- + + Perl v5.6.1 (changed from 2.18) (Non-Windows platforms) + ActiveState Perl v5.8.1 (Windows only) + +For MySQL Users +--------------- + + MySQL v3.23.41 (Note: 2.22 will require MySQL 4.x) + perl module: DBD::mysql v2.9003 (changed from 2.18) + +For PostgreSQL Users (new in 2.20) +-------------------- + + PostgreSQL 7.3.x (8.x has received less testing) + perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+) + +Required Perl Modules +--------------------- + + AppConfig v1.52 + CGI v2.93 + Data::Dumper (any) + Date::Format v2.21 + DBI v1.38 (changed from 2.18) + File::Spec v0.84 (changed from 2.18) + File::Temp (any) + Template Toolkit v2.08 + Text::Wrap v2001.0131 + Mail::Mailer 1.65 (new in 2.20) + Storable (any) (new in 2.20) + +Optional Perl Modules +--------------------- + + Chart::Base v1.0 + GD v1.20 + GD::Graph (any) + GD::Text::Align (any) + Net::LDAP (any) + PatchReader v0.9.4 + XML::Parser (any) + + +What's New? +*********** + +Experimental PostgreSQL Support +------------------------------- + +In addition to MySQL, Bugzilla now also supports PostgreSQL. PostgreSQL +support is still somewhat experimental. Although most major features of +Bugzilla work on PostgreSQL in 2.20, there are probably still a few bugs +that need to be worked out. + +PostgreSQL support in 2.20 is acceptable for smaller production +environments that don't mind running into a bug or two now and then. + + +New User-Interface Color/Style +------------------------------ + +You'll notice that Bugzilla looks a bit nicer, now! We've made a few +color and style changes to update the overall "feel" of Bugzilla's +User Inteface. We plan to do even more work on the UI for 2.22. + + +Higher-Level Categorization of Bugs (above "Product") +----------------------------------------------------- + +Previous Bugzillas had "Products" that you could file bugs in, +and "Components" for those products. Now, "Products" can be grouped +into "Classifications." + +To enable this, a Bugzilla administrator can turn on the +"useclassification" parameter, using editparams.cgi. + + +Regular Reports by Email of Complex Queries ("Whining") +------------------------------------------------------- + +You can now tell Bugzilla to do a specific query (or set of queries) +every X minutes/hours/days, and send you the results by email. This is +great for keeping track on a daily basis of what's going on in +your Bugzilla. + + +"Environment Variable" Authentication Method +-------------------------------------------- + +You can now tell Bugzilla to accept a certain value passed in from +Apache as authentication for Bugzilla users. This means that Bugzilla +now "supports" any type of authentication that Apache supports. + +To use this, set the "user_info_class" parameter to "ENV" and, at a +minimum, set the "auth_env_email" parameter to the name of the +Environment variable that passes the authenticated user (usually +"REMOTE_USER"). If your webserver knows users' real names as well, also +set the "auth_env_realname" parameter. If you are using a true +single-signon system that assigns an identifier uniquely to an +individual, even across changes of email address, then set +"auth_env_id" to the name of that variable. + + +User-List Drop-Down Menus +------------------------- + +Now, anywhere in Bugzilla where you previously had to type in an +email address by hand, you have the choice of having Bugzilla instead +display a drop-down menu of users to pick from. + +This feature is best for small installations with few users, because +on large installations the list grows too large to be useful. + +To enable the feature, turn on the "usemenuforusers" parameter in +editparams.cgi. + + +Server-Side Comment Wrapping +---------------------------- + +In older Bugzillas, comments were wrapped to 80 characters by the +user's web browser, and then stored in the database that way. This caused +problems because some browsers did not wrap comments properly. + +Now, Bugzilla stores comments unwrapped and wraps them at display time, so +all new comments should be properly wrapped. Also, when you upgrade, Bugzilla +will look for old "mis-wrapped" comments and attempt to wrap them properly. + +Lines beginning with the ">" character are assumed to be quotes, and are +*not* wrapped. + + +UI for Editing Priority, OS, Platform, and Severity +--------------------------------------------------- + +Bugzilla now has a User Interface for adding and removing values +from the OS, Platform, Priority, and Severity fields. You can also +rename values. Any user in the "editcomponents" group can click +on the "Field Values" link in their page footer to edit these fields. + +Also, the default list of choices for OS and Platform for new +installations is now much smaller. Old installations will keep +the same list they have now. + + +Bugzilla Queries as RSS +----------------------- + +You can now view a Bugzilla query as valid RSS 1.0. This means that you +could add a particular query to your RSS aggregator, if you wanted, to +keep track of changes in Bugzilla. + +To see a query as RSS, just click on the "RSS" link on the bottom of +your query results. Your query must return at least 1 result in order +for you to see the link. + + +Choice of E-Mail Sending Methods +-------------------------------- + +Bugzilla now uses perl's Mail::Mailer to send e-mail. This means that +you have several choices of how Bugzilla can send email. By default, it +still uses sendmail, but it can also use SMTP, qmail, or send all email +to a file instead of out to users. + +A Bugzilla administrator can change which method is used by setting the +"mail_delivery_method" parameter in editparams.cgi. + + +"User Preferences" +------------------ + +Bugzilla users will now notice a section in their Preferences called +"General Preferences." Administrators will notice a new link called +"User Preferences." + +The Preferences system allows Bugzilla developers to specify arbitrary +"user preferences" that change the behavior of certain parts of Bugzilla. +Administrators can control whether or not users are allowed to use these +preferences, and what the default settings are for a user who is not +logged in. + +The first two preferences that we have implemented are: + + "Show a quip at the top of each bug list" + + "When viewing a bug, show comments in this order..." + +We plan to implement more preferences in the future. + + +"Large Attachment" Storage +-------------------------- + +Bugzilla can now store very large attachments on disk instead of in the +database. These attachments can't be searched with Boolean Charts, but +they also don't take up database space, and they can be deleted individually +by the admin. + +When uploading an attachment, a user chooses if it's a "Big File." If so, +it's stored on the disk instead of in the database. + +To enable this feature, set the "maxlocalattachmentsize" parameter to +a non-zero value, in editparams.cgi. + + +"User Visibility" Controls +-------------------------- + +It is now possible to prevent users from encountering all other users when +using user-matching or drop-down userlists. To enable this restriction, +enable the "usevisibilitygroups" parameter. Once this is enabled, each +group's permissions will include a new column for "visible." The members +of any group for which the group being edited is visible will be +able to user-match this groups's users or see them in dropdown lists. + +This does not control who a user can CC on a bug, only who they can +see in the user-matching lists or drop-downs. + +Miscellaneous Improvements +-------------------------- + +- Marking an attachment as obsolete will now cancel all pending flag + requests for that attachment. That is, any flag that was set to "?" + on that attachment will be cleared. + +- You can now see which users are "watching" you, on the email + preferences page. + +- You can tell Bugzilla to mark certain comments in a different + color by adding "&mark=1,2,3,5-7" to the end of the show_bug.cgi URL, + where "1,2,3,5-7" means "highlight comment 1, comment 2, comment 3, and + comments 5 through 7." + +- "QA Contact" now also appears on the New Bug page, if QA Contacts are + enabled on your installation. + +- Bugzilla email now has the "In-Reply-To" header added to it, so if + you use an email client that supports threads, you can view your + Bugzilla email in threads. If you are upgrading to a new version of + Bugzilla, and you want this support, please see the instructions at: + https://bugzilla.mozilla.org/attachment.cgi?id=172267 + +- The email preferences system has been slightly updated. You will notice + the changes on your Email Preferences page. + +- You can now negate individual "boolean charts" (in the + "Advanced Searching" section at the bottom of the "Advanced + Search" page). That is, you can add "NOT" to the front of them. + +- You can add the words %assignee%, %reporter%, %user% (yourself), or + %qacontact% on the right-hand side of a Boolean Chart. For example, you + could make a Boolean Chart which said "Reporter" "does not equal" + "%assignee%". That would give you all bugs where the Reporter was not + the same as the Assignee. + +- You can now search Boolean Charts by "commenter." + +- If you have a group with no name, it will be re-named to "group_#" where + "#" is the numeric Bugzilla Group ID for that group. + +- If you are using time-tracking, you can now see a report of time spent + on bugs using summarize_time.cgi. + +- If you are using time-tracking, bugzilla will now set "hours remaining" + to "0" automatically if you RESOLVE a bug, whether you are in the + time-tracking group or not. + + +Deprecated Features +******************* + +- Bugzilla 2.20 is the last Bugzilla version to support MySQL 3.23.x. + Starting with Bugzilla 2.22, Bugzilla will require MySQL 4.0.x. This will + allow Bugzilla to take advantage of the advanced features of MySQL 4. + + +Outstanding Issues +****************** + +- (No Bug Number) VERY IMPORTANT: If you have customized the values in + your Status/Resolution field, you must edit checksetup.pl BEFORE YOU + RUN IT. Find the line that starts like this: + + bug_status => ["UNCONFIRMED", + + That's where you set the values for the Status field. + + resolution => ["","FIXED", + + And that's where you set values for the Resolution field. + + Those are both near line 1826 in checksetup.pl. + + If you forget to do this, you will have to manually edit the "bug_status" + and "resolution" tables in the database to contain the correct values. + +- bug 37765: VERY IMPORTANT: If you use the "sendmail" support of Bugzilla, + and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.) + you MUST turn on the "sendmailnow" parameter or Bugzilla will not send + e-mail correctly. + +- (No Bug Number) If you close your web browser while the process_bug.cgi + or post_bug.cgi screen is running, not all emails will be sent, and + the next time that that bug is updated, there will be two updates. This + is because of a behavior of Apache that is beyond our control. + +- bug 276230: The support for restricting access to particular Categories of + New Charts is not complete. You should treat the 'chartgroup' Param as the + only access mechanism available. However, additionally, charts migrated from + Old Charts will be restricted to the groups that are marked MANDATORY for + the corresponding Product. There is currently no way to change this + restriction, and the groupings will not be updated if the group configuration + for the Product changes. This will not be fixed in the 2.20 branch. + +- bug 69621: If you rename or remove a keyword that is in use on bugs, you will + need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing + the option to rebuild the cache when it asks. Otherwise keywords may not show + up properly in search results. + +- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for + example, if you use a translation of Bugzilla), don't enable the XS::Stash + option when you install the Template Toolkit, or your Bugzilla installation + may become slow. This problem is fixed in a not-yet-released version of the + Template Toolkit (after 2.14). + +- If at any time you upgraded from a version of Bugzilla between 2.17.4 - + 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in + order for them to work. See the following link for instructions on how to do + this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18 + If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer, + then you don't need to do this. + +- (No Bug Number) If your DBI is really, really old, Bugzilla might fail + with a strange error message when you try to run checksetup.pl. Try + upgrading your DBI using: perl -MCPAN -e'install DBI' + +- Bug 126266: Bugzilla does not use UTF-8 to display pages. This means + that if you enter non-ASCII characters into Bugzilla, they may + display strangely, or Bugzilla may have other problems. For a workaround, + see: http://www.bugzilla.org/docs/tip/html/security-bugzilla.html + This has been fixed in the 2.22 series. + +- Bug 99215: Flags are not protected by "mid-air collision" detection. + Nor are any attachment changes. + +- Bug 89822: When changing multiple bugs at the same time, there is no + "mid-air collision" protection. + +- Bug 285614: importxml.pl may be broken in many different ways. + It has been fixed and completely re-written in the 2.22 series. + +- (No Bug Number) Note that the email interface (bug_mail.pl) in the + contrib/ directory has not been maintained (as it has no maintainer), + and so may not be working properly. Contributions are welcome, if + anybody would like to work on it. + + +Upgrading From An Older Bugzilla +************************************ + +NOTE: Running checksetup.pl to upgrade a large installation (over 10,000 bugs) + may take a significant amount of time. checksetup will try to let + you know how long it will take, but expect downtime of an hour or + more if you have many bugs, many attachments, or many users. + +Steps for Upgrading +------------------- + +1) View the Sanity Check (sanitycheck.cgi) page on your installation before + upgrading. Attempt to fix all warnings that the page produces before + you go any further, or you may experience problems during your upgrade. + +2) Make a backup of the Bugzilla database before you upgrade, perhaps + by using mysqldump. + + Example: + + mysqldump -u root -p --databases bugs > bugs.db.backup + +3) Replace the files in your installation with the new version of Bugzilla, + or you can try to use CVS to upgrade. The Bugzilla.org website has + instructions on how to do the actual installation. + +4) Make sure that you run checksetup.pl after you install the new version. + +5) View the Sanity Check page again after you run checksetup.pl. + +6) It is recommended that, if possible, you fix any problems you find + immediately. Failure to do this may mean that Bugzilla will not work + correctly. Be aware that if the sanity check page contains more errors after + an upgrade, it doesn't necessarily mean there are more errors in your + database, as additional tests are added to the sanity check over time, and + it is possible that those errors weren't being checked for in the old + version. + +7) If you want threading support on your Bugzilla email (see the + "Miscellaneous Improvements" section above for a description), + you need to follow the instructions at: + https://bugzilla.mozilla.org/attachment.cgi?id=172267 + + +Code Changes Which May Affect Customizations +******************************************** + +The New Database-Compatibility Layer +------------------------------------ + +For most customizations, this should have no effect. However, you should +be aware that Bugzilla->dbh is now an instance of "Bugzilla::DB" instead +of being a DBI object directly. In fact, it's actually a +Bugzilla::DB::Mysql for MySQL users, and a Bugzilla::DB::Pg for +PostgreSQL users. + +Anything called from $dbh (like $dbh->bz_last_key) that starts with +"bz_" or "sql_" is a custom Bugzilla function. Anything *not* starting +with those two prefixes is a normal DBI function. + +Methods whose names start with "sql_" generate a piece of a SQL statement. +They generate the correct version of the statement for whichever database +you are using. + +Methods whose names start with "bz_" do something directly. + +You can see more documentation about this at: + +http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm + + +If You Customize Your Database... +--------------------------------- + +In order to support multiple databases, we had to do something sort of +tricky. Bugzilla now stores what it *thinks* the current database schema +is, in a table called bz_schema. + +This means that when checksetup changes the database, it updates the +bz_schema table. When *you* update the database, without using +checksetup to do it, the bz_schema table is *not* updated. + +So, if you're going to add/remove a new column/table to Bugzilla, or if you're +going to change the definition of a column, try to do it by adding code to +checksetup in the correct place. (It's one of the places where you find +the word "--TABLE--".) + +You can see the documentation on the $dbh functions used to do this at: + +http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm#schema_modification_methods + + +Many Functions Renamed +---------------------- + +We are reorganizing the Bugzilla code so that it can support mod_perl. As +part of this, we are moving all functions out of globals.pl and CGI.pl, and +into modules in the Bugzilla/ directory. + +Sometimes when we moved them, we also renamed them. The new Bugzilla standard +is to have functions_named_like_this, instead of FunctionsNamedLikeThis. + +So if you were using a FunctionNamedLikeThis that no longer works, try just +using it as function_named_like_this. If that doesn't work, you may have to +search for where we put it, and what we renamed it to. Most of the functions +moved to logical places. + +If you really can't find it, search bugzilla.mozilla.org using the name +of the old function. We usually moved one function per bug, so the new +name will be somewhere in a bug report. + + +User Preferences +---------------- + +Bugzilla now has a "User Preferences" system! These preferences are stored +in the database, and specified by a Bugzilla developer. The Bugzilla +developers actually call these "settings," but we called them "User +Preferences" in the UI to make things clearer. + +You access a user's settings differently depending on if you are in a +.cgi file or in a template file: + +CGI: Bugzilla->user->settings->{'setting_name'}->value +Template: Bugzilla.user.settings.setting_name.value + +Where "setting_name" is the name of the setting. You can see the current +setting names in the "setting" table in the database. + +Remember that sometimes you may want to check a user's settings when +making a customization. + +To see how to add new settings, search for "add_setting" in checksetup.pl. +Also see the template: template/en/default/global/setting-descs.none.tmpl. + +Other Changes +------------- + +- The $::unconfirmedstate variable has been replaced by the actual string + "UNCONFIRMED" everywhere in Bugzilla code. + +- The %::FORM and %::MFORM variables are no longer used to access form + data. Instead, use $cgi->param(). There are many examples of how to do + this, all over the Bugzilla code. + +- SendSQL() and related calls are deprecated, and the various $dbh methods + should be used instead, such as $dbh->prepare() and $dbh->execute(). + Bugzilla->dbh is the $dbh handle to use. For more information on how + to use the $dbh methods, see: http://search.cpan.org/dist/DBI/DBI.pm + +- The $::userid variable will be going away. Use Bugzilla->user->id instead. + +- All global variables (any that start with $::, @::, or %::) will + be entirely gone by Bugzilla 2.24. + + +Security Fixes in 2.20 Releases +******************************* + +2.20.1 +------ + +There were three security issues discovered after the release of +Bugzilla 2.20 that we resolved for Bugzilla 2.20.1. One SQL Injection +(from an administrator only), one Cross-Site Scripting vulnerability +(that mostly affects only the user who can exploit it), and one minor, +extremely specific information leak. + +To see details on the vulnerabilities that were fixed, see the +Security Advisory at: + +http://www.bugzilla.org/security/2.16.10/ + + +Release Notes for Previous Versions +*********************************** + +***************************************** +*** The Bugzilla 2.18.x Release Notes *** +***************************************** + +Table of Contents +***************** + +- Introduction +- Important Updates In This Point Release + * Version 2.18.1 + * Version 2.18.2 +- Requirements + * Dependency Requirements +- What's New? + * Generic Reporting + * Generic Charting + * Request System + * Enterprise Group Support + * User Wildcard Matching + * Support for "Insiders" + * Time Tracking + * Authentication module/LDAP improvements + * Improved localization support + * Patch Viewer + * Comment Reply Links + * Full-Text Search + * Email Address Munging + * Simple Search + * Miscellaneous Improvements + * All Changes +- What's Changed? + * Flag Names + * New Saved Search User Interface + * Rules for changing fields +- Removed Features +- Code Changes Which May Affect Customizations +- Recommended Practice for the Upgrade + * Note About Upgrading From MySQL With ISAM Tables + * Steps for Upgrading +- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) +- Security Fixes In 2.18 Releases +- Detailed Version-To-Version Release Notes + + +Introduction +************ + +This document contains the release notes for Bugzilla 2.18 and +the bugfix releases after 2.18. In this document, recently added, +changed, and removed features of Bugzilla are described. + +The 2.18 release is our current stable series, containing the results +of over two years of hard and dedicated work by volunteers all over +the world under the lead of Dave Miller. + + +Important Updates In This Point Release +*************************************** + +There are usually many other bug fixes than those listed below, +but the below fixes are the ones that we thought System Administrators +would like to specifically know about. + +To see a listing of all changes in this release, you can use the +table available at: + +http://www.bugzilla.org/status/changes.html + +Version 2.18.1 +-------------- + ++ You can now enter a negative time for "Hours Worked" + in the time-tracking area. (Bug 271276) + ++ The BugMail.pm customization required for Windows (as + described in the Bugzilla Guide) now actually works. (Bug 280911) + ++ Users who were using Bugzilla 2.8 can now successfully upgrade + to 2.18.1 (they couldn't upgrade to 2.18). (Bug 283403) + ++ Dependency mails are now properly sent during a mass-change of bugs. + (Bug 178157) + + +Version 2.18.2 +-------------- + ++ You can now create accounts with createaccount.cgi even + when the "requirelogin" parameter is turned on. (Bug 294778) + ++ Bugs that are in disabled groups may not show a padlock + on the bug list, or may otherwise behave strangely. You + can now fix this using sanitycheck.cgi. (Bug 277454) + ++ If sendmail dies while you are marking a bug + as a duplicate, the duplicates table will no longer become + corrupted. (Bug 225042) + + +Requirements +************ + +Dependency Requirements +----------------------- + +Minimum software requirements: + + MySQL v3.23.41 (changed from 2.16) + Perl v5.6.0 (changed from 2.16) (Non-Windows platforms) + ActiveState Perl v5.8.1 (Windows only) + +Required Perl modules: + + AppConfig v1.52 + CGI v2.93 (new since 2.16) (changed from 2.17.7) + Data::Dumper (any) + Date::Format v2.21 (changed from 2.16) + DBI v1.36 (changed from 2.16) (changed from 2.17.7) + DBD::mysql v2.1010 (changed from 2.16) + File::Spec v0.82 + File::Temp (any) + Template Toolkit v2.08 (changed from 2.16) + Text::Wrap v2001.0131 + +Optional Perl modules: + + Chart::Base v1.0 (changed from 2.16) (changed from 2.17.7) + GD v1.20 (changed from 2.16) + GD::Graph (any) (new since 2.16) + GD::Text::Align (any) (new since 2.16) + Net::LDAP (any) (new since 2.16) + PatchReader v0.9.4 (new since 2.16) (changed from 2.17.7) + XML::Parser (any) + + +What's New? +*********** + +Generic Reporting +----------------- + +Bugzilla has a new mechanism for generating reports of the current state of +the bug database. It has two related parts: a table-based view, and several +graphical views. + +The table-based view allows you to specify an x, y and z (multiple tables of +data) axis to plot, and then restrict the bugs plotted using the standard +query form. You can view the resulting data as an HTML or CSV export (e.g.: +for importing into a spreadsheet). + +There are also bar, line and pie charts, which are defined in a very similar +way. These views may be more appropriate for particular data types, and are +suitable for saving and then putting into presentations or web pages. + + +Generic Charting +---------------- + +Bugzilla has a new mechanism for generating charts (graphs over time) of any +arbitrary search. This is known as "New Charts." Legacy data from the previous +charting mechanism ("Old Charts") is migrated into the "New Charts" when you +upgrade. The Old Charts mechanism remains, but is deprecated and will be +removed in a future version of Bugzilla. + +Individual users can see/create charts as long as they are a member of the +group specified in the Param 'chartgroup'. Data can be collected for +personal charts every seven days (or a longer period, as set by the user). +Charts created by an administrator can be made public (visible to all). Data +is collected for administrator charts every day (or a longer period, as set +by the admin). + +The data is collected by the collectstats.pl script, which an administrator +will need to arrange to be run once every day (see the manual). Chart data can +be plotted in a number of different ways, and different data sets can be +plotted on the same graph for comparison. + +Please see the Known Bugs section for some important limitations relating to +access controls on charts. + + +Request System +--------------- + +The Request System (RS) is a set of enhancements that adds powerful flag +(superset of the old attachment status) features to the bugs. + +RS allows for four states: off, granted, denied, and (optionally) requested, +where "granted" is the equivalent of "on". These additions mean it is no +longer necessary to define a status to negate another status (e.g. +"needs-work" to negate "has-review") because negation is built into each +status via the status' "denied" state. Bug statuses: Previously only +attachments could have these kinds of statuses. RS enables them for bugs as +well. This feature can be used to request and grant/deny certain properties +for a bug, such as inclusion for a specific milestone or approval for checkin. +This way, Bugzilla supports the natural decision-making process in your +organization. + +- Requests: Flags can now optionally be made requestable, which means users + can ask other users to set them. When a user requests a flag, Bugzilla + emails the requestee and adds the request to a browsable queue so both the + requester and the requestee can keep track of its status. Once the + requestee fulfills the request by setting the flag to either granted or + denied, Bugzilla emails the requestee and removes the request from the + queue. This feature supports workflow like the mozilla.org code review + and milestone approval processes, whereby code is peer reviewed before + being committed and patches get approved by product release managers for + inclusion in specific product releases. + +- Product/component specificity: Previously flags were product-specific, and + if you wanted the same flag for multiple products you had to define + multiple flags with the same name. Flags are now + product/component-specific, and a single flag can be enabled or disabled + for multiple product/component combinations via inclusions and exclusions + lists. Flags are enabled for all combinations on their inclusions list + except those that appear on their exclusions list. + + +Enterprise Group Support +------------------------ + +Bugzilla is no longer limited to 55 access control groups. Administrators can +define an arbitrary number of access groups composed of individual users or +other groups. The groups can be configured via the web interface to achieve a +wide variety of access control policies. See the documentation section on +'Groups And Group Controls' for details. + + +User Wildcard Matching +---------------------- + +Sites can now enable the use of wildcards and substrings in bug entry and +editing forms. If the user enters an incomplete username, he'll get a list of +users that matched the given username. + + +Support for "Insiders" +---------------------- + +If the 'insidergroup' parameter is defined, a specific group of users can be +designated insiders who can designate comments and attachments as private to +other insiders. These comments and attachments will be invisible to other +users who are not members of the insiders group even if the bugs to which they +apply are visible. Other insiders will see the comments and attachments with a +visual tinting indicating that they are private. + + +Time Tracking +------------- + +Controls for tracking time spent fixing bugs are included in the bug form for +members of the group specified by the 'timetrackinggroup' parameter. Any time +comments are added to the bug, members of the time tracking group can add an +amount of time they spent, and it's figured into the total and displayed at +the top of the bug. Shown in the bug are your original estimate, the amount of +time spent so far, the revised estimate of how much time is remaining, and +your gain/loss on the original estimate. + + +Authentication module/LDAP improvements +--------------------------------------- + +Bugzilla's authentication mechanisms have been modularized, making pluggable +authentication schemes for Bugzilla a reality. Both the existing database and +LDAP systems were ported as part of modularization process. Additionally, the +CGI portion of the backend was redesigned to allow for authentication from +other sources, including (theoretically) email, which will help Bug 94850. + +As part of this conversion, LDAP logins now use Perl's standard Net::LDAP +module, which has no external library dependencies. + + +Improved localization support +----------------------------- + +Bugzilla administrators can now configure which languages are supported by +their installations and automatically serve correct, localized content to +users based on the HTTP 'Accept-Language' header sent from users' browsers. + +There are currently localized templates available for: Arabic, Belarusian, +Chinese, French, German, Italian, Korean, Portuguese (Brazil) Spanish (Spain +or Mexico) and Russian. These localized template packs are third-party +contributions, may only be available for specific versions, and may not be +supported in the future. (http://www.bugzilla.org/download/#localizations) + + +Patch Viewer +------------ + +Viewing and reviewing patches in Bugzilla is often difficult due to lack of +context, improper format and the inherent readability issues that raw patches +present. Patch Viewer is an enhancement to Bugzilla designed to fix that by +offering increased context, linking to sections, and integrating with Bonsai, +LXR and CVS. + + +Comment Reply Links +------------------- + +In Edit Bug, each bug comment now includes a convenient (reply) link that +quotes the comment text into the textarea. This feature is only enabled in +Javascript-capable browsers, but causes no inconvenience to other user agents. + + +Full-Text Search +---------------- + +It is now possible to query the Bugzilla database using full-text searching, +which spans comments and summaries, and which searches for substrings and stem +variations of the search term. Basically, it's like using Google. + + +Email Address Munging +--------------------- + +The fact that raw email addresses are displayed in Bugzilla makes it trivial +for bots that spamharvest to spider through Bugzilla, in particular, through +Bugzilla's buglists. This change adds HTML obfuscation of email addresses as +they appear in the Bugzilla web pages. + + +Google-like Bug Search +---------------------- + +Bugzilla now includes a very simple, Google-like "Find a Specific Bug" page, +in addition to its advanced search page. + + +Miscellaneous Improvements +-------------------------- + +- The "Assigned To" field on the new bug page is now prefilled with the default + component owner. + +- A bug alias column is now available in the buglist page. + +- Lists of bugs containing errors in the sanity check page now have a "view as + buglist" link in addition to the individual bug links. + +- Autolinkification Page - It's now possible to apply Bugzilla's comment + hyperlinking algorithm to any text you like. This should be useful for status + updates and other web pages which give lists of bugs. The bug links created + include the subject, status and resolution of the bug as a tooltip. + +- There are more tags on the links toolbar for navigating quickly between + different areas. + +- Buglists are now available as comma-separated value files (CSV) and JavaScript + (JS) as well as HTML and RDF. + +- Keywords and dependencies can now be entered during initial bug entry. + +- A CSS id signature unique to each Bugzilla installation is now added to the + tag on Bugzilla pages to allow custom end-user CSS to explicitly affect + Bugzilla. + +- Perl's path has been changed to a normal /usr/bin/perl from the original + legacy "bonsaitools" path specifier. + +- A new "always-require-login" parameter allows administrators to require a + login before being able to view any page, except the front page. + +- A developer may add an attachment, and also reassign a bug to himself as part + of that single action. + +- Bugzilla is now able to use the replication facilities provided by the + MySQL database to handle updates from the main database to the secondaries. + +- Mail handling is now between 125% to 175% faster. + +- Guided Bug Entry: You can see a sample enter_bug.cgi template at + enter_bug.cgi?format=guided that "guides" users through the process of + filing a "good" bug. It needs to be modified before use in your organization. + +- There is now a "Give me some help" link on the Advanced Search page that will + enable pop-up help for every field on the page. + +- The Bugzilla administrator can now forbid users from marking bugs RESOLVED + when there are unresolved dependencies. + + +All Changes +----------- + +To see a list of EVERY bug that was fixed between 2.16 and 2.18 (over 1000), +see: http://tinyurl.com/6m3e4 + + +What's Changed? +*************** + + +Flag names +---------- + +Prerelease versions of Bugzilla 2.17 and 2.18 inadvertantly allowed +commas and spaces in the names of flags, which due to the way they're +processed, caused lots of internal havoc if you named flags to have +any commas or spaces in them. Having commas or spaces in the names +can cause errors in the notification emails and in the bug activity +log. The ability to create new flags with these characters has been +removed. If you have any existing flags that you named that way, +running checksetup will attempt to automatically rename them by +replacing commas and spaces with underscores. + + +New Saved Search User Interface +------------------------------- + +In previous Bugzilla versions, you could specify on the search page that you +wanted to save a search and store it as a link in your footer. This option has +now moved to the search results page (buglist.cgi), where you will see a +"Remember search" button with a box next to it to enter the name of the search. + +You can manage your saved searches on the Preferences page. + + +Rules for changing fields +------------------------- + +There have been some changes to the rules governing who can change which fields +of a bug report. The rules for Bugzilla version 2.16 and 2.18, along with +differences between them, are listed below. Bear in mind that there are other +restrictions on bug manipulation besides the ones listed below. In particular, +the groups system enforces restrictions on who can create, edit, or even see +any given bug. + +Bugzilla 2.16 rules: + +- anyone can make a null change; +- anyone can add a comment; +- anyone in the editbugs group can make any change; +- the reporter can make any change to the status; +- anyone in the canconfirm group can change the status + to any opened state (NEW, REOPENED, ASSIGNED). +- anyone can change the status to any opened state + if the everconfirmed flag is set; +- the owner, QA contact, or reporter can make any change + *except* changing the status to an opened state; +- No other changes are permitted. + +[Note that these rules combine to allow the reporter to make any change +to the bug.] + +Bugzilla 2.18 rules: + +- anyone can make a null change; +- anyone can add a comment; +- anyone in the editbugs group can make any change; +- anyone in the canconfirm group can change the status + from UNCONFIRMED to any opened state; +- the owner or QA contact can make any change; +- the reporter can make any change *except*: + - changing the status from UNCONFIRMED to any opened state; or + - changing the target milestone; or + - changing the priority (unless the letsubmitterchoosepriority + parameter is set). +- No other changes are permitted. + +The effective differences in the rules: + +- In 2.16, the reporter could always change anything about a bug. + + In 2.18, the reporter can't: + + - confirm the bug unless he is in the canconfirm group; + - change the target milestone; + - change the priority (unless the 'letsubmitterchoosepriority' + parameter is set; + + (unless he is also the owner, the QA contact, or in the editbugs + group, in which case he can do all these things). + +- In 2.16, the owner or QA contact (if the 'useqacontact' parameter + is set) can't change the bug status to an opened status unless they + are also the reporter, or have editbugs or canconfirm, or the + everconfirmed flag is set on the bug). + + In 2.18 the owner or QA contact can make any change to a bug. + +- In 2.16, a member of the canconfirm group can set the status + to any opened status. + + In 2.18 this is only possible if the status was previously + the unconfirmed status. + +- In 2.16, the status can be set to anything by anybody + if the 'everconfirmed' flag is set. + + In 2.18, this authorization code does not pay any attention + to the 'everconfirmed' flag. + + +Removed Features +**************** + +- Please note that Bugzilla no longer supports MySQL 3.22. The minimum required + version is now 3.23.41. + +- The "shadow database" mechanism is no longer used. Instead, use MySQL's + built-in replication feature. + +- If you have placed any comments in the localconfig file, they may be removed + by checksetup.pl. + + +Code Changes Which May Affect Customizations +******************************************** + +- A mechanism (called "Template Hooks") for third party extensions to plug into + existing templates without having to patch or replace distributed templates + has been added. More information on this can be found in the documentation. + +- Header output now uses CGI.pm, in a step towards enabling mod_perl + compatibility. This change will affect users that had customized charsets in + their CGI files: previously the charset had to be added everywhere that + printed the Content-Type header; now it only needs changing in one spot, in + Bugzilla/CGI.pm. + +- $::FORM{} and $::COOKIE{} are deprecated. Use the $cgi methods to access + them. + +- $::userid is gone in favor of Bugzilla->user->id + +- ConnectToDatabase() is gone (it's done automatically when you initialize the + Bugzilla object) + +- quietly_check_login() and confirm_login() are gone, use Bugzilla->login() + with parameters for whether the login is required or not. + +- Use Bugzilla->user->login in place of $::COOKIE{Bugzilla_login} + +- You can tell if there's a user logged in or not by using + Bugzilla->user rather than looking for $::userid==0. + In new 2.18 code, use defined(Bugzilla->user) && (Bugzilla->user->id) + In 2.20, this will become just (Bugzilla->user->id) + In templates, always test [% IF user.id %] rather than [% IF user %] + +- SendSQL() and related calls are deprecated, and the various $dbh methods + should be used instead, such as $dbh->prepare() and $dbh->execute(). + Bugzilla->dbh is the $dbh handle to use. + + +Recommended Practice for the Upgrade +************************************ + +Note About Upgrading From MySQL With ISAM Tables +------------------------------------------------ +As previously noted in the Dependency Requirements MySQL is now required +to be at least version 3.23.41. This implies that all tables of type ISAM will +be converted by the checksetup.pl script to MyISAM. + + +Steps for Upgrading +------------------- + +1) View the Sanity Check (sanitycheck.cgi) page on your installation before + upgrading. + +2) As with any upgrade it is recommended that you make a backup of the + Bugzilla database before you upgrade, perhaps by using mysqldump. + + Example: + + mysqldump -u root -p --databases bugs > bugs.db.backup + +3) Replace the files in your installation, or you can try to use CVS to upgrade. + The Bugzilla.org website has instructions on how to do the actual + installation. + +4) Make sure that you run checksetup.pl after you install the new version. + +5) View the Sanity Check page again after you run checksetup.pl. + +6) It is recommended that, if possible, you fix any problems you find + immediately. Failure to do this may mean that Bugzilla will not work + correctly. Be aware that if the sanity check page contains more errors after + an upgrade, it doesn't necessarily mean there are more errors in your + database, as additional tests are added to the sanity check over time, and + it is possible that those errors weren't being checked for in the old + version. + + +Outstanding Issues +****************** + +These are known problems with the release that we think you should know about. +They each have a bug number for http://bugzilla.mozilla.org/ + +- If at any time you upgraded from a version of Bugzilla between 2.17.4 - + 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in + order for them to work. See the following link for instructions on how to do + this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18 + If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer, + then you don't need to do this. + +- bug 37765: If you use an MTA other than sendmail (such as Postfix, Exim, + etc.) you MUST turn on the "sendmailnow" parameter or Bugzilla will not send + e-mail correctly. + +- bug 276230: The support for restricting access to particular Categories of + New Charts is not complete. You should treat the 'chartgroup' Param as the + only access mechanism available. However, additionally, charts migrated from + Old Charts will be restricted to the groups that are marked MANDATORY for + the corresponding Product. There is currently no way to change this + restriction, and the groupings will not be updated if the group configuration + for the Product changes. + +- bug 69621: If you rename or remove a keyword that is in use on bugs, you will + need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing + the option to rebuild the cache when it asks. Otherwise keywords may not show + up properly in search results. + +- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for + example, if you use a translation of Bugzilla), don't enable the XS::Stash + option when you install the Template Toolkit, or your Bugzilla installation + may become slow. This problem is fixed in a not-yet-released version of the + Template Toolkit (after 2.14). + +- bug 266579: Users may be able to circumvent not having "canconfirm" privileges + in some circumstances. This is fixed starting with 2.19.3, but will not + be fixed in any 2.18 release, as the changes required to fix it are quite + large. + +- bug 99215: Attachment changes have no mid-air collision detection, unlike bug + changes. + +- bug 57350: Searching using the "commenter is" option may be VERY slow. Note + that searching for "field: comment, changed by: user@domain.com" is fast, + though. + +- bug 151509: Using the boolean chart option "contains the string" with the + "flag name" field or certain other fields will cause Bugzilla to emit an + error. This is fixed in 2.20rc1, but will not be fixed in the 2.18 series. + +- bug 234159: Bugzilla may sometimes send multiple notices in one email. + +- bug 237107: If you search for attachment information using the Boolean Charts + at the bottom of the Advanced Query page, bugs without attachments will not + show up in the result list. + + +Security Fixes In 2.18 Releases +******************************* + +Version 2.18 +------------ + +Summary: XSS in Internal Error messages in Bugzilla 2.16.7 and 2.18rc3 +CVE Name: CAN-2004-1061 +Reference: https://bugzilla.mozilla.org/show_bug.cgi?id=272620 +Details: + It is possible to send a carefully crafted URL to Bugzilla designed to +trigger an error message. The Internal Error message includes javascript code +which displays the URL the user is visiting. The javascript code does not +escape the URL before displaying it, allowing scripts contained in the URL to +be executed by the browser. Many browsers do not allow unescaped URLs to be +sent to a webserver (thus complying with RFC 2616 section 2.3.1 and RFC 2396 +section 2.4.3), and are thus immune to this issue. + Browsers which are known to be immune: Firefox 1.0, Mozilla 1.7.5, +Camino 0.8.2, Netscape 7.2, Safari 1.2.4 + Browsers known to be susceptible: Internet Explorer 6 SP2, +Konqueror 3.2 + Browsers not listed here have not been tested. + + +Version 2.18.1 +-------------- + +Two security issues were fixed in Bugzilla 2.18.1, neither of them +critical. + +See http://www.bugzilla.org/security/2.16.8/ for details. + + +Version 2.18.2 +-------------- + +Two security issues were fixed in Bugzilla 2.18.2. One of them +is a major Information Leak/Unauthorized Bug Change. The other +is a minor Information Leak. + +See http://www.bugzilla.org/security/2.18.1/ for details. + + +Detailed Version-To-Version Release Notes +***************************************** + +********************************************************* +*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.7 *** +********************************************************* + +*** Security fixes *** + +- It is possible to send a carefully crafted HTTP POST message to + process_bug.cgi which will remove keywords from a bug even if you don't have + permissions to edit all bug fields (the "editbugs" permission). Such changes + are reported in "bug changed" email notifications, so they are easily + detected and reversed if someone abuses it. Users are now prevented from + making changes to keywords if they do not have editbugs privileges. (bug + 252638) + +*** Bug fixes of note *** + +- Enforce a minimum of 10 minutes between attempts to reset a password, so + we don't mailbomb the user if someone submits the form many times in a + row. (bug 250897) + +- Put products in alphabetical order on the create attachment status page. + (bug 251427) + +- Specify MyISAM as the table type when creating new tables. MySQL 4.1 and + up default to InnoDB, which doesn't support some of the indexing methods + that we use. (bug 263165) + +********************************************************* +*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.6 *** +********************************************************* + +*** Security fixes *** + +- If Bugzilla is configured to hide entire products from some users, both + duplicates.cgi and the form for mass-editing a list of bugs in buglist.cgi + can disclose the names of those hidden products to such users. + (bugs 234825 and 234855) + +- Several administration CGIs echo invalid data back to the user without + escaping it. (bug 235265) + +- A user with privileges to grant membership to any group (i.e. usually an + administrator) can trick editusers.cgi into executing arbitrary SQL. + (bug 244272) + +*** Bug fixes of note *** + +- Allow XML import to function when there are regexp metacharacters in product + names (bug 237591) + +- Allow the bug_email.pl contrib script to work with useqacontact (bug 239912) + +- Improve the error message used by checksetup.pl when the MySQL requirements + are not met (bug 240228) + +- Elimnate the warning in checksetup.pl about the minimum sendmail version (bug + 240060) + +- $webservergroup now defaults to group 'apache' in new installations (bug + 224477) + +- Correct a situation where a bugmail message could be sent twice to a user + being added to the CC list if the address was entered in a different case + than the user registered with. (bug 117297) + +- Various documentation updates + +********************************************************* +*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.4 *** +********************************************************* + +*** Bug fixes of note *** + +- Fix a "used only once" warning that ocurred only in perl 5.00503 + (bug 2321691) + +- When a user is creating a new account and enters an invalid email + address, the error page sent the "Content-type" header twice, causing + the second one to be visible at the top of the page. + (bug 137121) + +- An HTML encoding issue which only affected Internet Explorer was + corrected in the "Change several bugs at once" page. + (bug 181106) + +- During initial setup, using invalid characters in the administrator + password would present an error message stating your password was + too long or too short instead of telling you it had invalid + characters. + (bug 166755) + +- When a user reset their own password via an emailed token, the new + password in the first field would be accepted if the second password + field was left blank. + (bug 123077) + +- Reopening bugs from the "change several bugs at once" page now works. + (bug 95430) + +- Fix a regression in xml.cgi caused by the previous bugfix for MySQL + SUM() changes. The original fix didn't work properly either. + (bug 225474) + +- No longer use server push with the "Safari" browser, which claims to + use the Mozilla layout engine but doesn't. + (bug 188712) + +- Creating a shadow database no longer fails with taint mode errors. + (bug 227510) + +- If you change your cookiepath setting at some stage (because you have + moved the directory Bugzilla resides on your webserver), users can + have login cookies with the old cookiepath, and their browsers will + send multiple logincookies. Bugzilla now uses the first rather than + the last in order to get the most specific cookie which will be the + correct one. + (bug 121419) + +- Fixed a regression caused by the previous DBD::mysql fixes, that + caused older versions of DBD::mysql to break due to not supporting + the new DBI syntax. + (bug 224815) + +- Bugzilla no longer sends out invalid dates for cookie expiry. This + bug had no known user visible ramifications. + (bug 228706) + +- Update the shadow database parameters description to tell the user + about permissions requirements for creating a shadow database. + (bug 227513) + +- Various documentation updates. + +********************************************************* +*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.3 *** +********************************************************* + +*** SECURITY ISSUES RESOLVED *** + +- A user with 'editproducts' privileges (i.e. usually an administrator) + can select arbitrary SQL to be run by the nightly statistics cron job + (collectstats.pl), by giving a product a special name. + (bug 214290) + +- A user with 'editkeywords' privileges (i.e. usually an administrator) + can inject arbitrary SQL via the URL used to edit an existing keyword. + (bug 219044) + +- When deleting products and the 'usebuggroups' parameter is on, the + privilege which allows someone to add people to the group which is + being deleted does not get removed, allowing people with that + privilege to get that privilege for the next group that is created + which reuses that group ID. Note that this only allows someone who + had been granted privileges in the past to retain them. + (bug 219690) + +- If you know the email address of someone who has voted on a secure + bug, you can access the summary of that bug even if you do not have + sufficient permissions to view the bug itself. + (bug 209376) + +*** Bug fixes of note *** + +Perl 5.8.0 Compatibility fixes: + +- Two taint errors were fixed, one in process_bug.cgi, and + another in post_bug.cgi. + (bugs 220332 and 177828) + +MySQL 4.0 Compatibility fixes: + +- A cosmetic fix was applied to votes.cgi (if there were no + votes, the "0" was not displayed) due to a change in semantics + in SUM() in MySQL 4.0. + (bug 217422) + +DBD::mysql > 2.1026 Compatibility fixes: + +- DBD::mysql versions after 2.1026 return the table list quoted, which + broke the existing "table exists" check in checksetup.pl, which caused + the second and subsequent attempts to run checksetup.pl to fail. + (bug 212095) + +Miscellaneous bug fixes: + +- A Mozilla-specific reference was removed from one of the report + templates. + (bug 221626) + +- It was possible to enter a situation where you were unable to get to + editparams.cgi to turn the shutdownhtml param back off after you + turned it on when Apache was configured to run Bugzilla in suexec + mode. + (bug 213384) + +- The processmail rescanall task would not send e-mails about more than + one bug to the same address. + (bug 219508) + +- If Bugzilla hadn't been accessed in the last hour when the + collectstats.pl or whineatnews.pl cron jobs ran, the versioncache + would get recreated with the file owner being the user the cron job + was running as (usually not the webserver user), causing subsequent + access to Bugzilla by the webserver to fail until the permissions were + fixed. Now if versioncache isn't readable when accessing from the + webserver, we pretend it doesn't exist and recreate it again. + (bug 160422) + +- The 'sendmailnow' param is now on by default in new installations + (this does not affect existing installations). + (bug 146087) + +- The 008filter.t test would fail if you had multiple language packs + installed. It now properly tests all of the installed language packs. + (bug 203318) + +- A few minor documentation changes were committed. + +********************************************************* +*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.2 *** +********************************************************* + +*** SECURITY ISSUES RESOLVED *** + +- A cross site scripting (XSS) vulnerability was fixed in which bug + summaries were not properly filtered when a user viewed a dependency graph + allowing JavaScript to be embedded on that page. + (bug 192661) + +- Several XSS vulnerabilities were fixed in which user + input was not escaped when being displayed. A new + test has been added to warn about unfiltered data in template + files (t/008filter.t). + (bug 192677) + +- An issue was fixed in which the QA contact was still treated as the QA + contact even after the 'useqacontact' setting was turned off. This also + allowed the QA contact to edit the security groups and view secured bugs that + he/she was allowed to access prior to the 'useqacontact' setting being + deactivated. + (bug 194394) + +- Fixed a situation where an attacker (with local access to the webserver) + could overwrite any file on the webserver to which the webserver user + has write access by creating appropriately named symbolic links in the + data and webdot directories (world-writable in many configurations). + Bugzilla now uses File::Temp to create secure temporary files. File::Temp + is part of the Perl distribution for Perl 5.6.1 and later, but if you're + using an older version of Perl you'll need to install it with CPAN. + (bug 197153) + +** IMPORTANT CHANGES *** + +- New module requirement: File::Temp, as mentioned above. + +*** Bug fixes of note *** + +- An issue was fixed in which administrator rights could be removed from an + administrator who deleted a product while the 'usebuggroups' setting is + activated. + (bug 157704) + +- Fixed an issue in which importxml.pl would fail the test suite when running + under perl 5.8.0 with the optional XML::Parse module. + (bug 172331) + +- There was previously a bug in CGI.pl in which the following warning + would be given under certain conditions: + "Character in "c" format wrapped at CGI.pl..." + This is now fixed. In some cases the warning was filling up web server log + files. + (bug 194125) + +- Fixed a bug in which long component names (in excess of 50 characters) would + be accepted when creating the component but would cause problems when trying + to use that component on a bug because it would get truncated. It is now no + longer possible to create components with names in excess of 50 characters. + (bug 197180) + +- Fixed a bug in checksetup.pl in which permissions were not being fixed + on the 'data/comments' file, the quip file. + (bug 160279) + +***************************************************************** +*** USERS UPGRADING FROM 2.16.1 OR EARLIER, 2.14.4 OR EARLIER *** +***************************************************************** + +*** SECURITY ISSUES RESOLVED *** + +- Fixed a cross site scriptability issue in quips. This is only a problem + if quips with HTML could have been inserted into your quips files. Bugzilla + has not allowed this since 2.12. + (bug 179329) +- checksetup.pl will now attempt to prevent access to "editor backups" of + localconfig. + (bug 186383) +- collectstats.pl no longer makes data/mining (which contains graphing + information) world writeable. + (bug 183188) + +*********************************************** +*** USERS UPGRADING FROM 2.16.0 OR EARLIER *** +*********************************************** + +*** SECURITY ISSUES RESOLVED *** + +- Apostrophes were not properly handled in email addresses. This was a + regression introduced in 2.16. It is not known whether this was + exploitable. + (bug 165221) + +See also next major section. + +*** Bug fixes of note *** + +- The VERSION cookie which allowed the previously entered version of a product + to be remembered was not correctly set. It was only set as a session + cookie, and under some circumstances could interfere with other cookies + (such as the login information) send at the same time. + (bug 160227) + +- importxml.pl would fail if the versioncache needed to be updated. + (bug 164464) + +- Bug changes going through intermediate pages would munge fields with + multiple fields, such as CCs. + (bug 161203) + +- On failure in template->new, Bugzilla will now die rather than futilely + attempt to use an error template. + (bug 166023) + +- Fixed a problem where checksetup had problems converting old installations + that didn't have a duplicates table. + (bug 151619) + +- Fixed a problem that caused taint errors when viewing or editing user + preferences with Perl 5.005 and Template 2.08. + (bug 160710) + +See also next section. + +****************************************************** +*** USERS UPGRADING FROM 2.16.0, 2.14.3 OR EARLIER *** +****************************************************** + +*** SECURITY ISSUES RESOLVED *** + +- When a new product is added to an installation with 47 groups or more and + "usebuggroups" is enabled, the new group will be assigned a groupset bit + using Perl math that is not exact beyond 2^48. This results in the new + group being defined with a "bit" that has several bits set. As users are + given access to the new group, those users will also gain access to + spurious lower group privileges. Also, group bits were not always reused + when groups were deleted. + (bug 167485) + +- The email interface had another insecure single parameter system call. This + could potentially allow arbitrary shell commands to be run. This file is + not supported at this time, but as long as we knew about the problem, we + couldn't overlook it. + (bug 163024) + +*** Bug fixes of note *** + +- The email interface was broken. This was a 2.14.3 regression. This file + is not supported at this time, but as long as we knew about the problem, we + couldn't overlook it. + (bug 160631) + +*********************************************** +*** USERS UPGRADING FROM 2.14.5 OR EARLIER *** +*********************************************** + +*** SECURITY ISSUES RESOLVED *** + +- The bug reporter could set the priority even when + 'letsubmitterchoosepriority' was off. + (bug 63018) + +- Most CGIs are now templatized. This helps to make it + easier to remember to HTML filter values and easier to spot + when they are not, preventing cross site scripting attacks. + (bug 86168) + +- Most CGIs now run in taint mode. This helps to prevent + failure to validate errors. + (bug 108982) + +*** IMPORTANT CHANGES *** + +- 2.16 introduces "templatization", a new feature that allows + administrators to easily customize the HTML output (the "look and feel") + of Bugzilla without altering Perl code. Bugzilla uses the + "Template Toolkit" for this. Please see the "Template Customization" + section of the Bugzilla Guide for more details. + + Administrators who ran the 2.15 development version with custom + templates should check the templates are still valid, as file names + and file paths have changed. + + Most output is now templatized. This process will be complete next + milestone. + + For speed, compiled templates are cached on disk. If you modify the + templates, the toolkit will normally detect the changes, and recompile the + changed templates. + + Adding new directories anywhere inside the template directory may cause + permission errors if you don't have a webservergroup specified in + localconfig. If you see these, rerun checksetup.pl as root. If you do not + have root access, or cannot get someone who does to do this for you, you can + rename the data/template directory to data/template.old (or any other name + Bugzilla doesn't use). Then rerun checksetup.pl to regenerate the compiled + templates. + (bug 86168, 97832) + +- Administrators can now configure maximum attachment sizes. These + should remain below the maximum size for your MySQL server, or you + will get obscure MySQL errors if you attach a bigger attachment. + + To find out the current size attachment that MySQL can accept, type + the command 'mysqladmin variables' and find out the value of the + 'max_allowed_packet' varible in bytes. + + To change the maximum size that MySQL can accept you can alter this + variable in your 'my.cnf' file. + (bug 91664) + +- Perl 5.004 is no longer supported because the Template Toolkit + requires 5.005. + (bug 97721) + +- New module requirements: Text::Wrap, Template [requires AppConfig], + File::Spec. + (bugs 97784, 84338, 103778) + +- The index page is now a CGI instead of an HTML page. You should remove + any existing index.html file and make sure your web server allows index.cgi + to be the default page in a directory. If you are not able to do that you + can instead set index_html in the 'localconfig' file to 1 and checksetup.pl + will create a redirect page for you. + (bug 80183) + +- It is now recommended that administrators run "processmail rescanall" + after upgrading to 2.16 or beyond. + + This will send out notification emails for changes that were + made but not emailed, due to Bugzilla bugs. All known + causes of this have been fixed in this version (bug 104589 and 99519). + + It is also recommended that this be run nightly to avoid + lengthy delays in future if this problem reoccurs. + (bug 106377) + +- In parallel with templatization, a lot of changes have been made to the HTML + output of the Bugzilla CGIs. This could break code that attempts to parse + such code. For example, this breaks mozbot. + (no bug number) + +- The "HTML template" parameters (headerhtml, bodyhtml, footerhtml, + errorhtml, bannerhtml, blurbhtml, mostfreqhtml, entryheaderhtml) have now + been moved to Template Toolkit templates. If you have modified these + parameters you will need to make corresponding changes to the corresponding + templates. Your old parameter values will be moved to a file called + old-params.txt by checksetup.pl. + + The old parameters correspond to files in template/en/default as follows: + + headerhtml: global/header.html.tmpl + footerhtml: global/footer.html.tmpl + bannerhtml: global/banner.html.tmpl + blurbhtml: global/banner.html.tmpl + mostfreqhtml: reports/duplicates*.html.tmpl + entryheaderhtml: bug/create/user-message.html.tmpl + + (bug 140437) + +*** Other changes of note *** + +- The query page has been redesigned for better user friendliness. + (bug 98707) +- Users can now change their email account. + (bug 23067) +- "Dependent Bug Changed" notification emails now contain the + dependent bug's summary and URL. + (bug 28736, 113383) +- Bugs with severity "critical", "blocker", and "enhancement" are + visually differentiated on bug lists for browsers with sufficient + CSS support. + (bug 28884) +- Bugzilla now has a sidebar for the Mozilla browser. + (bug 37339) +- A link to just created attachments now appears in notification + email. + (bug 66651) +- Comments now have numbers and can be referenced with + autohyperlinkifying similar to bugs. + (bug 71840) +- The attachment system has been rewritten, supporting new + "attachment statuses" (like keywords, but for attachments), + the ability to obsolete attachments, edit attachment MIME type, + and edit whether the attachment is a patch. + (bugs 84338, 75176) +- syncshadowdb now supports a configurable temp file location, + and properly shuts down Bugzilla while running. + (bug 75840) +- Dependency tree now lets you exclude resolved bugs and bugs + below a specified depth. + (bugs 83058) +- The "strictvaluechecks" parameter has gone away. These checks + are now always done. + (bug 119715) +- The midair collision page now shows all changes since the bug + page was loaded, not just the last one. + (bug 108312) +- Added support for making dependency graphs with 'dot', which + is better at creating complex graphs than 'webdot'. + (bug 120537) + +*** Bug fixes of note *** + +- Bugzilla scripts are now usually not terminated when the browser + window they are running in is closed. This caused hard to + reproduce bugs. + (bug 104589) +- On browsers that "reflow" the page, large component / milestone / + version fields were extremely slow to reflow when you altered + the product field. + (bug 96534) +- The selection in the component / milestone / version fields is + no longer lost when you change the selection in the product + field or use the back/forward buttons in your browser to return + to the page. + (bug 97966) +- You could not reverse dependencies in one step. + (bug 82143) +- Mass reassignment of non-open bugs will no longer reopen them. + (bug 30731) +- Attempting to bulk change no bugs will now give a user-friendly + error message. + (bug 90333) +- If you make a change to a bug where you only add yourself to CC, + email notifications are now properly sent out for MySQL 3.23. + (bug 99519) +- Bug entry now properly validates the data it has been sent. + (bug 107743) +- Midair collision checks will now properly work in all situations + where dependencies have changed. + (bug 73502) +- Browsers can no longer corrupt the params file if they use the "wrong" + end-of-line markers. + (bug 92500) +- The MySQL port defined in localconfig is now properly honoured. + (bug 98368) +- Apostrophes in component/milestone/version names no longer cause + a problem on the query page. + (bug 30689/42810) +- File attachment comments will now wrap. + (bug 52060) +- Saved queries are no longer mangled if you need to log in again, + for example if you had cookies off. + (bug 38835) +- Bug counts (on reports.cgi) were very slow if you had to + count a lot of bugs. + (bug 63249) +- 2.14 introduced options to let people see a bug when their name + is on it but who aren't in the groups the bug is restricted + to. These only allowed the people to view the bugs directly, + and not see them on buglists and receive email about them. + (bugs 95024, 97469) +- A new 'cookiepath' parameter on editparams.cgi allows multiple + Bugzilla installations to exist on one host without problems. + (bug 19910) +- whineatnews.pl now respects the 'sendmailnow' parameter. + (bug 52782) +- The query page came up even when Bugzilla was shut down. + (bug 121747) +- Quicksearch gave a weird error message when Bugzilla was + shut down. + (bug 121741) +- Operating system detection fixes. + (bugs 92763, 135666) +- QA contacts now receive emails when a new bug is created and + their only email preference was being added or removed from QA. + (bug 143091) + +*********************************************** +*** USERS UPGRADING FROM 2.14.4 OR EARLIER *** +*********************************************** + +See section above about users upgrading from 2.16.1 or earlier, +2.14.4 or earlier. + +*********************************************** +*** USERS UPGRADING FROM 2.14.3 OR EARLIER *** +*********************************************** + +See section above about users upgrading from 2.16.0 or earlier. + +*********************************************** +*** USERS UPGRADING FROM 2.14.2 OR EARLIER *** +*********************************************** + +*** SECURITY ISSUES RESOLVED *** + +- Basic maintenance on contrib/bug_email.pl and + contrib/bugzilla_email_append.pl which also fixes a + possible security hole with a misuse of a system() call. + These files are not supported at this time, but as long + as we knew about the problem, we couldn't overlook it. + (bug 154008) + +*** Bug fixes of note *** + +- The fix for bug 130821 in 2.14.2 broke being able to sort + bug lists on more than one field. buglist.cgi now allows + you to sort on more than one field again. + (bug 152138) + +*********************************************** +*** USERS UPGRADING FROM 2.14.1 OR EARLIER *** +*********************************************** + +*** SECURITY ISSUES RESOLVED *** + +- queryhelp.cgi no longer shows confidential products to + people it shouldn't. + (bug 126801) + +- It was possible for a user to bypass the IP check by + setting up a fake reverse DNS, if the Bugzilla web server + was configured to do reverse DNS lookups. Apache is not + configured as such by default. This is not a complete + exploit, as the user's login cookie would also need to + be divulged for this to be a problem. + (bug 129466) + +- In some situations the data directory became world writeable. + (bug 134575) + +- Any user with access to editusers.cgi could delete a user + regardless of whether 'allowuserdeletion' is on. + (bug 141557) + +- Real names were not HTML filtered, causing possible cross + site scripting attacks. + (bug 146447, 147486) + +- Mass change would set the groupset of every bug to be the + groupset of the first bug. + (bug 107718) + +- Some browsers (eg NetPositive) interacted with Bugzilla + badly and could have various form problems, including + removing group restrictions on bugs. + (bug 148674) + +- It was possible for random confidential information to be + divulged, if the shadow database was in use and became + corrupted. + (bug 92263) + +- The bug list sort order is now stricter about the SQL it will accept, + ensuring you use correct column name syntax. Before this, there were + some syntax checks, so it is not known whether this problem was + exploitable. + (bug 130821) + +******************************************** +*** USERS UPGRADING FROM 2.14 OR EARLIER *** +******************************************** + +The 2.14.1 release fixes several security issues that became +known to us after the Bugzilla 2.14 release. + +*** SECURITY ISSUES RESOLVED *** + +- If LDAP Authentication was being used, Bugzilla would allow + you to log in as anyone if you left the password blank. + (bug 54901) + +- It was possible to add comments or file a bug as someone else + by editing the HTML on the appropriate submission page before + submitting the form. User identity is checked now, and the + form values suggesting the user are now ignored. + (bug 108385, 108516) + +- The Product popup menu on the show_bug form listed all + products, even if the user didn't have access to all of them. + It now only shows products the user has access to (and the + product the bug is in, if the user is viewing it because of + some other override). + (bug 102141) + +- If a user had any blessgroupset privileges (the ability to + change only specific privileges for other users), it was + possible to change your own groupset (privileges) by + altering the page HTML before submitting on editusers.cgi. + (bug 108821) + +- An untrusted variable was echoed back to user in the HTML + output if there was a login error while editing votes. + (bug 98146) + +- buglist.cgi had an undocumented parameter that allowed you + to pass arbitrary SQL for the "WHERE" part of a query. + This has been disabled. + (bug 108812) + +- It was possible for a user to send arbitrary SQL by inserting + single quotes in the "mybugslink" field in the user + preferences. + (bug 108822) + +- buglist.cgi was not validating that the field names being + passed from the "boolean chart" query form were valid field + names, thus allowing arbitrary SQL to be inserted if you + edited the HTML by hand before submitting the form. + (bug 109679) + +- long_list.cgi was not validating that the bug ID parameter + was actually a number, allowing arbitrary SQL to be inserted + if you edited the HTML by hand. + (bug 109690) + +******************************************** +*** USERS UPGRADING FROM 2.12 OR EARLIER *** +******************************************** + +*** SECURITY ISSUES RESOLVED *** + +- Multiple instances of unauthorized access to confidential + bugs have been fixed. + (bug 39524, 39526, 39527, 39531, 39533, 70189, 82781) + +- Multiple instances of untrusted parameters not being + checked/escaped was fixed. These included definite security + holes. + (bug 38854, 38855, 38859, 39536, 87701, 95235) + +- After logging in passwords no longer appear in the URL. + (bug 15980) + +- Procedures to prevent unauthorized access to confidential + files are now simpler. In particular the shadow directory + no longer exists and the data/comments file no longer needs + to be directly accessible, so the entire data directory can + be blocked. However, no changes are required here if you + have a properly secured 2.12 installation as no new files + must be protected. + (bug 71552, 73191) + +- If they do not already exist, checksetup.pl will attempt to + write Apache .htaccess files by default, to prevent + unauthorized access to confidential files. You can turn this + off in the localconfig file. + (bug 76154) + +- Sanity check can now only be run by people in the 'editbugs' + group. Although it would be better to have a separate + group, this is not possible until the limitation on the + number of groups allowed has been removed. + (bug 54556) + +- The password is no longer stored in plaintext form. It will + be eradicated next time you run checksetup.pl. A user must + now change their password via a password change request that + gets validated at their e-mail account, rather than have it + mailed to them. + (bug 74032) + +- When you are using product groups and you move a bug between + products (single or mass change), the bug will no longer be + restricted to the old product's group (if it was) and will + be restricted to the new product's group. + (bug 66235) + +- There are now options on a bug to choose whether the + reporter, and CCs can access a bug even if they aren't in + groups the bug it is restricted to. + (bug 39816) + +- You can no longer mark a bug as a duplicate of a bug you + can't see, and if you mark a bug a duplicate of a bug + the reporter cannot see you will be given options as to + what to do regarding adding the reporter of the resolved + bug to the CC of the open bug. + (bug 96085) + +*** IMPORTANT CHANGES *** + +- Bugzilla 2.14 no longer supports old email tech. Upon + upgrading, all users will be moved over to new email tech. + This should speed up upgrading for installations with + a large number of bugs. + (bug 71552) + +- There is new functionality for people to see why they are + receiving notification mails. + + Previously, some people filtered old email tech + notifications depending on whether they were in the To or the + CC header, in order to get a limited way of determining why + they were receiving the notification for filtering purposes. + + Existing installations will need to make changes to support + this feature. The receive reasons can be added to the + notifications as a header and/or in the body. To add these + you will need to modify your newchangedmail parameter on + editparams.cgi, either by resetting it or appropriately + modifying it. The header value is specified by + %reasonsheader% and the body by %reasonsbody%. For example, + the new default parameter is: + + -------------------------------------------------- + From: bugzilla-daemon + To: %to% + Subject: [Bug %bugid%] %neworchanged%%summary% + X-Bugzilla-Reason: %reasonsheader% + + %urlbase%show_bug.cgi?id=%bugid% + + %diffs% + + + + %reasonsbody% + -------------------------------------------------- + + (bug 26194) + +- Very long fields (especially multi-valued fields like keywords, + CCs, dependencies) on bug activity and notifications previously + could get truncated, resulting in useless notifications and data + loss on bug activity. Now the multi-valued fields only show + changes, and very big changes are split into multiple lines. + Where data loss has already occurred on bug activity, it is + indicated using question marks. + (bug 55161, 92266) + +- Previously, when a product's voting preferences changed all + votes were removed from all the bugs in the product. Also, + when a bug was moved to another product, all of its votes + were removed. This no longer occurs. + + Instead, if the action would leave one or more bugs with + greater than the maximum number of votes per person per bug, + the number of votes will be reduced to the maximum. The + person will still be notified of this as before. + + If the action would leave a user with more votes in a product + than is allowed, the limit will be breached so as to not lose + votes. However the user will not be able to update their + votes except to fix this situation. No further action is taken + in this version to make sure that the user does this. + (bug 28882, 92593) + +*** Other changes of note *** + +- Groups can now be marked inactive, so you can't add a new + restriction on that group to a bug, while leaving bugs that + were previously restricted on that group alone. + (bug 75482) +- backdoor.cgi has been removed from the installation. It was + old code that was Netscape-specific and its name was scaring + people. + (bug 87983) +- You can now add or remove from CC on the bulk change page. + (bug 12819) +- New users created by administrators are now automatically + inserted into groups according to the group's regular + expression. Administrators must edit the user in a second + step to override these choices. Previously the + administrator specified these explicitly which could lead + to incorrect settings. + (bug 45164) +- The userregexp of system groups can now be edited without + resorting to direct database access. + (bug 65290) + +*** Bug fixes of note *** + +- The bug list page was sometimes bringing up a not logged in + footer when the user was logged in and the installation was + using a shadow database. + (bug 47914) +- You can now view the bug summary in your browser title for + a group-restricted bug if you have proper permissions. + (bug 71767) +- Quick search for search terms did not work in IE5. + This has been worked around. + (bug 77699) +- Quick search for search terms crashed NN4.76/4.77 for Unix. + This has been worked around. + (bug 83619) +- Queries on bugs you have commented on using the "added + comment" feature should be a lot faster and not time out + on large installations due to the addition of an index. + (bug 57350) +- You can now alter group settings on bulk change for groups + that aren't on for all bugs or off for all bugs. + (bug 84714) +- New bug notifications now include the CC and QA fields. + (bug 28458) +- Bugzilla is now more Windows friendly, although it is still + not an official platform. + (bug 88179, 29064) +- Passwords are now encrypted using Perl's encrypt function. + This makes Bugzilla more portable to more operating systems. + (bug 77473) +- Bugzilla didn't properly shut down when told to - some + queries could still be sent to the database. + (bug 95082) + +******************************************** +*** USERS UPGRADING FROM 2.10 OR EARLIER *** +******************************************** + +*** SECURITY ISSUES RESOLVED *** + +- Some security holes have been fixed where shell escape characters + could be passed to Bugzilla, allowing remote users to execute + system commands on the web server. + +*** IMPORTANT CHANGES *** + +- There is now a facility for users to choose the sort of + notifications they wish to receive. This facility will + probably be improved in future versions. + (bug 17464) + +- "Changed" will no longer appear on the subject line of + change notification emails. Because of this, you should + change the subject line in your 'changedmail' and + 'newchangedmail' params on editparams.cgi. The subject + line needs to be changed from + + Subject: [Bug %bugid%] %neworchanged% - %summary% + + to: + + Subject: [Bug %bugid%] %neworchanged%%summary% + + or whatever is appropriate for the subject you are using + on your system. Note the removal of the " - " in the + middle. + (bug 29820) + +*** Other changes of note *** + +- Bug titles now appear in the page title, and will hence + display in the user's browser's bookmarks and history. + (bug 22041) +- Edit groups functionality (editgroups.cgi). + (bug 25010) +- Support for moving bugs to other Bugzilla databases. + (bug 36133) +- Bugzilla now can generate a frequently reported bugs list + based on what duplicates you receive. + (bug 25693) +- When installing Bugzilla fresh, the administrator account is + now created in checksetup.pl. + (bug 17773) +- Stored queries now show their name above the bug list, which + helps the user when they have multiple bug lists in multiple + browser windows. It also appears in the page title, and will + hence display in the user's browser's bookmarks and history. + (bug 52228) +- All states and resolutions can now be collected for charting. + (bug 6682) +- A new search-engine-like "quick search" feature appears on + the front page to try and making searching easier. + (bug 69793) +- Querying on dependencies now works in the advanced query + section of the query page. + (bug 30823) +- When a bug is marked as a duplicate, the reporter of the + resolved bug is automatically added to the CC list of the + open bug. + (bug 28676) + +*** Bug fixes of note *** + +- Notification emails will now always be sent to QA contacts. + Previously they wouldn't if you were using new email tech. + (bug 30826) +- When marking a bug as a duplicate, the duplicate stamp marked + on the open bug will no longer be written too early (such as + on mid-air collisions). + (bug 7873) +- Various bug fixes were made to the initial assignee and QA + of a component. It is no longer possible to enter an + invalid address. They will also now properly update when + a user's email address is changed. Sanity check will now + check these. + (bug 66876) +- Administrators can no longer create an email accounts that do + not match the global email regular expression parameter. + Previously this could occur and would cause sanity check + errors. + (bug 32971) +- The resolution field can no longer become empty when the + bug is resolved. This occurred because of midair collisions. + (bug 49306) + +******************************************* +*** USERS UPGRADING FROM 2.8 OR EARLIER *** +******************************************* + +This version of Bugzilla cannot upgrade from version 2.8 (released +November 19, 1999). You will first have to upgrade to Bugzilla 3.6 and +then upgrade to the latest release. + +If you are upgrading from a version earlier than 2.8, See the +PGRADING-pre-2.8 file in Bugzilla 3.0 for information +on upgrading from a version that is earlier than 2.8. diff --git a/docs/en/images/callouts/1.gif b/docs/en/images/callouts/1.gif deleted file mode 100644 index 79fd388a8..000000000 Binary files a/docs/en/images/callouts/1.gif and /dev/null differ diff --git a/docs/en/images/callouts/2.gif b/docs/en/images/callouts/2.gif deleted file mode 100644 index b9be050e4..000000000 Binary files a/docs/en/images/callouts/2.gif and /dev/null differ diff --git a/docs/en/images/callouts/3.gif b/docs/en/images/callouts/3.gif deleted file mode 100644 index 73635e3f7..000000000 Binary files a/docs/en/images/callouts/3.gif and /dev/null differ diff --git a/docs/en/images/caution.gif b/docs/en/images/caution.gif deleted file mode 100644 index a48223013..000000000 Binary files a/docs/en/images/caution.gif and /dev/null differ diff --git a/docs/en/images/note.gif b/docs/en/images/note.gif deleted file mode 100644 index 613bc7f70..000000000 Binary files a/docs/en/images/note.gif and /dev/null differ diff --git a/docs/en/images/tip.gif b/docs/en/images/tip.gif deleted file mode 100644 index c8d5ae9bd..000000000 Binary files a/docs/en/images/tip.gif and /dev/null differ diff --git a/docs/en/images/warning.gif b/docs/en/images/warning.gif deleted file mode 100644 index 693ffc3e8..000000000 Binary files a/docs/en/images/warning.gif and /dev/null differ diff --git a/docs/en/make.bat b/docs/en/make.bat new file mode 100644 index 000000000..5c1494bf7 --- /dev/null +++ b/docs/en/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=. +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% rst +set I18NSPHINXOPTS=%SPHINXOPTS% rst +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Bugzilla.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Bugzilla.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/txt + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/txt. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/en/rel_notes.txt b/docs/en/rel_notes.txt deleted file mode 100644 index 4014951f0..000000000 --- a/docs/en/rel_notes.txt +++ /dev/null @@ -1,3028 +0,0 @@ -Release Notes for Bugzilla version 3.0 and higher are available in HTML -format, either on the bugzilla.org website, or in your current installation, -linked from the index page. - -bugzilla.org links for release notes ------------------------------------- -3.0.2: http://www.bugzilla.org/releases/3.0.2/release-notes.html - -*************************************** -*** The Bugzilla 2.22 Release Notes *** -*************************************** - -Table of Contents -***************** - -- Introduction -- Important Updates In This Point Release -- Minimum Requirements - * Perl - * For MySQL Users - * For PostgreSQL Users - * Required Perl Modules - * Optional Perl Modules -- What's New? - * Complete PostgreSQL Support - * Parameters In Sections - * One Codebase, Multiple Databases - * UTF-8 for New Installations - * Admins Can Impersonate Users - * Bug Import and Moving Improvements - * Adding Individual Bugs to Saved Searches - * Attach URLs - * Optional "Strict Isolation" for Groups - * "editcomponents" Change - * "shutdownhtml" Change - * Miscellaneous Improvements - * All Changes -- Deprecated Features -- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) -- How to Upgrade From An Older Bugzilla - * Steps for Upgrading -- Code Changes Which May Affect Customizations - * CGI.pl is Gone - * Other Changes -- Security Fixes In 2.22 Releases -- Release Notes for Previous Versions - -Introduction -************ -Bugzilla 2.22 is one of our most polished releases. We did a lot of -small cleanups to make Bugzilla easier to use and more useful in -many, many small ways, in addition to adding some major new features. - -This document contains the release notes for Bugzilla 2.22. -In this document, recently added, changed, and removed features -of Bugzilla are described. If you are upgrading from an older version, -you will definitely want to read these release notes in detail, so that -you have an idea of what has changed. - -If you are upgrading from a version before 2.20, also read the 2.20 -release notes (lower in this file) and any previous release notes. - -If you are installing a new Bugzilla, you will still want to look over -the release notes to see if there is any particularly important -information that affects your installation. - -If you would like to contribute code to Bugzilla, read our -Contributor's Guide at: - -http://www.bugzilla.org/docs/contributor.html - - -Important Updates In This Point Release -*************************************** - -This section describes bugs fixed in releases after the original 2.22 -release. - -Version 2.22.2 --------------- - -+ Make Bugzilla compatible with Template Toolkit 2.15 (bug 357374) - -+ Make Bugzilla compatible with versions of MySQL higher than 5.0.25 - (bug 321645) - -+ Sanity Check can now only be run by people with the "admin" privilege. - (bug 91761) - -Version 2.22.1 --------------- - -+ When sending mail, Bugzilla could throw the error "Insecure dependency in - exec while running with -T switch" (bug 340538). - -+ Using the public webdot server (for dependency graphs) should work - again (bug 351243). - -+ The "I'm added to or removed from this capacity" email preference - wasn't working for new bugs (bug 349852). - -+ The original release of 2.22 incorrectly said it required Template-Toolkit - version 2.08. In actual fact, Bugzilla requires version 2.10 (bug 351478). - -+ votes.cgi would crash if your bug was the one confirming a bug (bug 351300). - -+ checksetup.pl now correctly reports if your Template::Plugin::GD module - is missing. If missing, it could lead to charts and graphs not working - (bug 345389). - -+ The "Keyword" field on buglist.cgi was not sorted alphabetically, so - it wasn't very useful for sorting (bug 342828). - -+ Sendmail will no longer complain about there being a newline in the - email address, when Bugzilla sends mail (bug 331365). - -+ contrib/bzdbcopy.pl would try to insert an invalid value into the - database, unnecessarily (bug 335572). - -+ Deleting a bug now correctly deletes its attachments from the database - (bug 339667). - - -Minimum Requirements -******************** - -Perl ----- - - Perl v5.6.1 (Non-Windows platforms) - ActiveState Perl v5.8.1 (Windows only) - - Note that this is the last release of Bugzilla to support perl 5.6.x-- - future versions will require perl 5.8. - -For MySQL Users ---------------- - - MySQL v4.0.14 (changed from 2.20) - perl module: DBD::mysql v2.9003 (changed from 2.18) - -For PostgreSQL Users --------------------- - - PostgreSQL 7.3.x - perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+) - - WARNING: DBD::Pg 1.43 has a bug which causes checksetup.pl to fail - and corrupt the database. If you are using DBD::Pg 1.43, either downgrade - to 1.41 or upgrade to 1.45 (1.42 and 1.44 seem broken somehow too). - - Note that this is the last release of Bugzilla to support PostgreSQL 7.x. - Future versions will require PostgreSQL 8.0 and DBD::Pg 1.45. - -Required Perl Modules ---------------------- - - AppConfig v1.52 - CGI v2.93 - Data::Dumper (any) - Date::Format v2.21 - DBI v1.38 - File::Spec v0.84 - File::Temp (any) - Template Toolkit v2.10 (changed from 2.20) - Text::Wrap v2001.0131 - Mail::Mailer v1.67 (changed from 2.20) - MIME::Base64 v3.01 (new in 2.22) - MIME::Parser v5.406 (new in 2.22) - Storable (any) - - Note: The SMTP support in Mail::Mailer 1.73 (the most recent version) - is broken. The last known working version is 1.67. - -Optional Perl Modules ---------------------- - - Chart::Base v1.0 - GD v1.20 - GD::Graph (any) - GD::Text::Align (any) - Net::LDAP (any) - PatchReader v0.9.4 - XML::Twig (any) (new in 2.22) - Image::Magick (new in 2.22) - - -What's New? -*********** - -Complete PostgreSQL Support ---------------------------- -Bugzilla 2.20 contained experimental support for PostgreSQL. -In Bugzilla 2.22, PostgreSQL support is fully complete and stable. Using -PostgreSQL with Bugzilla should be as stable as using MySQL, and if -you experience any problems they will be taken as seriously as if you -were running MySQL. - -There are no known remaining major problems with Bugzilla on PostgreSQL. -All features of Bugzilla have been tested and work. - - -Parameters In Sections ----------------------- -Long-time users of Bugzilla know that over time the parameter list has -grown quite large. It has now been split into sections to make it easier -to use. - - -One Codebase, Multiple Databases --------------------------------- -There is now limited support for having multiple projects use the -same Bugzilla codebase, but all have separate databases. - -The different projects can have their own templates and their own -bug database, but all use the same set of Bugzilla code in the same -directory. - -To enable this, set an environment variable called PROJECT when -calling the Bugzilla CGIs. Then for each project, you can have -a localconfig.PROJECT (where "PROJECT" is the value of the PROJECT -environment variable) file for the database parameters, and a -template/en/PROJECT directory (where "PROJECT" is the value of the -PROJECT environment variable) - -This feature isn't documented yet, but we hope to have documentation for -it soon. - - -UTF-8 For New Installations ---------------------------- -If this is the first time you're installing Bugzilla, it will now use -UTF-8 encoding for all pages, automatically. It will also send emails -in UTF-8. This eliminates most of the internationalization problems -users have experienced, as one Bugzilla page may now contain any number -of languages simultaneously. - -If you are upgrading and you want to use UTF-8, just turn on the "utf8" -Parameter. However, realize that if you have non-UTF-8 data in your -Bugzilla, it will appear unreadable. (If you just have ASCII in your -database, you're safe to turn on the "utf8" parameter, definitely.) - - -Admins Can Impersonate Users ----------------------------- -User impersonation (think of the su/sudo command on Unix) allows you -to view pages and perform actions as if you are logged in as someone else, -without having to know their password. - -A user in the new "bz_sudoers" group has the option of "becoming" -any user in Bugzilla. Once they "become" that user, they *are* that user -for the rest of the session, until they decide to switch back to being -themselves. - -However, they cannot "become" any user in the "bz_sudo_protect" group. -This group includes everybody in the "admin" and "bz_sudoers" groups by -default. - -Any time a user is impersonated, they will get an email notifying them -who has impersonated them. - - -Bug Import and Moving Improvements ----------------------------------- -The XML Import script, importxml.pl, has been completely re-written. - -It now: - - * Correctly imports the "priority" field - * Understands when the "Reporter" or "CC List" security boxes - are unchecked on the bug. - * Places bugs in the appropriate groups - * Allows attachments to be imported - * Is much more forgiving about small problems in the XML - - -Adding Individual Bugs to Saved Searches (Tagging) --------------------------------------------------- -Users now have the option of adding an individual bug to any -particular Saved Search. Individual users that disagree with the site -default can add or remove this feature (which appears as an entry box -visible in the footer) by changing the General Preferences setting -called "Enable tags for bugs". - - -Attach URLs ------------ -Instead of attaching a file, you can now also attach a URL to a bug. -This will show up just like an attachment on show_bug.cgi, but when -you click on it, it will take you to the URL. - -To enable this, turn on the "allow_attach_url" parameter. - - -Optional "Strict Isolation" for Groups --------------------------------------- -If you turn on the "strict_isolation" parameter in Bugzilla, you -will *not* be able to add any user to the CC field (or set them -as an Assignee or QA Contact) unless that user could normally see -the bug. That is, you will no longer be able to "accidentally" -(or intentionally) give somebody access to a bug that they -otherwise couldn't see. - - -"editcomponents" Change ------------------------ -Previously, all users who had "editcomponents" could see every Product, -using the editcomponents.cgi script. Now, users with "editcomponents" -can only see Products that they normally have access to. - -This restriction also affects editversions.cgi, editmilestones.cgi and -editproducts.cgi. - - -"shutdownhtml" Change ---------------------- -All of Bugzilla is now affected by the "shutdownhtml" parameter, -including command-line scripts. checksetup.pl is exempt. Many scripts -(such as collectstats.pl and whine.pl) will just exit silently when -"shutdownhtml" is turned on. - - -Miscellaneous Improvements --------------------------- - -- Added a frequently-requested user preference for whether or not to go - to the next bug in your list after submitting changes to a bug. - -- The ability to do relative date searches (like "1d" for "1 day" or "1w" - for "1 week") by hour now, in addition to days and other units of time. - -- "Alias" added to the New Bug form, for users with editbugs. - -- Users can now actually see the descriptions of flags that you enter - in editflagtypes.cgi. The description will appear as a tooltip - when a user places their mouse over the flag name on show_bug.cgi. - -- Bugzilla will optionally convert BMP attachments into PNGs for you. - See the "convert_uncompressed_images" in the "Attachments" section - of the Parameters. - -- You can now edit the Status Whiteboard when you are changing multiple - bugs at once. - -- The way that groups work in the database has changed, and large-scale - Bugzilla use with many concurrent users should be much faster, as a - result. (Technical Details: The need for Bugzilla to "derive groups" - has gone away pretty much entirely.) - -- Performance improvements on searching attachment information that's not - the actual content of the attachment (such as searching the Attachment - Description or the Attachment MIME Type) - -- You can now specify multiple email addresses, comma-separated, when - setting the requestee of a flag, and it will set the flag once for each - of those email addresses - -- "Bug Creation Time" is now searchable in the Boolean Charts. - -- When you mark a comment on a bug as private, the background color - of the comment will change immediately. However, in order for - Bugzilla to register that the comment is now private, you still - have to "submit" the changes. - -- Emails sent from Bugzilla now have "X-Bugzilla-Keywords" and - "X-Bugzilla-Severity" by default, containing the information - from the related Bugzilla fields. - -- You can now change the assignee and QA contact on multiple bugs at - once even when those bugs are in different products. - -- contrib/merge-users.pl allows you to merge two user accounts. This is - particulary useful when a user opened several accounts and only one should - be kept. It also lets you merge a deleted account with an existing one. - -All Changes ------------ - -If you'd like to see all the changes between Bugzilla 2.20 and Bugzilla -2.22, see: - -http://tinyurl.com/9p2tm - - -Deprecated Features -******************* - -- This is the last release of Bugzilla to support perl 5.6.x. All future - versions of Bugzilla will require at least perl 5.8. - - This is the last release of Bugzilla to support PostgreSQL 7.x. Future - releases using PostgreSQL will require PostgreSQL 8.0 and DBD::Pg 1.45. - -Outstanding Issues -****************** - -- bug 305836: PostgreSQL users: do not use DBD::Pg version 1.43 with - Bugzilla. It has a bug which can corrupt the database. Version 1.41 - is fine. Version 1.45 or higher is fine too. - -- (No Bug Number) VERY IMPORTANT: If you have customized the values in - your Status/Resolution field, you must edit checksetup.pl BEFORE YOU - RUN IT. Find the line that starts like this: - - bug_status => ["UNCONFIRMED", - - That's where you set the values for the Status field. - - resolution => ["","FIXED", - - And that's where you set values for the Resolution field. - - Those are both near line 1826 in checksetup.pl. - - If you forget to do this, you will have to manually edit the "bug_status" - and "resolution" tables in the database to contain the correct values. - -- bug 276230: The support for restricting access to particular Categories of - New Charts is not complete. You should treat the 'chartgroup' Param as the - only access mechanism available. However, additionally, charts migrated from - Old Charts will be restricted to the groups that are marked MANDATORY for - the corresponding Product. There is currently no way to change this - restriction, and the groupings will not be updated if the group configuration - for the Product changes. - -- bug 37765: If you use the "sendmail" support of Bugzilla, - and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.) - make sure the "sendmailnow" parameter is ON or Bugzilla will not send - e-mail correctly. - -- bug 69621: If you rename or remove a keyword that is in use on bugs, you will - need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing - the option to rebuild the cache when it asks. Otherwise keywords may not show - up properly in search results. - -- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for - example, if you use a translation of Bugzilla), don't enable the XS::Stash - option when you install the Template Toolkit, or your Bugzilla installation - may become slow. This problem is fixed in a not-yet-released version of the - Template Toolkit (after 2.14). - -- Bug 99215: Flags are not protected by "mid-air collision" detection. - Nor are any attachment changes. - -- Bug 89822: When changing multiple bugs at the same time, there is no - "mid-air collision" protection. - -- bug 322955: The email interface (bug_mail.pl) in the contrib/ directory - has not been maintained (as it has no maintainer), and does not work - properly. We hope to have this fixed in our next major release of - Bugzilla; however, any help or contributions in this area are very - welcome. - - -How to Upgrade From An Older Bugzilla -************************************* - -NOTE: Upgrading from a large installation (over 10,000 bugs) running 2.18 - or before may take a significant amount of time. checksetup will - try to let you know how long it will take, but expect downtime - of an hour or more if you have many bugs, many attachments, - or many users. - -Steps for Upgrading -------------------- - -1) Read these entire Release Notes, particularly the "Outstanding Issues" - and "Security Fixes" sections. - -2) View the Sanity Check (sanitycheck.cgi) page on your installation before - upgrading. Attempt to fix all warnings that the page produces before - you go any further, or you may experience problems during your upgrade. - -3) Make a backup of the Bugzilla database before you upgrade, perhaps - by using mysqldump. THIS IS VERY IMPORTANT. If anything goes wrong - during the upgrade, your installation can be corrupted beyond - recovery. Having a backup keeps you safe. - - Example: - - mysqldump -u root -p bugs > bugs-db.sql - -4) Replace the files in your installation with the new version of Bugzilla, - or you can try to use CVS to upgrade. The bugzilla.org website has - instructions on how to do the actual installation. - - You can also use a brand-new Bugzilla directory, as long as you - copy over the old data/ directory and the "localconfig" file to the - new installation. - -5) Run checksetup.pl after you install the new version. - -7) View the Sanity Check page again after you run checksetup.pl. - -8) It is recommended that, if possible, you fix any problems you find - immediately. Failure to do this may mean that Bugzilla will not work - correctly. Be aware that if the sanity check page contains more errors after - an upgrade, it doesn't necessarily mean there are more errors in your - database, as additional tests are added to the sanity check over time, and - it is possible that those errors weren't being checked for in the old - version. - -9) This version of Bugzilla contains improvements to the email that - Bugzilla sends when a bug is changed. The template for that email - is contained in the "newchangedmail" parameter. If you would like - to take advantage of the email enhancements in this version of - Bugzilla, reset that parameter to its default. (You can customize - it after that again, if you want.) - - -Code Changes Which May Affect Customizations -******************************************** - -CGI.pl is Gone --------------- -The CGI.pl file, which used to contain many global functions, and which -also contained initialization code for every CGI, is gone. The functions -have been moved to various places and sometimes renamed. - -The initialization code that used to happen inside CGI.pl is now inside -of Bugzilla.pm. All CGIs must "use Bugzilla" in one way or another. (Some -CGIs "use Bugzilla" by doing "require globals.pl".) - - -Deriving Groups No Longer Happens ---------------------------------- -Bugzilla no longer needs to "derive groups" in advance. That is, previously -Bugzilla used to flatten the group heirarchy into the user_group_map -table. (That is, show that a user was in every group they were in, -even if they were only in that group because they belonged to *another* -group.) Now the table only contains groups that the user is in directly, -and groups that they are in because of a regexp. - -Instead, The Bugzilla::User->group function determines the groups a user -is in when called. - -We did this because the group derivation was causing a lot of complexity -in the code, and also deriving the groups was a slow process that -frequently had to happen inside of a database lock while sending mail -or viewing a bug list. - -See https://bugzilla.mozilla.org/show_bug.cgi?id=304583 for details. - - -Other Changes -------------- - -- The move.pl script's functionality has been merged into process_bug.cgi. - -- $::template and $::vars are gone from globals.pl. Instead of $::template, - use Bugzilla->template. Every script creates the $vars variable by itself - instead of using a global $::vars variable. - -- $::userid is gone. Instead use Bugzilla->user->id. - -- QuickSearch is now in perl instead of in JavaScript. The code is in - Bugzilla/Search/QuickSearch.pm. This makes it much easier to customize, - and it also fixes some long-standing issues that QuickSearch had. - -- Attachment data is now in the attach_data table. Other information - about attachments is still in the "attachments" table. - -- Much like the 2.20 release, many functions have been removed from - globals.pl and CGI.pl. They were moved elsewhere and renamed. - Search RESOLVED bugs in bugzilla.mozilla.org for the old - version of the function name, and that will usually show you - the bug where we moved the function, allowing you to find out - what the new name and location is. - -- This is the last release that contains the deprecated - SendSQL, SqlQuote, FetchSqlData, MoreSqlData, and FetchOneColumn - functions. Instead, you should use DBI functions. For a very brief - example, see: - - http://www.bugzilla.org/docs/developer.html#sql-sendreceive - - -Security Fixes in 2.22 Releases -******************************* - -A long-standing, well-known security issue is finally resolved in Bugzilla -2.22: Previously, the "Session ID" of each user could be easily guessed, -given enough time. This could have allowed an attacker to take over a -user's account, in certain circumstances. Now, the "Session ID" is totally -random, resolving this issue. See bug 119524 in bugzilla.mozilla.org for -details. - -If you are very concerned about the security of your Bugzilla installation, -it would be a very good idea to run the following command on your -database immediately after upgrading: - -TRUNCATE TABLE logincookies; - -This is actually safe to do at any time--it just forces a logout of -every single user, even those with saved sessions. (It invalidates -every login cookie Bugzilla has ever given out.) - -Version 2.22.2 --------------- - -A Cross-Site Scripting vulnerability is fixed in Bugzilla 2.22.2. You can -read the details of the fix at: - -http://www.bugzilla.org/security/2.20.3/ - -Version 2.22.1 --------------- - -The Bugzilla team fixed two Information Leaks and three Cross-Site -Scripting vulnerabilities that existed in versions of Bugzilla -prior to 2.22.1. We strongly recommend that you update any 2.22 -installation to 2.22.1, to be protected from these vulnerabilities. - -In addition, we have made an enhancement to security in this version -of Bugzilla. In previous versions, it was possible for malicious -users to exploit administrators in certain ways. Although this has -never happened (to our knowledge) in the real world, we thought it -was important that we protect administrators from this sort of attack. - -You can see details on all the vulnerabilities and enhancements at: - -http://www.bugzilla.org/security/2.18.5/ - - -Release Notes For Previous Versions -************************************ - -*************************************** -*** The Bugzilla 2.20 Release Notes *** -*************************************** - -Table of Contents -***************** - -- Introduction -- Important Updates in this Point Release - * Version 2.20.1 - * Version 2.20.2 -- Minimum Requirements - * Perl - * For MySQL Users - * For PostgreSQL Users - * Required Perl Modules - * Optional Perl Modules -- What's New? - * Experimental PostgreSQL Support - * New User-Interface Color/Style - * Higher-Level Categorization of Bugs (above "Product") - * Regular Reports by Email of Complex Queries ("Whining") - * "Environment Variable" Authentication Method - * User-List Drop-Down Menus - * Server-Side Comment Wrapping - * UI for Editing Priority, OS, Platform, and Severity - * Bugzilla Queries as RSS - * Choice of E-Mail Sending Methods - * "User Preferences" - * "Large Attachment" Storage - * "User Visibility" Controls - * Miscellaneous Improvements - * All Changes -- Deprecated Features -- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) -- How to Upgrade From An Older Bugzilla - * Steps for Upgrading -- Code Changes Which May Affect Customizations - * The New Database-Compatibility Layer - * If You Customize Your Database... - * Many Functions Renamed - * User Preferences - * Other Changes -- Security Fixes In 2.20 Releases -- Release Notes for Previous Versions - - -Introduction -************ - -This document contains the release notes for Bugzilla 2.20. -In this document, recently added, changed, and removed features -of Bugzilla are described. If you are upgrading from an older version, -you will definitely want to read these release notes in detail, so that -you have an idea of what has changed. - -If you are upgrading from a version before 2.18, also read the 2.18 release -notes (lower in this file) and any previous release notes. - -If you are installing a new Bugzilla, you will still want to look over -the release notes to see if there is any particularly important information -that affects your installation. - -The 2.20 release has had about nine months of development since 2.18, but -they were nearly the most active nine months in Bugzilla's history. We hope -that users will appreciate our many external changes, and that Bugzilla -administators will find that our internal changes make their lives easier. - -If you would like to contribute code to Bugzilla, read our -Contributor's Guide at: - -http://www.bugzilla.org/docs/contributor.html - - -Important Updates In This Point Release -*************************************** - -Version 2.20.1 --------------- - -+ Many PostgreSQL fixes, including fixing whine.pl on Pg 8 - (bug 301062) and fixing the --regenerate option of collectstats.pl - for all versions of Pg (bug 316971). However, users who want full - PostgreSQL support are encouraged to use the 2.22 series, as - certain PostgreSQL bugs were discovered that will not be fixed - in 2.20 (their fixes were too complex). - -+ In Bugzilla 2.20, the "administrator" user created by checksetup.pl - would not ever be sent email, because their email preferences were - left blank. This has been fixed for 2.20.1. However, if you created - this administrative user with Bugzilla 2.20, make sure to go back - and enable their Email Preferences. (bug 317489) - -+ The bzdbcopy.pl script mentioned in these release notes - has now actually been checked-in to the 2.20 branch, and so - it's included in this release. (bug 291776) - -+ When there's only one Classification, you now won't be required - to pick a Classification on bug entry. (bug 311489) - -+ You can no longer add dependencies on bugs you can't see. - (bug 141593) - -+ The CC list is included in "New" bug emails, again. (bug 313661) - -+ In the original 2.20, certain scripts were not correctly using - the "shadow database," if it was specified. This has been fixed - in 2.20.1. (bug 313695) - -+ "Saved Searches" that were saved before Bugzilla 2.20, would throw - an error if they contained "Days Since Bug Changed." as part of their - criteria. This has been fixed in Bugzilla 2.20.1. (bug 302599) - -+ You can now successfully delete a product even when Target Milestones - are turned off. (bug 317025) - -+ checksetup.pl now correctly pre-compiles templates for languages other - than English. (bug 304417) - -+ The "All Closed" chart that is created by default in New Charts - now actually represents all closed bugs, and not all bugs in the - product. (bug 300473) - -+ CSV bug lists with more than 1000 dates now work properly. (bug 257813) - -+ Various bugs with upgrading from previous versions of Bugzilla - have been fixed. (bug 307662, bug 311047, bug 310108) - -+ Many, many other bug fixes. See http://www.bugzilla.org/status/changes.html - for details on what was fixed between 2.20 and 2.20.1. - - -Version 2.20.2 --------------- - -+ Adding a new attachment and taking the bug at the same time does not - create a referential integrity problem anymore if the bug was marked as - a duplicate (bug 332705). - -+ Some additional admin links have been added to the sidebar (bug 282613). - -+ A new test has been added to our test suite, named 012throwables.t. - It will now make sure that all tags used in ThrowUserError() and - ThrowCodeError() are defined, and that there are no unused tags (bug 312042). - -+ whine.pl now works correctly on MySQL 4.0. MySQL 4.1 is not affected - (bug 327348). - -+ contrib/merge-users.pl allows you to merge two user accounts. This is - especially useful when a user opened several accounts and only one - should be kept (bug 188264). - -+ The login form on index.cgi again works correctly on a fresh installation - (bug 328108). - -+ Email preferences are now set correctly when creating a new user account - using the ENV method (bug 327355). - - -Minimum Requirements -******************** - -Perl ----- - - Perl v5.6.1 (changed from 2.18) (Non-Windows platforms) - ActiveState Perl v5.8.1 (Windows only) - -For MySQL Users ---------------- - - MySQL v3.23.41 (Note: 2.22 will require MySQL 4.x) - perl module: DBD::mysql v2.9003 (changed from 2.18) - -For PostgreSQL Users (new in 2.20) --------------------- - - PostgreSQL 7.3.x (8.x has received less testing) - perl module: DBD::Pg 1.31 (1.41 required for PostgreSQL 8+) - -Required Perl Modules ---------------------- - - AppConfig v1.52 - CGI v2.93 - Data::Dumper (any) - Date::Format v2.21 - DBI v1.38 (changed from 2.18) - File::Spec v0.84 (changed from 2.18) - File::Temp (any) - Template Toolkit v2.08 - Text::Wrap v2001.0131 - Mail::Mailer 1.65 (new in 2.20) - Storable (any) (new in 2.20) - -Optional Perl Modules ---------------------- - - Chart::Base v1.0 - GD v1.20 - GD::Graph (any) - GD::Text::Align (any) - Net::LDAP (any) - PatchReader v0.9.4 - XML::Parser (any) - - -What's New? -*********** - -Experimental PostgreSQL Support -------------------------------- - -In addition to MySQL, Bugzilla now also supports PostgreSQL. PostgreSQL -support is still somewhat experimental. Although most major features of -Bugzilla work on PostgreSQL in 2.20, there are probably still a few bugs -that need to be worked out. - -PostgreSQL support in 2.20 is acceptable for smaller production -environments that don't mind running into a bug or two now and then. - - -New User-Interface Color/Style ------------------------------- - -You'll notice that Bugzilla looks a bit nicer, now! We've made a few -color and style changes to update the overall "feel" of Bugzilla's -User Inteface. We plan to do even more work on the UI for 2.22. - - -Higher-Level Categorization of Bugs (above "Product") ------------------------------------------------------ - -Previous Bugzillas had "Products" that you could file bugs in, -and "Components" for those products. Now, "Products" can be grouped -into "Classifications." - -To enable this, a Bugzilla administrator can turn on the -"useclassification" parameter, using editparams.cgi. - - -Regular Reports by Email of Complex Queries ("Whining") -------------------------------------------------------- - -You can now tell Bugzilla to do a specific query (or set of queries) -every X minutes/hours/days, and send you the results by email. This is -great for keeping track on a daily basis of what's going on in -your Bugzilla. - - -"Environment Variable" Authentication Method --------------------------------------------- - -You can now tell Bugzilla to accept a certain value passed in from -Apache as authentication for Bugzilla users. This means that Bugzilla -now "supports" any type of authentication that Apache supports. - -To use this, set the "user_info_class" parameter to "ENV" and, at a -minimum, set the "auth_env_email" parameter to the name of the -Environment variable that passes the authenticated user (usually -"REMOTE_USER"). If your webserver knows users' real names as well, also -set the "auth_env_realname" parameter. If you are using a true -single-signon system that assigns an identifier uniquely to an -individual, even across changes of email address, then set -"auth_env_id" to the name of that variable. - - -User-List Drop-Down Menus -------------------------- - -Now, anywhere in Bugzilla where you previously had to type in an -email address by hand, you have the choice of having Bugzilla instead -display a drop-down menu of users to pick from. - -This feature is best for small installations with few users, because -on large installations the list grows too large to be useful. - -To enable the feature, turn on the "usemenuforusers" parameter in -editparams.cgi. - - -Server-Side Comment Wrapping ----------------------------- - -In older Bugzillas, comments were wrapped to 80 characters by the -user's web browser, and then stored in the database that way. This caused -problems because some browsers did not wrap comments properly. - -Now, Bugzilla stores comments unwrapped and wraps them at display time, so -all new comments should be properly wrapped. Also, when you upgrade, Bugzilla -will look for old "mis-wrapped" comments and attempt to wrap them properly. - -Lines beginning with the ">" character are assumed to be quotes, and are -*not* wrapped. - - -UI for Editing Priority, OS, Platform, and Severity ---------------------------------------------------- - -Bugzilla now has a User Interface for adding and removing values -from the OS, Platform, Priority, and Severity fields. You can also -rename values. Any user in the "editcomponents" group can click -on the "Field Values" link in their page footer to edit these fields. - -Also, the default list of choices for OS and Platform for new -installations is now much smaller. Old installations will keep -the same list they have now. - - -Bugzilla Queries as RSS ------------------------ - -You can now view a Bugzilla query as valid RSS 1.0. This means that you -could add a particular query to your RSS aggregator, if you wanted, to -keep track of changes in Bugzilla. - -To see a query as RSS, just click on the "RSS" link on the bottom of -your query results. Your query must return at least 1 result in order -for you to see the link. - - -Choice of E-Mail Sending Methods --------------------------------- - -Bugzilla now uses perl's Mail::Mailer to send e-mail. This means that -you have several choices of how Bugzilla can send email. By default, it -still uses sendmail, but it can also use SMTP, qmail, or send all email -to a file instead of out to users. - -A Bugzilla administrator can change which method is used by setting the -"mail_delivery_method" parameter in editparams.cgi. - - -"User Preferences" ------------------- - -Bugzilla users will now notice a section in their Preferences called -"General Preferences." Administrators will notice a new link called -"User Preferences." - -The Preferences system allows Bugzilla developers to specify arbitrary -"user preferences" that change the behavior of certain parts of Bugzilla. -Administrators can control whether or not users are allowed to use these -preferences, and what the default settings are for a user who is not -logged in. - -The first two preferences that we have implemented are: - + "Show a quip at the top of each bug list" - + "When viewing a bug, show comments in this order..." - -We plan to implement more preferences in the future. - - -"Large Attachment" Storage --------------------------- - -Bugzilla can now store very large attachments on disk instead of in the -database. These attachments can't be searched with Boolean Charts, but -they also don't take up database space, and they can be deleted individually -by the admin. - -When uploading an attachment, a user chooses if it's a "Big File." If so, -it's stored on the disk instead of in the database. - -To enable this feature, set the "maxlocalattachmentsize" parameter to -a non-zero value, in editparams.cgi. - - -"User Visibility" Controls --------------------------- - -It is now possible to prevent users from encountering all other users when -using user-matching or drop-down userlists. To enable this restriction, -enable the "usevisibilitygroups" parameter. Once this is enabled, each -group's permissions will include a new column for "visible." The members -of any group for which the group being edited is visible will be -able to user-match this groups's users or see them in dropdown lists. - -This does not control who a user can CC on a bug, only who they can -see in the user-matching lists or drop-downs. - -Miscellaneous Improvements --------------------------- - -- Marking an attachment as obsolete will now cancel all pending flag - requests for that attachment. That is, any flag that was set to "?" - on that attachment will be cleared. - -- You can now see which users are "watching" you, on the email - preferences page. - -- You can tell Bugzilla to mark certain comments in a different - color by adding "&mark=1,2,3,5-7" to the end of the show_bug.cgi URL, - where "1,2,3,5-7" means "highlight comment 1, comment 2, comment 3, and - comments 5 through 7." - -- "QA Contact" now also appears on the New Bug page, if QA Contacts are - enabled on your installation. - -- Bugzilla email now has the "In-Reply-To" header added to it, so if - you use an email client that supports threads, you can view your - Bugzilla email in threads. If you are upgrading to a new version of - Bugzilla, and you want this support, please see the instructions at: - https://bugzilla.mozilla.org/attachment.cgi?id=172267 - -- The email preferences system has been slightly updated. You will notice - the changes on your Email Preferences page. - -- You can now negate individual "boolean charts" (in the - "Advanced Searching" section at the bottom of the "Advanced - Search" page). That is, you can add "NOT" to the front of them. - -- You can add the words %assignee%, %reporter%, %user% (yourself), or - %qacontact% on the right-hand side of a Boolean Chart. For example, you - could make a Boolean Chart which said "Reporter" "does not equal" - "%assignee%". That would give you all bugs where the Reporter was not - the same as the Assignee. - -- You can now search Boolean Charts by "commenter." - -- If you have a group with no name, it will be re-named to "group_#" where - "#" is the numeric Bugzilla Group ID for that group. - -- If you are using time-tracking, you can now see a report of time spent - on bugs using summarize_time.cgi. - -- If you are using time-tracking, bugzilla will now set "hours remaining" - to "0" automatically if you RESOLVE a bug, whether you are in the - time-tracking group or not. - - -Deprecated Features -******************* - -- Bugzilla 2.20 is the last Bugzilla version to support MySQL 3.23.x. - Starting with Bugzilla 2.22, Bugzilla will require MySQL 4.0.x. This will - allow Bugzilla to take advantage of the advanced features of MySQL 4. - - -Outstanding Issues -****************** - -- (No Bug Number) VERY IMPORTANT: If you have customized the values in - your Status/Resolution field, you must edit checksetup.pl BEFORE YOU - RUN IT. Find the line that starts like this: - - bug_status => ["UNCONFIRMED", - - That's where you set the values for the Status field. - - resolution => ["","FIXED", - - And that's where you set values for the Resolution field. - - Those are both near line 1826 in checksetup.pl. - - If you forget to do this, you will have to manually edit the "bug_status" - and "resolution" tables in the database to contain the correct values. - -- bug 37765: VERY IMPORTANT: If you use the "sendmail" support of Bugzilla, - and you use an MTA which is *not* Sendmail (such as Postfix, Exim, etc.) - you MUST turn on the "sendmailnow" parameter or Bugzilla will not send - e-mail correctly. - -- (No Bug Number) If you close your web browser while the process_bug.cgi - or post_bug.cgi screen is running, not all emails will be sent, and - the next time that that bug is updated, there will be two updates. This - is because of a behavior of Apache that is beyond our control. - -- bug 276230: The support for restricting access to particular Categories of - New Charts is not complete. You should treat the 'chartgroup' Param as the - only access mechanism available. However, additionally, charts migrated from - Old Charts will be restricted to the groups that are marked MANDATORY for - the corresponding Product. There is currently no way to change this - restriction, and the groupings will not be updated if the group configuration - for the Product changes. This will not be fixed in the 2.20 branch. - -- bug 69621: If you rename or remove a keyword that is in use on bugs, you will - need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing - the option to rebuild the cache when it asks. Otherwise keywords may not show - up properly in search results. - -- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for - example, if you use a translation of Bugzilla), don't enable the XS::Stash - option when you install the Template Toolkit, or your Bugzilla installation - may become slow. This problem is fixed in a not-yet-released version of the - Template Toolkit (after 2.14). - -- If at any time you upgraded from a version of Bugzilla between 2.17.4 - - 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in - order for them to work. See the following link for instructions on how to do - this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18 - If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer, - then you don't need to do this. - -- (No Bug Number) If your DBI is really, really old, Bugzilla might fail - with a strange error message when you try to run checksetup.pl. Try - upgrading your DBI using: perl -MCPAN -e'install DBI' - -- Bug 126266: Bugzilla does not use UTF-8 to display pages. This means - that if you enter non-ASCII characters into Bugzilla, they may - display strangely, or Bugzilla may have other problems. For a workaround, - see: http://www.bugzilla.org/docs/tip/html/security-bugzilla.html - This has been fixed in the 2.22 series. - -- Bug 99215: Flags are not protected by "mid-air collision" detection. - Nor are any attachment changes. - -- Bug 89822: When changing multiple bugs at the same time, there is no - "mid-air collision" protection. - -- Bug 285614: importxml.pl may be broken in many different ways. - It has been fixed and completely re-written in the 2.22 series. - -- (No Bug Number) Note that the email interface (bug_mail.pl) in the - contrib/ directory has not been maintained (as it has no maintainer), - and so may not be working properly. Contributions are welcome, if - anybody would like to work on it. - - -Upgrading From An Older Bugzilla -************************************ - -NOTE: Running checksetup.pl to upgrade a large installation (over 10,000 bugs) - may take a significant amount of time. checksetup will try to let - you know how long it will take, but expect downtime of an hour or - more if you have many bugs, many attachments, or many users. - -Steps for Upgrading -------------------- - -1) View the Sanity Check (sanitycheck.cgi) page on your installation before - upgrading. Attempt to fix all warnings that the page produces before - you go any further, or you may experience problems during your upgrade. - -2) Make a backup of the Bugzilla database before you upgrade, perhaps - by using mysqldump. - - Example: - - mysqldump -u root -p --databases bugs > bugs.db.backup - -3) Replace the files in your installation with the new version of Bugzilla, - or you can try to use CVS to upgrade. The Bugzilla.org website has - instructions on how to do the actual installation. - -4) Make sure that you run checksetup.pl after you install the new version. - -5) View the Sanity Check page again after you run checksetup.pl. - -6) It is recommended that, if possible, you fix any problems you find - immediately. Failure to do this may mean that Bugzilla will not work - correctly. Be aware that if the sanity check page contains more errors after - an upgrade, it doesn't necessarily mean there are more errors in your - database, as additional tests are added to the sanity check over time, and - it is possible that those errors weren't being checked for in the old - version. - -7) If you want threading support on your Bugzilla email (see the - "Miscellaneous Improvements" section above for a description), - you need to follow the instructions at: - https://bugzilla.mozilla.org/attachment.cgi?id=172267 - - -Code Changes Which May Affect Customizations -******************************************** - -The New Database-Compatibility Layer ------------------------------------- - -For most customizations, this should have no effect. However, you should -be aware that Bugzilla->dbh is now an instance of "Bugzilla::DB" instead -of being a DBI object directly. In fact, it's actually a -Bugzilla::DB::Mysql for MySQL users, and a Bugzilla::DB::Pg for -PostgreSQL users. - -Anything called from $dbh (like $dbh->bz_last_key) that starts with -"bz_" or "sql_" is a custom Bugzilla function. Anything *not* starting -with those two prefixes is a normal DBI function. - -Methods whose names start with "sql_" generate a piece of a SQL statement. -They generate the correct version of the statement for whichever database -you are using. - -Methods whose names start with "bz_" do something directly. - -You can see more documentation about this at: - -http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm - - -If You Customize Your Database... ---------------------------------- - -In order to support multiple databases, we had to do something sort of -tricky. Bugzilla now stores what it *thinks* the current database schema -is, in a table called bz_schema. - -This means that when checksetup changes the database, it updates the -bz_schema table. When *you* update the database, without using -checksetup to do it, the bz_schema table is *not* updated. - -So, if you're going to add/remove a new column/table to Bugzilla, or if you're -going to change the definition of a column, try to do it by adding code to -checksetup in the correct place. (It's one of the places where you find -the word "--TABLE--".) - -You can see the documentation on the $dbh functions used to do this at: - -http://www.bugzilla.org/docs/2.20/pod/Bugzilla/DB.pm#schema_modification_methods - - -Many Functions Renamed ----------------------- - -We are reorganizing the Bugzilla code so that it can support mod_perl. As -part of this, we are moving all functions out of globals.pl and CGI.pl, and -into modules in the Bugzilla/ directory. - -Sometimes when we moved them, we also renamed them. The new Bugzilla standard -is to have functions_named_like_this, instead of FunctionsNamedLikeThis. - -So if you were using a FunctionNamedLikeThis that no longer works, try just -using it as function_named_like_this. If that doesn't work, you may have to -search for where we put it, and what we renamed it to. Most of the functions -moved to logical places. - -If you really can't find it, search bugzilla.mozilla.org using the name -of the old function. We usually moved one function per bug, so the new -name will be somewhere in a bug report. - - -User Preferences ----------------- - -Bugzilla now has a "User Preferences" system! These preferences are stored -in the database, and specified by a Bugzilla developer. The Bugzilla -developers actually call these "settings," but we called them "User -Preferences" in the UI to make things clearer. - -You access a user's settings differently depending on if you are in a -.cgi file or in a template file: - -CGI: Bugzilla->user->settings->{'setting_name'}->value -Template: Bugzilla.user.settings.setting_name.value - -Where "setting_name" is the name of the setting. You can see the current -setting names in the "setting" table in the database. - -Remember that sometimes you may want to check a user's settings when -making a customization. - -To see how to add new settings, search for "add_setting" in checksetup.pl. -Also see the template: template/en/default/global/setting-descs.none.tmpl. - -Other Changes -------------- - -- The $::unconfirmedstate variable has been replaced by the actual string - "UNCONFIRMED" everywhere in Bugzilla code. - -- The %::FORM and %::MFORM variables are no longer used to access form - data. Instead, use $cgi->param(). There are many examples of how to do - this, all over the Bugzilla code. - -- SendSQL() and related calls are deprecated, and the various $dbh methods - should be used instead, such as $dbh->prepare() and $dbh->execute(). - Bugzilla->dbh is the $dbh handle to use. For more information on how - to use the $dbh methods, see: http://search.cpan.org/dist/DBI/DBI.pm - -- The $::userid variable will be going away. Use Bugzilla->user->id instead. - -- All global variables (any that start with $::, @::, or %::) will - be entirely gone by Bugzilla 2.24. - - -Security Fixes in 2.20 Releases -******************************* - -2.20.1 ------- - -There were three security issues discovered after the release of -Bugzilla 2.20 that we resolved for Bugzilla 2.20.1. One SQL Injection -(from an administrator only), one Cross-Site Scripting vulnerability -(that mostly affects only the user who can exploit it), and one minor, -extremely specific information leak. - -To see details on the vulnerabilities that were fixed, see the -Security Advisory at: - -http://www.bugzilla.org/security/2.16.10/ - - -Release Notes for Previous Versions -*********************************** - -***************************************** -*** The Bugzilla 2.18.x Release Notes *** -***************************************** - -Table of Contents -***************** - -- Introduction -- Important Updates In This Point Release - * Version 2.18.1 - * Version 2.18.2 -- Requirements - * Dependency Requirements -- What's New? - * Generic Reporting - * Generic Charting - * Request System - * Enterprise Group Support - * User Wildcard Matching - * Support for "Insiders" - * Time Tracking - * Authentication module/LDAP improvements - * Improved localization support - * Patch Viewer - * Comment Reply Links - * Full-Text Search - * Email Address Munging - * Simple Search - * Miscellaneous Improvements - * All Changes -- What's Changed? - * Flag Names - * New Saved Search User Interface - * Rules for changing fields -- Removed Features -- Code Changes Which May Affect Customizations -- Recommended Practice for the Upgrade - * Note About Upgrading From MySQL With ISAM Tables - * Steps for Upgrading -- Outstanding Issues (<======================== IMPORTANT, PLEASE READ) -- Security Fixes In 2.18 Releases -- Detailed Version-To-Version Release Notes - - -Introduction -************ - -This document contains the release notes for Bugzilla 2.18 and -the bugfix releases after 2.18. In this document, recently added, -changed, and removed features of Bugzilla are described. - -The 2.18 release is our current stable series, containing the results -of over two years of hard and dedicated work by volunteers all over -the world under the lead of Dave Miller. - - -Important Updates In This Point Release -*************************************** - -There are usually many other bug fixes than those listed below, -but the below fixes are the ones that we thought System Administrators -would like to specifically know about. - -To see a listing of all changes in this release, you can use the -table available at: - -http://www.bugzilla.org/status/changes.html - -Version 2.18.1 --------------- - -+ You can now enter a negative time for "Hours Worked" - in the time-tracking area. (Bug 271276) - -+ The BugMail.pm customization required for Windows (as - described in the Bugzilla Guide) now actually works. (Bug 280911) - -+ Users who were using Bugzilla 2.8 can now successfully upgrade - to 2.18.1 (they couldn't upgrade to 2.18). (Bug 283403) - -+ Dependency mails are now properly sent during a mass-change of bugs. - (Bug 178157) - - -Version 2.18.2 --------------- - -+ You can now create accounts with createaccount.cgi even - when the "requirelogin" parameter is turned on. (Bug 294778) - -+ Bugs that are in disabled groups may not show a padlock - on the bug list, or may otherwise behave strangely. You - can now fix this using sanitycheck.cgi. (Bug 277454) - -+ If sendmail dies while you are marking a bug - as a duplicate, the duplicates table will no longer become - corrupted. (Bug 225042) - - -Requirements -************ - -Dependency Requirements ------------------------ - -Minimum software requirements: - - MySQL v3.23.41 (changed from 2.16) - Perl v5.6.0 (changed from 2.16) (Non-Windows platforms) - ActiveState Perl v5.8.1 (Windows only) - -Required Perl modules: - - AppConfig v1.52 - CGI v2.93 (new since 2.16) (changed from 2.17.7) - Data::Dumper (any) - Date::Format v2.21 (changed from 2.16) - DBI v1.36 (changed from 2.16) (changed from 2.17.7) - DBD::mysql v2.1010 (changed from 2.16) - File::Spec v0.82 - File::Temp (any) - Template Toolkit v2.08 (changed from 2.16) - Text::Wrap v2001.0131 - -Optional Perl modules: - - Chart::Base v1.0 (changed from 2.16) (changed from 2.17.7) - GD v1.20 (changed from 2.16) - GD::Graph (any) (new since 2.16) - GD::Text::Align (any) (new since 2.16) - Net::LDAP (any) (new since 2.16) - PatchReader v0.9.4 (new since 2.16) (changed from 2.17.7) - XML::Parser (any) - - -What's New? -*********** - -Generic Reporting ------------------ - -Bugzilla has a new mechanism for generating reports of the current state of -the bug database. It has two related parts: a table-based view, and several -graphical views. - -The table-based view allows you to specify an x, y and z (multiple tables of -data) axis to plot, and then restrict the bugs plotted using the standard -query form. You can view the resulting data as an HTML or CSV export (e.g.: -for importing into a spreadsheet). - -There are also bar, line and pie charts, which are defined in a very similar -way. These views may be more appropriate for particular data types, and are -suitable for saving and then putting into presentations or web pages. - - -Generic Charting ----------------- - -Bugzilla has a new mechanism for generating charts (graphs over time) of any -arbitrary search. This is known as "New Charts." Legacy data from the previous -charting mechanism ("Old Charts") is migrated into the "New Charts" when you -upgrade. The Old Charts mechanism remains, but is deprecated and will be -removed in a future version of Bugzilla. - -Individual users can see/create charts as long as they are a member of the -group specified in the Param 'chartgroup'. Data can be collected for -personal charts every seven days (or a longer period, as set by the user). -Charts created by an administrator can be made public (visible to all). Data -is collected for administrator charts every day (or a longer period, as set -by the admin). - -The data is collected by the collectstats.pl script, which an administrator -will need to arrange to be run once every day (see the manual). Chart data can -be plotted in a number of different ways, and different data sets can be -plotted on the same graph for comparison. - -Please see the Known Bugs section for some important limitations relating to -access controls on charts. - - -Request System ---------------- - -The Request System (RS) is a set of enhancements that adds powerful flag -(superset of the old attachment status) features to the bugs. - -RS allows for four states: off, granted, denied, and (optionally) requested, -where "granted" is the equivalent of "on". These additions mean it is no -longer necessary to define a status to negate another status (e.g. -"needs-work" to negate "has-review") because negation is built into each -status via the status' "denied" state. Bug statuses: Previously only -attachments could have these kinds of statuses. RS enables them for bugs as -well. This feature can be used to request and grant/deny certain properties -for a bug, such as inclusion for a specific milestone or approval for checkin. -This way, Bugzilla supports the natural decision-making process in your -organization. - -- Requests: Flags can now optionally be made requestable, which means users - can ask other users to set them. When a user requests a flag, Bugzilla - emails the requestee and adds the request to a browsable queue so both the - requester and the requestee can keep track of its status. Once the - requestee fulfills the request by setting the flag to either granted or - denied, Bugzilla emails the requestee and removes the request from the - queue. This feature supports workflow like the mozilla.org code review - and milestone approval processes, whereby code is peer reviewed before - being committed and patches get approved by product release managers for - inclusion in specific product releases. - -- Product/component specificity: Previously flags were product-specific, and - if you wanted the same flag for multiple products you had to define - multiple flags with the same name. Flags are now - product/component-specific, and a single flag can be enabled or disabled - for multiple product/component combinations via inclusions and exclusions - lists. Flags are enabled for all combinations on their inclusions list - except those that appear on their exclusions list. - - -Enterprise Group Support ------------------------- - -Bugzilla is no longer limited to 55 access control groups. Administrators can -define an arbitrary number of access groups composed of individual users or -other groups. The groups can be configured via the web interface to achieve a -wide variety of access control policies. See the documentation section on -'Groups And Group Controls' for details. - - -User Wildcard Matching ----------------------- - -Sites can now enable the use of wildcards and substrings in bug entry and -editing forms. If the user enters an incomplete username, he'll get a list of -users that matched the given username. - - -Support for "Insiders" ----------------------- - -If the 'insidergroup' parameter is defined, a specific group of users can be -designated insiders who can designate comments and attachments as private to -other insiders. These comments and attachments will be invisible to other -users who are not members of the insiders group even if the bugs to which they -apply are visible. Other insiders will see the comments and attachments with a -visual tinting indicating that they are private. - - -Time Tracking -------------- - -Controls for tracking time spent fixing bugs are included in the bug form for -members of the group specified by the 'timetrackinggroup' parameter. Any time -comments are added to the bug, members of the time tracking group can add an -amount of time they spent, and it's figured into the total and displayed at -the top of the bug. Shown in the bug are your original estimate, the amount of -time spent so far, the revised estimate of how much time is remaining, and -your gain/loss on the original estimate. - - -Authentication module/LDAP improvements ---------------------------------------- - -Bugzilla's authentication mechanisms have been modularized, making pluggable -authentication schemes for Bugzilla a reality. Both the existing database and -LDAP systems were ported as part of modularization process. Additionally, the -CGI portion of the backend was redesigned to allow for authentication from -other sources, including (theoretically) email, which will help Bug 94850. - -As part of this conversion, LDAP logins now use Perl's standard Net::LDAP -module, which has no external library dependencies. - - -Improved localization support ------------------------------ - -Bugzilla administrators can now configure which languages are supported by -their installations and automatically serve correct, localized content to -users based on the HTTP 'Accept-Language' header sent from users' browsers. - -There are currently localized templates available for: Arabic, Belarusian, -Chinese, French, German, Italian, Korean, Portuguese (Brazil) Spanish (Spain -or Mexico) and Russian. These localized template packs are third-party -contributions, may only be available for specific versions, and may not be -supported in the future. (http://www.bugzilla.org/download/#localizations) - - -Patch Viewer ------------- - -Viewing and reviewing patches in Bugzilla is often difficult due to lack of -context, improper format and the inherent readability issues that raw patches -present. Patch Viewer is an enhancement to Bugzilla designed to fix that by -offering increased context, linking to sections, and integrating with Bonsai, -LXR and CVS. - - -Comment Reply Links -------------------- - -In Edit Bug, each bug comment now includes a convenient (reply) link that -quotes the comment text into the textarea. This feature is only enabled in -Javascript-capable browsers, but causes no inconvenience to other user agents. - - -Full-Text Search ----------------- - -It is now possible to query the Bugzilla database using full-text searching, -which spans comments and summaries, and which searches for substrings and stem -variations of the search term. Basically, it's like using Google. - - -Email Address Munging ---------------------- - -The fact that raw email addresses are displayed in Bugzilla makes it trivial -for bots that spamharvest to spider through Bugzilla, in particular, through -Bugzilla's buglists. This change adds HTML obfuscation of email addresses as -they appear in the Bugzilla web pages. - - -Google-like Bug Search ----------------------- - -Bugzilla now includes a very simple, Google-like "Find a Specific Bug" page, -in addition to its advanced search page. - - -Miscellaneous Improvements --------------------------- - -- The "Assigned To" field on the new bug page is now prefilled with the default - component owner. - -- A bug alias column is now available in the buglist page. - -- Lists of bugs containing errors in the sanity check page now have a "view as - buglist" link in addition to the individual bug links. - -- Autolinkification Page - It's now possible to apply Bugzilla's comment - hyperlinking algorithm to any text you like. This should be useful for status - updates and other web pages which give lists of bugs. The bug links created - include the subject, status and resolution of the bug as a tooltip. - -- There are more tags on the links toolbar for navigating quickly between - different areas. - -- Buglists are now available as comma-separated value files (CSV) and JavaScript - (JS) as well as HTML and RDF. - -- Keywords and dependencies can now be entered during initial bug entry. - -- A CSS id signature unique to each Bugzilla installation is now added to the - tag on Bugzilla pages to allow custom end-user CSS to explicitly affect - Bugzilla. - -- Perl's path has been changed to a normal /usr/bin/perl from the original - legacy "bonsaitools" path specifier. - -- A new "always-require-login" parameter allows administrators to require a - login before being able to view any page, except the front page. - -- A developer may add an attachment, and also reassign a bug to himself as part - of that single action. - -- Bugzilla is now able to use the replication facilities provided by the - MySQL database to handle updates from the main database to the secondaries. - -- Mail handling is now between 125% to 175% faster. - -- Guided Bug Entry: You can see a sample enter_bug.cgi template at - enter_bug.cgi?format=guided that "guides" users through the process of - filing a "good" bug. It needs to be modified before use in your organization. - -- There is now a "Give me some help" link on the Advanced Search page that will - enable pop-up help for every field on the page. - -- The Bugzilla administrator can now forbid users from marking bugs RESOLVED - when there are unresolved dependencies. - - -All Changes ------------ - -To see a list of EVERY bug that was fixed between 2.16 and 2.18 (over 1000), -see: http://tinyurl.com/6m3e4 - - -What's Changed? -*************** - - -Flag names ----------- - -Prerelease versions of Bugzilla 2.17 and 2.18 inadvertantly allowed -commas and spaces in the names of flags, which due to the way they're -processed, caused lots of internal havoc if you named flags to have -any commas or spaces in them. Having commas or spaces in the names -can cause errors in the notification emails and in the bug activity -log. The ability to create new flags with these characters has been -removed. If you have any existing flags that you named that way, -running checksetup will attempt to automatically rename them by -replacing commas and spaces with underscores. - - -New Saved Search User Interface -------------------------------- - -In previous Bugzilla versions, you could specify on the search page that you -wanted to save a search and store it as a link in your footer. This option has -now moved to the search results page (buglist.cgi), where you will see a -"Remember search" button with a box next to it to enter the name of the search. - -You can manage your saved searches on the Preferences page. - - -Rules for changing fields -------------------------- - -There have been some changes to the rules governing who can change which fields -of a bug report. The rules for Bugzilla version 2.16 and 2.18, along with -differences between them, are listed below. Bear in mind that there are other -restrictions on bug manipulation besides the ones listed below. In particular, -the groups system enforces restrictions on who can create, edit, or even see -any given bug. - -Bugzilla 2.16 rules: - -- anyone can make a null change; -- anyone can add a comment; -- anyone in the editbugs group can make any change; -- the reporter can make any change to the status; -- anyone in the canconfirm group can change the status - to any opened state (NEW, REOPENED, ASSIGNED). -- anyone can change the status to any opened state - if the everconfirmed flag is set; -- the owner, QA contact, or reporter can make any change - *except* changing the status to an opened state; -- No other changes are permitted. - -[Note that these rules combine to allow the reporter to make any change -to the bug.] - -Bugzilla 2.18 rules: - -- anyone can make a null change; -- anyone can add a comment; -- anyone in the editbugs group can make any change; -- anyone in the canconfirm group can change the status - from UNCONFIRMED to any opened state; -- the owner or QA contact can make any change; -- the reporter can make any change *except*: - - changing the status from UNCONFIRMED to any opened state; or - - changing the target milestone; or - - changing the priority (unless the letsubmitterchoosepriority - parameter is set). -- No other changes are permitted. - -The effective differences in the rules: - -- In 2.16, the reporter could always change anything about a bug. - - In 2.18, the reporter can't: - - - confirm the bug unless he is in the canconfirm group; - - change the target milestone; - - change the priority (unless the 'letsubmitterchoosepriority' - parameter is set; - - (unless he is also the owner, the QA contact, or in the editbugs - group, in which case he can do all these things). - -- In 2.16, the owner or QA contact (if the 'useqacontact' parameter - is set) can't change the bug status to an opened status unless they - are also the reporter, or have editbugs or canconfirm, or the - everconfirmed flag is set on the bug). - - In 2.18 the owner or QA contact can make any change to a bug. - -- In 2.16, a member of the canconfirm group can set the status - to any opened status. - - In 2.18 this is only possible if the status was previously - the unconfirmed status. - -- In 2.16, the status can be set to anything by anybody - if the 'everconfirmed' flag is set. - - In 2.18, this authorization code does not pay any attention - to the 'everconfirmed' flag. - - -Removed Features -**************** - -- Please note that Bugzilla no longer supports MySQL 3.22. The minimum required - version is now 3.23.41. - -- The "shadow database" mechanism is no longer used. Instead, use MySQL's - built-in replication feature. - -- If you have placed any comments in the localconfig file, they may be removed - by checksetup.pl. - - -Code Changes Which May Affect Customizations -******************************************** - -- A mechanism (called "Template Hooks") for third party extensions to plug into - existing templates without having to patch or replace distributed templates - has been added. More information on this can be found in the documentation. - -- Header output now uses CGI.pm, in a step towards enabling mod_perl - compatibility. This change will affect users that had customized charsets in - their CGI files: previously the charset had to be added everywhere that - printed the Content-Type header; now it only needs changing in one spot, in - Bugzilla/CGI.pm. - -- $::FORM{} and $::COOKIE{} are deprecated. Use the $cgi methods to access - them. - -- $::userid is gone in favor of Bugzilla->user->id - -- ConnectToDatabase() is gone (it's done automatically when you initialize the - Bugzilla object) - -- quietly_check_login() and confirm_login() are gone, use Bugzilla->login() - with parameters for whether the login is required or not. - -- Use Bugzilla->user->login in place of $::COOKIE{Bugzilla_login} - -- You can tell if there's a user logged in or not by using - Bugzilla->user rather than looking for $::userid==0. - In new 2.18 code, use defined(Bugzilla->user) && (Bugzilla->user->id) - In 2.20, this will become just (Bugzilla->user->id) - In templates, always test [% IF user.id %] rather than [% IF user %] - -- SendSQL() and related calls are deprecated, and the various $dbh methods - should be used instead, such as $dbh->prepare() and $dbh->execute(). - Bugzilla->dbh is the $dbh handle to use. - - -Recommended Practice for the Upgrade -************************************ - -Note About Upgrading From MySQL With ISAM Tables ------------------------------------------------- -As previously noted in the Dependency Requirements MySQL is now required -to be at least version 3.23.41. This implies that all tables of type ISAM will -be converted by the checksetup.pl script to MyISAM. - - -Steps for Upgrading -------------------- - -1) View the Sanity Check (sanitycheck.cgi) page on your installation before - upgrading. - -2) As with any upgrade it is recommended that you make a backup of the - Bugzilla database before you upgrade, perhaps by using mysqldump. - - Example: - - mysqldump -u root -p --databases bugs > bugs.db.backup - -3) Replace the files in your installation, or you can try to use CVS to upgrade. - The Bugzilla.org website has instructions on how to do the actual - installation. - -4) Make sure that you run checksetup.pl after you install the new version. - -5) View the Sanity Check page again after you run checksetup.pl. - -6) It is recommended that, if possible, you fix any problems you find - immediately. Failure to do this may mean that Bugzilla will not work - correctly. Be aware that if the sanity check page contains more errors after - an upgrade, it doesn't necessarily mean there are more errors in your - database, as additional tests are added to the sanity check over time, and - it is possible that those errors weren't being checked for in the old - version. - - -Outstanding Issues -****************** - -These are known problems with the release that we think you should know about. -They each have a bug number for http://bugzilla.mozilla.org/ - -- If at any time you upgraded from a version of Bugzilla between 2.17.4 - - 2.17.7 to either 2.18rc3 or 2.19.1, you must manually fix your New Charts in - order for them to work. See the following link for instructions on how to do - this: https://bugzilla.mozilla.org/show_bug.cgi?id=276237#c18 - If you are using 2.18rc3, but did not upgrade from version 2.17.4 or newer, - then you don't need to do this. - -- bug 37765: If you use an MTA other than sendmail (such as Postfix, Exim, - etc.) you MUST turn on the "sendmailnow" parameter or Bugzilla will not send - e-mail correctly. - -- bug 276230: The support for restricting access to particular Categories of - New Charts is not complete. You should treat the 'chartgroup' Param as the - only access mechanism available. However, additionally, charts migrated from - Old Charts will be restricted to the groups that are marked MANDATORY for - the corresponding Product. There is currently no way to change this - restriction, and the groupings will not be updated if the group configuration - for the Product changes. - -- bug 69621: If you rename or remove a keyword that is in use on bugs, you will - need to rebuild the "keyword cache" by running sanitycheck.cgi and choosing - the option to rebuild the cache when it asks. Otherwise keywords may not show - up properly in search results. - -- (No Bug Number) If you have a lot of non-ASCII data in your Bugzilla (for - example, if you use a translation of Bugzilla), don't enable the XS::Stash - option when you install the Template Toolkit, or your Bugzilla installation - may become slow. This problem is fixed in a not-yet-released version of the - Template Toolkit (after 2.14). - -- bug 266579: Users may be able to circumvent not having "canconfirm" privileges - in some circumstances. This is fixed starting with 2.19.3, but will not - be fixed in any 2.18 release, as the changes required to fix it are quite - large. - -- bug 99215: Attachment changes have no mid-air collision detection, unlike bug - changes. - -- bug 57350: Searching using the "commenter is" option may be VERY slow. Note - that searching for "field: comment, changed by: user@domain.com" is fast, - though. - -- bug 151509: Using the boolean chart option "contains the string" with the - "flag name" field or certain other fields will cause Bugzilla to emit an - error. This is fixed in 2.20rc1, but will not be fixed in the 2.18 series. - -- bug 234159: Bugzilla may sometimes send multiple notices in one email. - -- bug 237107: If you search for attachment information using the Boolean Charts - at the bottom of the Advanced Query page, bugs without attachments will not - show up in the result list. - - -Security Fixes In 2.18 Releases -******************************* - -Version 2.18 ------------- - -Summary: XSS in Internal Error messages in Bugzilla 2.16.7 and 2.18rc3 -CVE Name: CAN-2004-1061 -Reference: https://bugzilla.mozilla.org/show_bug.cgi?id=272620 -Details: - It is possible to send a carefully crafted URL to Bugzilla designed to -trigger an error message. The Internal Error message includes javascript code -which displays the URL the user is visiting. The javascript code does not -escape the URL before displaying it, allowing scripts contained in the URL to -be executed by the browser. Many browsers do not allow unescaped URLs to be -sent to a webserver (thus complying with RFC 2616 section 2.3.1 and RFC 2396 -section 2.4.3), and are thus immune to this issue. - Browsers which are known to be immune: Firefox 1.0, Mozilla 1.7.5, -Camino 0.8.2, Netscape 7.2, Safari 1.2.4 - Browsers known to be susceptible: Internet Explorer 6 SP2, -Konqueror 3.2 - Browsers not listed here have not been tested. - - -Version 2.18.1 --------------- - -Two security issues were fixed in Bugzilla 2.18.1, neither of them -critical. - -See http://www.bugzilla.org/security/2.16.8/ for details. - - -Version 2.18.2 --------------- - -Two security issues were fixed in Bugzilla 2.18.2. One of them -is a major Information Leak/Unauthorized Bug Change. The other -is a minor Information Leak. - -See http://www.bugzilla.org/security/2.18.1/ for details. - - -Detailed Version-To-Version Release Notes -***************************************** - -********************************************************* -*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.7 *** -********************************************************* - -*** Security fixes *** - -- It is possible to send a carefully crafted HTTP POST message to - process_bug.cgi which will remove keywords from a bug even if you don't have - permissions to edit all bug fields (the "editbugs" permission). Such changes - are reported in "bug changed" email notifications, so they are easily - detected and reversed if someone abuses it. Users are now prevented from - making changes to keywords if they do not have editbugs privileges. (bug - 252638) - -*** Bug fixes of note *** - -- Enforce a minimum of 10 minutes between attempts to reset a password, so - we don't mailbomb the user if someone submits the form many times in a - row. (bug 250897) - -- Put products in alphabetical order on the create attachment status page. - (bug 251427) - -- Specify MyISAM as the table type when creating new tables. MySQL 4.1 and - up default to InnoDB, which doesn't support some of the indexing methods - that we use. (bug 263165) - -********************************************************* -*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.6 *** -********************************************************* - -*** Security fixes *** - -- If Bugzilla is configured to hide entire products from some users, both - duplicates.cgi and the form for mass-editing a list of bugs in buglist.cgi - can disclose the names of those hidden products to such users. - (bugs 234825 and 234855) - -- Several administration CGIs echo invalid data back to the user without - escaping it. (bug 235265) - -- A user with privileges to grant membership to any group (i.e. usually an - administrator) can trick editusers.cgi into executing arbitrary SQL. - (bug 244272) - -*** Bug fixes of note *** - -- Allow XML import to function when there are regexp metacharacters in product - names (bug 237591) - -- Allow the bug_email.pl contrib script to work with useqacontact (bug 239912) - -- Improve the error message used by checksetup.pl when the MySQL requirements - are not met (bug 240228) - -- Elimnate the warning in checksetup.pl about the minimum sendmail version (bug - 240060) - -- $webservergroup now defaults to group 'apache' in new installations (bug - 224477) - -- Correct a situation where a bugmail message could be sent twice to a user - being added to the CC list if the address was entered in a different case - than the user registered with. (bug 117297) - -- Various documentation updates - -********************************************************* -*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.4 *** -********************************************************* - -*** Bug fixes of note *** - -- Fix a "used only once" warning that ocurred only in perl 5.00503 - (bug 2321691) - -- When a user is creating a new account and enters an invalid email - address, the error page sent the "Content-type" header twice, causing - the second one to be visible at the top of the page. - (bug 137121) - -- An HTML encoding issue which only affected Internet Explorer was - corrected in the "Change several bugs at once" page. - (bug 181106) - -- During initial setup, using invalid characters in the administrator - password would present an error message stating your password was - too long or too short instead of telling you it had invalid - characters. - (bug 166755) - -- When a user reset their own password via an emailed token, the new - password in the first field would be accepted if the second password - field was left blank. - (bug 123077) - -- Reopening bugs from the "change several bugs at once" page now works. - (bug 95430) - -- Fix a regression in xml.cgi caused by the previous bugfix for MySQL - SUM() changes. The original fix didn't work properly either. - (bug 225474) - -- No longer use server push with the "Safari" browser, which claims to - use the Mozilla layout engine but doesn't. - (bug 188712) - -- Creating a shadow database no longer fails with taint mode errors. - (bug 227510) - -- If you change your cookiepath setting at some stage (because you have - moved the directory Bugzilla resides on your webserver), users can - have login cookies with the old cookiepath, and their browsers will - send multiple logincookies. Bugzilla now uses the first rather than - the last in order to get the most specific cookie which will be the - correct one. - (bug 121419) - -- Fixed a regression caused by the previous DBD::mysql fixes, that - caused older versions of DBD::mysql to break due to not supporting - the new DBI syntax. - (bug 224815) - -- Bugzilla no longer sends out invalid dates for cookie expiry. This - bug had no known user visible ramifications. - (bug 228706) - -- Update the shadow database parameters description to tell the user - about permissions requirements for creating a shadow database. - (bug 227513) - -- Various documentation updates. - -********************************************************* -*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.3 *** -********************************************************* - -*** SECURITY ISSUES RESOLVED *** - -- A user with 'editproducts' privileges (i.e. usually an administrator) - can select arbitrary SQL to be run by the nightly statistics cron job - (collectstats.pl), by giving a product a special name. - (bug 214290) - -- A user with 'editkeywords' privileges (i.e. usually an administrator) - can inject arbitrary SQL via the URL used to edit an existing keyword. - (bug 219044) - -- When deleting products and the 'usebuggroups' parameter is on, the - privilege which allows someone to add people to the group which is - being deleted does not get removed, allowing people with that - privilege to get that privilege for the next group that is created - which reuses that group ID. Note that this only allows someone who - had been granted privileges in the past to retain them. - (bug 219690) - -- If you know the email address of someone who has voted on a secure - bug, you can access the summary of that bug even if you do not have - sufficient permissions to view the bug itself. - (bug 209376) - -*** Bug fixes of note *** - -Perl 5.8.0 Compatibility fixes: - -- Two taint errors were fixed, one in process_bug.cgi, and - another in post_bug.cgi. - (bugs 220332 and 177828) - -MySQL 4.0 Compatibility fixes: - -- A cosmetic fix was applied to votes.cgi (if there were no - votes, the "0" was not displayed) due to a change in semantics - in SUM() in MySQL 4.0. - (bug 217422) - -DBD::mysql > 2.1026 Compatibility fixes: - -- DBD::mysql versions after 2.1026 return the table list quoted, which - broke the existing "table exists" check in checksetup.pl, which caused - the second and subsequent attempts to run checksetup.pl to fail. - (bug 212095) - -Miscellaneous bug fixes: - -- A Mozilla-specific reference was removed from one of the report - templates. - (bug 221626) - -- It was possible to enter a situation where you were unable to get to - editparams.cgi to turn the shutdownhtml param back off after you - turned it on when Apache was configured to run Bugzilla in suexec - mode. - (bug 213384) - -- The processmail rescanall task would not send e-mails about more than - one bug to the same address. - (bug 219508) - -- If Bugzilla hadn't been accessed in the last hour when the - collectstats.pl or whineatnews.pl cron jobs ran, the versioncache - would get recreated with the file owner being the user the cron job - was running as (usually not the webserver user), causing subsequent - access to Bugzilla by the webserver to fail until the permissions were - fixed. Now if versioncache isn't readable when accessing from the - webserver, we pretend it doesn't exist and recreate it again. - (bug 160422) - -- The 'sendmailnow' param is now on by default in new installations - (this does not affect existing installations). - (bug 146087) - -- The 008filter.t test would fail if you had multiple language packs - installed. It now properly tests all of the installed language packs. - (bug 203318) - -- A few minor documentation changes were committed. - -********************************************************* -*** USERS UPGRADING FROM ALL VERSIONS PRIOR TO 2.16.2 *** -********************************************************* - -*** SECURITY ISSUES RESOLVED *** - -- A cross site scripting (XSS) vulnerability was fixed in which bug - summaries were not properly filtered when a user viewed a dependency graph - allowing JavaScript to be embedded on that page. - (bug 192661) - -- Several XSS vulnerabilities were fixed in which user - input was not escaped when being displayed. A new - test has been added to warn about unfiltered data in template - files (t/008filter.t). - (bug 192677) - -- An issue was fixed in which the QA contact was still treated as the QA - contact even after the 'useqacontact' setting was turned off. This also - allowed the QA contact to edit the security groups and view secured bugs that - he/she was allowed to access prior to the 'useqacontact' setting being - deactivated. - (bug 194394) - -- Fixed a situation where an attacker (with local access to the webserver) - could overwrite any file on the webserver to which the webserver user - has write access by creating appropriately named symbolic links in the - data and webdot directories (world-writable in many configurations). - Bugzilla now uses File::Temp to create secure temporary files. File::Temp - is part of the Perl distribution for Perl 5.6.1 and later, but if you're - using an older version of Perl you'll need to install it with CPAN. - (bug 197153) - -** IMPORTANT CHANGES *** - -- New module requirement: File::Temp, as mentioned above. - -*** Bug fixes of note *** - -- An issue was fixed in which administrator rights could be removed from an - administrator who deleted a product while the 'usebuggroups' setting is - activated. - (bug 157704) - -- Fixed an issue in which importxml.pl would fail the test suite when running - under perl 5.8.0 with the optional XML::Parse module. - (bug 172331) - -- There was previously a bug in CGI.pl in which the following warning - would be given under certain conditions: - "Character in "c" format wrapped at CGI.pl..." - This is now fixed. In some cases the warning was filling up web server log - files. - (bug 194125) - -- Fixed a bug in which long component names (in excess of 50 characters) would - be accepted when creating the component but would cause problems when trying - to use that component on a bug because it would get truncated. It is now no - longer possible to create components with names in excess of 50 characters. - (bug 197180) - -- Fixed a bug in checksetup.pl in which permissions were not being fixed - on the 'data/comments' file, the quip file. - (bug 160279) - -***************************************************************** -*** USERS UPGRADING FROM 2.16.1 OR EARLIER, 2.14.4 OR EARLIER *** -***************************************************************** - -*** SECURITY ISSUES RESOLVED *** - -- Fixed a cross site scriptability issue in quips. This is only a problem - if quips with HTML could have been inserted into your quips files. Bugzilla - has not allowed this since 2.12. - (bug 179329) -- checksetup.pl will now attempt to prevent access to "editor backups" of - localconfig. - (bug 186383) -- collectstats.pl no longer makes data/mining (which contains graphing - information) world writeable. - (bug 183188) - -*********************************************** -*** USERS UPGRADING FROM 2.16.0 OR EARLIER *** -*********************************************** - -*** SECURITY ISSUES RESOLVED *** - -- Apostrophes were not properly handled in email addresses. This was a - regression introduced in 2.16. It is not known whether this was - exploitable. - (bug 165221) - -See also next major section. - -*** Bug fixes of note *** - -- The VERSION cookie which allowed the previously entered version of a product - to be remembered was not correctly set. It was only set as a session - cookie, and under some circumstances could interfere with other cookies - (such as the login information) send at the same time. - (bug 160227) - -- importxml.pl would fail if the versioncache needed to be updated. - (bug 164464) - -- Bug changes going through intermediate pages would munge fields with - multiple fields, such as CCs. - (bug 161203) - -- On failure in template->new, Bugzilla will now die rather than futilely - attempt to use an error template. - (bug 166023) - -- Fixed a problem where checksetup had problems converting old installations - that didn't have a duplicates table. - (bug 151619) - -- Fixed a problem that caused taint errors when viewing or editing user - preferences with Perl 5.005 and Template 2.08. - (bug 160710) - -See also next section. - -****************************************************** -*** USERS UPGRADING FROM 2.16.0, 2.14.3 OR EARLIER *** -****************************************************** - -*** SECURITY ISSUES RESOLVED *** - -- When a new product is added to an installation with 47 groups or more and - "usebuggroups" is enabled, the new group will be assigned a groupset bit - using Perl math that is not exact beyond 2^48. This results in the new - group being defined with a "bit" that has several bits set. As users are - given access to the new group, those users will also gain access to - spurious lower group privileges. Also, group bits were not always reused - when groups were deleted. - (bug 167485) - -- The email interface had another insecure single parameter system call. This - could potentially allow arbitrary shell commands to be run. This file is - not supported at this time, but as long as we knew about the problem, we - couldn't overlook it. - (bug 163024) - -*** Bug fixes of note *** - -- The email interface was broken. This was a 2.14.3 regression. This file - is not supported at this time, but as long as we knew about the problem, we - couldn't overlook it. - (bug 160631) - -*********************************************** -*** USERS UPGRADING FROM 2.14.5 OR EARLIER *** -*********************************************** - -*** SECURITY ISSUES RESOLVED *** - -- The bug reporter could set the priority even when - 'letsubmitterchoosepriority' was off. - (bug 63018) - -- Most CGIs are now templatized. This helps to make it - easier to remember to HTML filter values and easier to spot - when they are not, preventing cross site scripting attacks. - (bug 86168) - -- Most CGIs now run in taint mode. This helps to prevent - failure to validate errors. - (bug 108982) - -*** IMPORTANT CHANGES *** - -- 2.16 introduces "templatization", a new feature that allows - administrators to easily customize the HTML output (the "look and feel") - of Bugzilla without altering Perl code. Bugzilla uses the - "Template Toolkit" for this. Please see the "Template Customization" - section of the Bugzilla Guide for more details. - - Administrators who ran the 2.15 development version with custom - templates should check the templates are still valid, as file names - and file paths have changed. - - Most output is now templatized. This process will be complete next - milestone. - - For speed, compiled templates are cached on disk. If you modify the - templates, the toolkit will normally detect the changes, and recompile the - changed templates. - - Adding new directories anywhere inside the template directory may cause - permission errors if you don't have a webservergroup specified in - localconfig. If you see these, rerun checksetup.pl as root. If you do not - have root access, or cannot get someone who does to do this for you, you can - rename the data/template directory to data/template.old (or any other name - Bugzilla doesn't use). Then rerun checksetup.pl to regenerate the compiled - templates. - (bug 86168, 97832) - -- Administrators can now configure maximum attachment sizes. These - should remain below the maximum size for your MySQL server, or you - will get obscure MySQL errors if you attach a bigger attachment. - - To find out the current size attachment that MySQL can accept, type - the command 'mysqladmin variables' and find out the value of the - 'max_allowed_packet' varible in bytes. - - To change the maximum size that MySQL can accept you can alter this - variable in your 'my.cnf' file. - (bug 91664) - -- Perl 5.004 is no longer supported because the Template Toolkit - requires 5.005. - (bug 97721) - -- New module requirements: Text::Wrap, Template [requires AppConfig], - File::Spec. - (bugs 97784, 84338, 103778) - -- The index page is now a CGI instead of an HTML page. You should remove - any existing index.html file and make sure your web server allows index.cgi - to be the default page in a directory. If you are not able to do that you - can instead set index_html in the 'localconfig' file to 1 and checksetup.pl - will create a redirect page for you. - (bug 80183) - -- It is now recommended that administrators run "processmail rescanall" - after upgrading to 2.16 or beyond. - - This will send out notification emails for changes that were - made but not emailed, due to Bugzilla bugs. All known - causes of this have been fixed in this version (bug 104589 and 99519). - - It is also recommended that this be run nightly to avoid - lengthy delays in future if this problem reoccurs. - (bug 106377) - -- In parallel with templatization, a lot of changes have been made to the HTML - output of the Bugzilla CGIs. This could break code that attempts to parse - such code. For example, this breaks mozbot. - (no bug number) - -- The "HTML template" parameters (headerhtml, bodyhtml, footerhtml, - errorhtml, bannerhtml, blurbhtml, mostfreqhtml, entryheaderhtml) have now - been moved to Template Toolkit templates. If you have modified these - parameters you will need to make corresponding changes to the corresponding - templates. Your old parameter values will be moved to a file called - old-params.txt by checksetup.pl. - - The old parameters correspond to files in template/en/default as follows: - - headerhtml: global/header.html.tmpl - footerhtml: global/footer.html.tmpl - bannerhtml: global/banner.html.tmpl - blurbhtml: global/banner.html.tmpl - mostfreqhtml: reports/duplicates*.html.tmpl - entryheaderhtml: bug/create/user-message.html.tmpl - - (bug 140437) - -*** Other changes of note *** - -- The query page has been redesigned for better user friendliness. - (bug 98707) -- Users can now change their email account. - (bug 23067) -- "Dependent Bug Changed" notification emails now contain the - dependent bug's summary and URL. - (bug 28736, 113383) -- Bugs with severity "critical", "blocker", and "enhancement" are - visually differentiated on bug lists for browsers with sufficient - CSS support. - (bug 28884) -- Bugzilla now has a sidebar for the Mozilla browser. - (bug 37339) -- A link to just created attachments now appears in notification - email. - (bug 66651) -- Comments now have numbers and can be referenced with - autohyperlinkifying similar to bugs. - (bug 71840) -- The attachment system has been rewritten, supporting new - "attachment statuses" (like keywords, but for attachments), - the ability to obsolete attachments, edit attachment MIME type, - and edit whether the attachment is a patch. - (bugs 84338, 75176) -- syncshadowdb now supports a configurable temp file location, - and properly shuts down Bugzilla while running. - (bug 75840) -- Dependency tree now lets you exclude resolved bugs and bugs - below a specified depth. - (bugs 83058) -- The "strictvaluechecks" parameter has gone away. These checks - are now always done. - (bug 119715) -- The midair collision page now shows all changes since the bug - page was loaded, not just the last one. - (bug 108312) -- Added support for making dependency graphs with 'dot', which - is better at creating complex graphs than 'webdot'. - (bug 120537) - -*** Bug fixes of note *** - -- Bugzilla scripts are now usually not terminated when the browser - window they are running in is closed. This caused hard to - reproduce bugs. - (bug 104589) -- On browsers that "reflow" the page, large component / milestone / - version fields were extremely slow to reflow when you altered - the product field. - (bug 96534) -- The selection in the component / milestone / version fields is - no longer lost when you change the selection in the product - field or use the back/forward buttons in your browser to return - to the page. - (bug 97966) -- You could not reverse dependencies in one step. - (bug 82143) -- Mass reassignment of non-open bugs will no longer reopen them. - (bug 30731) -- Attempting to bulk change no bugs will now give a user-friendly - error message. - (bug 90333) -- If you make a change to a bug where you only add yourself to CC, - email notifications are now properly sent out for MySQL 3.23. - (bug 99519) -- Bug entry now properly validates the data it has been sent. - (bug 107743) -- Midair collision checks will now properly work in all situations - where dependencies have changed. - (bug 73502) -- Browsers can no longer corrupt the params file if they use the "wrong" - end-of-line markers. - (bug 92500) -- The MySQL port defined in localconfig is now properly honoured. - (bug 98368) -- Apostrophes in component/milestone/version names no longer cause - a problem on the query page. - (bug 30689/42810) -- File attachment comments will now wrap. - (bug 52060) -- Saved queries are no longer mangled if you need to log in again, - for example if you had cookies off. - (bug 38835) -- Bug counts (on reports.cgi) were very slow if you had to - count a lot of bugs. - (bug 63249) -- 2.14 introduced options to let people see a bug when their name - is on it but who aren't in the groups the bug is restricted - to. These only allowed the people to view the bugs directly, - and not see them on buglists and receive email about them. - (bugs 95024, 97469) -- A new 'cookiepath' parameter on editparams.cgi allows multiple - Bugzilla installations to exist on one host without problems. - (bug 19910) -- whineatnews.pl now respects the 'sendmailnow' parameter. - (bug 52782) -- The query page came up even when Bugzilla was shut down. - (bug 121747) -- Quicksearch gave a weird error message when Bugzilla was - shut down. - (bug 121741) -- Operating system detection fixes. - (bugs 92763, 135666) -- QA contacts now receive emails when a new bug is created and - their only email preference was being added or removed from QA. - (bug 143091) - -*********************************************** -*** USERS UPGRADING FROM 2.14.4 OR EARLIER *** -*********************************************** - -See section above about users upgrading from 2.16.1 or earlier, -2.14.4 or earlier. - -*********************************************** -*** USERS UPGRADING FROM 2.14.3 OR EARLIER *** -*********************************************** - -See section above about users upgrading from 2.16.0 or earlier. - -*********************************************** -*** USERS UPGRADING FROM 2.14.2 OR EARLIER *** -*********************************************** - -*** SECURITY ISSUES RESOLVED *** - -- Basic maintenance on contrib/bug_email.pl and - contrib/bugzilla_email_append.pl which also fixes a - possible security hole with a misuse of a system() call. - These files are not supported at this time, but as long - as we knew about the problem, we couldn't overlook it. - (bug 154008) - -*** Bug fixes of note *** - -- The fix for bug 130821 in 2.14.2 broke being able to sort - bug lists on more than one field. buglist.cgi now allows - you to sort on more than one field again. - (bug 152138) - -*********************************************** -*** USERS UPGRADING FROM 2.14.1 OR EARLIER *** -*********************************************** - -*** SECURITY ISSUES RESOLVED *** - -- queryhelp.cgi no longer shows confidential products to - people it shouldn't. - (bug 126801) - -- It was possible for a user to bypass the IP check by - setting up a fake reverse DNS, if the Bugzilla web server - was configured to do reverse DNS lookups. Apache is not - configured as such by default. This is not a complete - exploit, as the user's login cookie would also need to - be divulged for this to be a problem. - (bug 129466) - -- In some situations the data directory became world writeable. - (bug 134575) - -- Any user with access to editusers.cgi could delete a user - regardless of whether 'allowuserdeletion' is on. - (bug 141557) - -- Real names were not HTML filtered, causing possible cross - site scripting attacks. - (bug 146447, 147486) - -- Mass change would set the groupset of every bug to be the - groupset of the first bug. - (bug 107718) - -- Some browsers (eg NetPositive) interacted with Bugzilla - badly and could have various form problems, including - removing group restrictions on bugs. - (bug 148674) - -- It was possible for random confidential information to be - divulged, if the shadow database was in use and became - corrupted. - (bug 92263) - -- The bug list sort order is now stricter about the SQL it will accept, - ensuring you use correct column name syntax. Before this, there were - some syntax checks, so it is not known whether this problem was - exploitable. - (bug 130821) - -******************************************** -*** USERS UPGRADING FROM 2.14 OR EARLIER *** -******************************************** - -The 2.14.1 release fixes several security issues that became -known to us after the Bugzilla 2.14 release. - -*** SECURITY ISSUES RESOLVED *** - -- If LDAP Authentication was being used, Bugzilla would allow - you to log in as anyone if you left the password blank. - (bug 54901) - -- It was possible to add comments or file a bug as someone else - by editing the HTML on the appropriate submission page before - submitting the form. User identity is checked now, and the - form values suggesting the user are now ignored. - (bug 108385, 108516) - -- The Product popup menu on the show_bug form listed all - products, even if the user didn't have access to all of them. - It now only shows products the user has access to (and the - product the bug is in, if the user is viewing it because of - some other override). - (bug 102141) - -- If a user had any blessgroupset privileges (the ability to - change only specific privileges for other users), it was - possible to change your own groupset (privileges) by - altering the page HTML before submitting on editusers.cgi. - (bug 108821) - -- An untrusted variable was echoed back to user in the HTML - output if there was a login error while editing votes. - (bug 98146) - -- buglist.cgi had an undocumented parameter that allowed you - to pass arbitrary SQL for the "WHERE" part of a query. - This has been disabled. - (bug 108812) - -- It was possible for a user to send arbitrary SQL by inserting - single quotes in the "mybugslink" field in the user - preferences. - (bug 108822) - -- buglist.cgi was not validating that the field names being - passed from the "boolean chart" query form were valid field - names, thus allowing arbitrary SQL to be inserted if you - edited the HTML by hand before submitting the form. - (bug 109679) - -- long_list.cgi was not validating that the bug ID parameter - was actually a number, allowing arbitrary SQL to be inserted - if you edited the HTML by hand. - (bug 109690) - -******************************************** -*** USERS UPGRADING FROM 2.12 OR EARLIER *** -******************************************** - -*** SECURITY ISSUES RESOLVED *** - -- Multiple instances of unauthorized access to confidential - bugs have been fixed. - (bug 39524, 39526, 39527, 39531, 39533, 70189, 82781) - -- Multiple instances of untrusted parameters not being - checked/escaped was fixed. These included definite security - holes. - (bug 38854, 38855, 38859, 39536, 87701, 95235) - -- After logging in passwords no longer appear in the URL. - (bug 15980) - -- Procedures to prevent unauthorized access to confidential - files are now simpler. In particular the shadow directory - no longer exists and the data/comments file no longer needs - to be directly accessible, so the entire data directory can - be blocked. However, no changes are required here if you - have a properly secured 2.12 installation as no new files - must be protected. - (bug 71552, 73191) - -- If they do not already exist, checksetup.pl will attempt to - write Apache .htaccess files by default, to prevent - unauthorized access to confidential files. You can turn this - off in the localconfig file. - (bug 76154) - -- Sanity check can now only be run by people in the 'editbugs' - group. Although it would be better to have a separate - group, this is not possible until the limitation on the - number of groups allowed has been removed. - (bug 54556) - -- The password is no longer stored in plaintext form. It will - be eradicated next time you run checksetup.pl. A user must - now change their password via a password change request that - gets validated at their e-mail account, rather than have it - mailed to them. - (bug 74032) - -- When you are using product groups and you move a bug between - products (single or mass change), the bug will no longer be - restricted to the old product's group (if it was) and will - be restricted to the new product's group. - (bug 66235) - -- There are now options on a bug to choose whether the - reporter, and CCs can access a bug even if they aren't in - groups the bug it is restricted to. - (bug 39816) - -- You can no longer mark a bug as a duplicate of a bug you - can't see, and if you mark a bug a duplicate of a bug - the reporter cannot see you will be given options as to - what to do regarding adding the reporter of the resolved - bug to the CC of the open bug. - (bug 96085) - -*** IMPORTANT CHANGES *** - -- Bugzilla 2.14 no longer supports old email tech. Upon - upgrading, all users will be moved over to new email tech. - This should speed up upgrading for installations with - a large number of bugs. - (bug 71552) - -- There is new functionality for people to see why they are - receiving notification mails. - - Previously, some people filtered old email tech - notifications depending on whether they were in the To or the - CC header, in order to get a limited way of determining why - they were receiving the notification for filtering purposes. - - Existing installations will need to make changes to support - this feature. The receive reasons can be added to the - notifications as a header and/or in the body. To add these - you will need to modify your newchangedmail parameter on - editparams.cgi, either by resetting it or appropriately - modifying it. The header value is specified by - %reasonsheader% and the body by %reasonsbody%. For example, - the new default parameter is: - - -------------------------------------------------- - From: bugzilla-daemon - To: %to% - Subject: [Bug %bugid%] %neworchanged%%summary% - X-Bugzilla-Reason: %reasonsheader% - - %urlbase%show_bug.cgi?id=%bugid% - - %diffs% - - - - %reasonsbody% - -------------------------------------------------- - - (bug 26194) - -- Very long fields (especially multi-valued fields like keywords, - CCs, dependencies) on bug activity and notifications previously - could get truncated, resulting in useless notifications and data - loss on bug activity. Now the multi-valued fields only show - changes, and very big changes are split into multiple lines. - Where data loss has already occurred on bug activity, it is - indicated using question marks. - (bug 55161, 92266) - -- Previously, when a product's voting preferences changed all - votes were removed from all the bugs in the product. Also, - when a bug was moved to another product, all of its votes - were removed. This no longer occurs. - - Instead, if the action would leave one or more bugs with - greater than the maximum number of votes per person per bug, - the number of votes will be reduced to the maximum. The - person will still be notified of this as before. - - If the action would leave a user with more votes in a product - than is allowed, the limit will be breached so as to not lose - votes. However the user will not be able to update their - votes except to fix this situation. No further action is taken - in this version to make sure that the user does this. - (bug 28882, 92593) - -*** Other changes of note *** - -- Groups can now be marked inactive, so you can't add a new - restriction on that group to a bug, while leaving bugs that - were previously restricted on that group alone. - (bug 75482) -- backdoor.cgi has been removed from the installation. It was - old code that was Netscape-specific and its name was scaring - people. - (bug 87983) -- You can now add or remove from CC on the bulk change page. - (bug 12819) -- New users created by administrators are now automatically - inserted into groups according to the group's regular - expression. Administrators must edit the user in a second - step to override these choices. Previously the - administrator specified these explicitly which could lead - to incorrect settings. - (bug 45164) -- The userregexp of system groups can now be edited without - resorting to direct database access. - (bug 65290) - -*** Bug fixes of note *** - -- The bug list page was sometimes bringing up a not logged in - footer when the user was logged in and the installation was - using a shadow database. - (bug 47914) -- You can now view the bug summary in your browser title for - a group-restricted bug if you have proper permissions. - (bug 71767) -- Quick search for search terms did not work in IE5. - This has been worked around. - (bug 77699) -- Quick search for search terms crashed NN4.76/4.77 for Unix. - This has been worked around. - (bug 83619) -- Queries on bugs you have commented on using the "added - comment" feature should be a lot faster and not time out - on large installations due to the addition of an index. - (bug 57350) -- You can now alter group settings on bulk change for groups - that aren't on for all bugs or off for all bugs. - (bug 84714) -- New bug notifications now include the CC and QA fields. - (bug 28458) -- Bugzilla is now more Windows friendly, although it is still - not an official platform. - (bug 88179, 29064) -- Passwords are now encrypted using Perl's encrypt function. - This makes Bugzilla more portable to more operating systems. - (bug 77473) -- Bugzilla didn't properly shut down when told to - some - queries could still be sent to the database. - (bug 95082) - -******************************************** -*** USERS UPGRADING FROM 2.10 OR EARLIER *** -******************************************** - -*** SECURITY ISSUES RESOLVED *** - -- Some security holes have been fixed where shell escape characters - could be passed to Bugzilla, allowing remote users to execute - system commands on the web server. - -*** IMPORTANT CHANGES *** - -- There is now a facility for users to choose the sort of - notifications they wish to receive. This facility will - probably be improved in future versions. - (bug 17464) - -- "Changed" will no longer appear on the subject line of - change notification emails. Because of this, you should - change the subject line in your 'changedmail' and - 'newchangedmail' params on editparams.cgi. The subject - line needs to be changed from - - Subject: [Bug %bugid%] %neworchanged% - %summary% - - to: - - Subject: [Bug %bugid%] %neworchanged%%summary% - - or whatever is appropriate for the subject you are using - on your system. Note the removal of the " - " in the - middle. - (bug 29820) - -*** Other changes of note *** - -- Bug titles now appear in the page title, and will hence - display in the user's browser's bookmarks and history. - (bug 22041) -- Edit groups functionality (editgroups.cgi). - (bug 25010) -- Support for moving bugs to other Bugzilla databases. - (bug 36133) -- Bugzilla now can generate a frequently reported bugs list - based on what duplicates you receive. - (bug 25693) -- When installing Bugzilla fresh, the administrator account is - now created in checksetup.pl. - (bug 17773) -- Stored queries now show their name above the bug list, which - helps the user when they have multiple bug lists in multiple - browser windows. It also appears in the page title, and will - hence display in the user's browser's bookmarks and history. - (bug 52228) -- All states and resolutions can now be collected for charting. - (bug 6682) -- A new search-engine-like "quick search" feature appears on - the front page to try and making searching easier. - (bug 69793) -- Querying on dependencies now works in the advanced query - section of the query page. - (bug 30823) -- When a bug is marked as a duplicate, the reporter of the - resolved bug is automatically added to the CC list of the - open bug. - (bug 28676) - -*** Bug fixes of note *** - -- Notification emails will now always be sent to QA contacts. - Previously they wouldn't if you were using new email tech. - (bug 30826) -- When marking a bug as a duplicate, the duplicate stamp marked - on the open bug will no longer be written too early (such as - on mid-air collisions). - (bug 7873) -- Various bug fixes were made to the initial assignee and QA - of a component. It is no longer possible to enter an - invalid address. They will also now properly update when - a user's email address is changed. Sanity check will now - check these. - (bug 66876) -- Administrators can no longer create an email accounts that do - not match the global email regular expression parameter. - Previously this could occur and would cause sanity check - errors. - (bug 32971) -- The resolution field can no longer become empty when the - bug is resolved. This occurred because of midair collisions. - (bug 49306) - -******************************************* -*** USERS UPGRADING FROM 2.8 OR EARLIER *** -******************************************* - -This version of Bugzilla cannot upgrade from version 2.8 (released -November 19, 1999). You will first have to upgrade to Bugzilla 3.6 and -then upgrade to the latest release. - -If you are upgrading from a version earlier than 2.8, See the -PGRADING-pre-2.8 file in Bugzilla 3.0 for information -on upgrading from a version that is earlier than 2.8. diff --git a/docs/en/rst/_static/stuff.css b/docs/en/rst/_static/stuff.css new file mode 100644 index 000000000..c3d8ea781 --- /dev/null +++ b/docs/en/rst/_static/stuff.css @@ -0,0 +1,3 @@ +@import 'default.css'; + +dt { font-weight: bold; } diff --git a/docs/en/rst/about.rst b/docs/en/rst/about.rst new file mode 100644 index 000000000..199988bf4 --- /dev/null +++ b/docs/en/rst/about.rst @@ -0,0 +1,184 @@ + + +.. _about: + +================ +About This Guide +================ + +.. _introduction: + +Introduction +############ + +This is the documentation for version |version| of Bugzilla, a +bug-tracking system from mozilla.org. +Bugzilla is an enterprise-class piece of software +that tracks millions of bugs and issues for hundreds of +organizations around the world. + +The most current version of this document can always be found on the +`Bugzilla +Documentation Page `_. + +.. _copyright: + +Copyright Information +##################### + +This document is copyright (c) 2000-2012 by the various +Bugzilla contributors who wrote it. + + 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 :ref:`gfdl`. + +If you have any questions regarding this document, its +copyright, or publishing this document in non-electronic form, +please contact the Bugzilla Team. + +.. _disclaimer: + +Disclaimer +########## + +No liability for the contents of this document can be accepted. +Follow the instructions herein at your own risk. +This document may contain errors +and inaccuracies that may damage your system, cause your partner +to leave you, your boss to fire you, your cats to +pee on your furniture and clothing, and global thermonuclear +war. Proceed with caution. + +Naming of particular products or brands should not be seen as +endorsements, with the exception of the term "GNU/Linux". We +wholeheartedly endorse the use of GNU/Linux; it is an extremely +versatile, stable, +and robust operating system that offers an ideal operating +environment for Bugzilla. + +Although the Bugzilla development team has taken great care to +ensure that all exploitable bugs have been fixed, security holes surely +exist in any piece of code. Great care should be taken both in +the installation and usage of this software. The Bugzilla development +team members assume no liability for your use of Bugzilla. You have +the source code, and are responsible for auditing it yourself to ensure +your security needs are met. + +.. COMMENT: Section 2: New Versions + +.. _newversions: + +New Versions +############ + +This is version |version| of The Bugzilla Guide. It is so named +to match the current version of Bugzilla. + +.. todo:: BZ-DEVEL This version of the guide, like its associated Bugzilla version, is a + development version. + +The latest version of this guide can always be found at ``_. However, you should read +the version which came with the Bugzilla release you are using. + +In addition, there are Bugzilla template localization projects in +`several languages `_. +They may have translated documentation available. If you would like to +volunteer to translate the Guide into additional languages, please visit the +`Bugzilla L10n team `_ +page. + +.. _credits: + +Credits +####### + +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: + +.. COMMENT: TODO: This is evil... there has to be a valid way to get this look + +Matthew P. Barnson mbarnson@sisna.com + for the Herculean task of pulling together the Bugzilla Guide + and shepherding it to 2.14. + +Terry Weissman terry@mozilla.org + for initially writing Bugzilla and creating the README upon + which the UNIX installation documentation is largely based. + +Tara Hernandez tara@tequilarists.org + for keeping Bugzilla development going strong after Terry left + mozilla.org and for running landfill. + +Dave Lawrence dkl@redhat.com + for providing insight into the key differences between Red + Hat's customized Bugzilla. + +Dawn Endico endico@mozilla.org + for being a hacker extraordinaire and putting up with Matthew's + incessant questions and arguments on irc.mozilla.org in #mozwebtools + +Jacob Steenhagen jake@bugzilla.org + for taking over documentation during the 2.17 development + period. + +Dave Miller justdave@bugzilla.org + for taking over as project lead when Tara stepped down and + continually pushing for the documentation to be the best it can be. + +Thanks also go to the following people for significant contributions +to this documentation: +Kevin Brannen, Vlad Dascalu, Ben FrantzDale, Eric Hanson, Zach Lipton, Gervase Markham, Andrew Pearson, Joe Robins, Spencer Smith, Ron Teitelbaum, Shane Travis, Martin Wulffeld. + +Also, thanks are due to the members of the +`mozilla.support.bugzilla `_ +newsgroup (and its predecessor, netscape.public.mozilla.webtools). +Without your discussions, insight, suggestions, and patches, +this could never have happened. + +.. _conventions: + +Document Conventions +#################### + +This document uses the following conventions: + +.. caution:: This is a caution. Make sure to read this to not be in trouble! + +.. tip:: This is a hint or tip, especially about some configuration tweaks. + +.. note:: This is just a note, for your information. + +.. warning:: This is a warning, something you should take care of. + +A filename or a path to a filename is displayed like this: +:file:`/path/to/filename.ext` + +A command to type in the shell is displayed like this: +:command:`command --arguments` + +bash$ represents a normal user's prompt under bash shell + +bash# represents a root user's prompt under bash shell + +A word which is in the glossary will appear like this: +Bugzilla + +A sample of code is illustrated like this: + +:: + + First Line of Code + Second Line of Code + ... + +This documentation is maintained in ReStructured Text format. +Changes are best submitted as diffs, attached +to a bug filed in the `Bugzilla Documentation `_ +component. + diff --git a/docs/en/rst/administration.rst b/docs/en/rst/administration.rst new file mode 100644 index 000000000..2bac84499 --- /dev/null +++ b/docs/en/rst/administration.rst @@ -0,0 +1,2149 @@ + + +.. _administration: + +====================== +Administering Bugzilla +====================== + +.. _parameters: + +Bugzilla Configuration +###################### + +Bugzilla is configured by changing various parameters, accessed +from the "Parameters" link in the Administration page (the +Administration page can be found by clicking the "Administration" +link in the footer). The parameters are divided into several categories, +accessed via the menu on the left. Following is a description of the +different categories and important parameters within those categories. + +.. _param-requiredsettings: + +Required Settings +================= + +The core required parameters for any Bugzilla installation are set +here. These parameters must be set before a new Bugzilla installation +can be used. Administrators should review this list before +deploying a new Bugzilla installation. + +maintainer + Email address of the person + responsible for maintaining this Bugzilla installation. + The address need not be that of a valid Bugzilla account. + +urlbase + Defines the fully qualified domain name and web + server path to this Bugzilla installation. + For example, if the Bugzilla query page is + :file:`http://www.foo.com/bugzilla/query.cgi`, + the ``urlbase`` should be set + to :file:`http://www.foo.com/bugzilla/`. + +docs_urlbase + Defines path to the Bugzilla documentation. This can be a fully + qualified domain name, or a path relative to "urlbase". + For example, if the "Bugzilla Configuration" page + of the documentation is + :file:`http://www.foo.com/bugzilla/docs/html/parameters.html`, + set the ``docs_urlbase`` + to :file:`http://www.foo.com/bugzilla/docs/html/`. + +sslbase + Defines the fully qualified domain name and web + server path for HTTPS (SSL) connections to this Bugzilla installation. + For example, if the Bugzilla main page is + :file:`https://www.foo.com/bugzilla/index.cgi`, + the ``sslbase`` should be set + to :file:`https://www.foo.com/bugzilla/`. + +ssl_redirect + If enabled, Bugzilla will force HTTPS (SSL) connections, by + automatically redirecting any users who try to use a non-SSL + connection. + +cookiedomain + Defines the domain for Bugzilla cookies. This is typically left blank. + If there are multiple hostnames that point to the same webserver, which + require the same cookie, then this parameter can be utilized. For + example, If your website is at + :file:`https://www.foo.com/`, setting this to + :file:`.foo.com/` will also allow + :file:`bar.foo.com/` to access Bugzilla cookies. + +cookiepath + Defines a path, relative to the web server root, that Bugzilla + cookies will be restricted to. For example, if the + :command:`urlbase` is set to + :file:`http://www.foo.com/bugzilla/`, the + :command:`cookiepath` should be set to + :file:`/bugzilla/`. Setting it to "/" will allow all sites + served by this web server or virtual host to read Bugzilla cookies. + +utf8 + Determines whether to use UTF-8 (Unicode) encoding for all text in + Bugzilla. New installations should set this to true to avoid character + encoding problems. Existing databases should set this to true only + after the data has been converted from existing legacy character + encoding to UTF-8, using the + :file:`contrib/recode.pl` script. + + .. note:: If you turn this parameter from "off" to "on", you must + re-run :file:`checksetup.pl` immediately afterward. + +shutdownhtml + If there is any text in this field, this Bugzilla installation will + be completely disabled and this text will appear instead of all + Bugzilla pages for all users, including Admins. Used in the event + of site maintenance or outage situations. + + .. note:: Although regular log-in capability is disabled + while :command:`shutdownhtml` + is enabled, safeguards are in place to protect the unfortunate + admin who loses connection to Bugzilla. Should this happen to you, + go directly to the :file:`editparams.cgi` (by typing + the URL in manually, if necessary). Doing this will prompt you to + log in, and your name/password will be accepted here (but nowhere + else). + +announcehtml + Any text in this field will be displayed at the top of every HTML + page in this Bugzilla installation. The text is not wrapped in any + tags. For best results, wrap the text in a ``
`` + tag. Any style attributes from the CSS can be applied. For example, + to make the text green inside of a red box, add ``id=message`` + to the ``
`` tag. + +proxy_url + If this Bugzilla installation is behind a proxy, enter the proxy + information here to enable Bugzilla to access the Internet. Bugzilla + requires Internet access to utilize the + :command:`upgrade_notification` parameter (below). If the + proxy requires authentication, use the syntax: + :file:`http://user:pass@proxy_url/`. + +upgrade_notification + Enable or disable a notification on the homepage of this Bugzilla + installation when a newer version of Bugzilla is available. This + notification is only visible to administrators. Choose "disabled", + to turn off the notification. Otherwise, choose which version of + Bugzilla you want to be notified about: "development_snapshot" is the + latest release on the trunk; "latest_stable_release" is the most + recent release available on the most recent stable branch; + "stable_branch_release" the most recent release on the branch + this installation is based on. + +.. _param-admin-policies: + +Administrative Policies +======================= + +This page contains parameters for basic administrative functions. +Options include whether to allow the deletion of bugs and users, +and whether to allow users to change their email address. + +.. _param-user-authentication: + +User Authentication +=================== + +This page contains the settings that control how this Bugzilla +installation will do its authentication. Choose what authentication +mechanism to use (the Bugzilla database, or an external source such +as LDAP), and set basic behavioral parameters. For example, choose +whether to require users to login to browse bugs, the management +of authentication cookies, and the regular expression used to +validate email addresses. Some parameters are highlighted below. + +emailregexp + Defines the regular expression used to validate email addresses + used for login names. The default attempts to match fully + qualified email addresses (i.e. 'user@example.com') in a slightly + more restrictive way than what is allowed in RFC 2822. + Some Bugzilla installations allow only local user names (i.e 'user' + instead of 'user@example.com'). In that case, this parameter + should be used to define the email domain. + +emailsuffix + This string is appended to login names when actually sending + email to a user. For example, + If :command:`emailregexp` has been set to allow + local usernames, + then this parameter would contain the email domain for all users + (i.e. '@example.com'). + +.. _param-attachments: + +Attachments +=========== + +This page allows for setting restrictions and other parameters +regarding attachments to bugs. For example, control size limitations +and whether to allow pointing to external files via a URI. + +.. _param-bug-change-policies: + +Bug Change Policies +=================== + +Set policy on default behavior for bug change events. For example, +choose which status to set a bug to when it is marked as a duplicate, +and choose whether to allow bug reporters to set the priority or +target milestone. Also allows for configuration of what changes +should require the user to make a comment, described below. + +commenton* + 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. + 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:: 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!) + +noresolveonopenblockers + This option will prevent users from resolving bugs as FIXED if + they have unresolved dependencies. Only the FIXED resolution + is affected. Users will be still able to resolve bugs to + resolutions other than FIXED if they have unresolved dependent + bugs. + +.. _param-bugfields: + +Bug Fields +========== + +The parameters in this section determine the default settings of +several Bugzilla fields for new bugs, and also control whether +certain fields are used. For example, choose whether to use the +"target milestone" field or the "status whiteboard" field. + +useqacontact + This allows you to define an email address for each component, + in addition to that of the default assignee, who will be sent + carbon copies of incoming bugs. + +usestatuswhiteboard + 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. + +.. _param-bugmoving: + +Bug Moving +========== + +This page controls whether this Bugzilla installation allows certain +users to move bugs to an external database. If bug moving is enabled, +there are a number of parameters that control bug moving behaviors. +For example, choose which users are allowed to move bugs, the location +of the external database, and the default product and component that +bugs moved *from* other bug databases to this +Bugzilla installation are assigned to. + +.. _param-dependency-graphs: + +Dependency Graphs +================= + +This page has one parameter that sets the location of a Web Dot +server, or of the Web Dot binary on the local system, that is used +to generate dependency graphs. Web Dot is a CGI program that creates +images from :file:`.dot` graphic description files. If +no Web Dot server or binary is specified, then dependency graphs will +be disabled. + +.. _param-group-security: + +Group Security +============== + +Bugzilla allows for the creation of different groups, with the +ability to restrict the visibility of bugs in a group to a set of +specific users. Specific products can also be associated with +groups, and users restricted to only see products in their groups. +Several parameters are described in more detail below. Most of the +configuration of groups and their relationship to products is done +on the "Groups" and "Product" pages of the "Administration" area. +The options on this page control global default behavior. +For more information on Groups and Group Security, see +:ref:`groups` + +makeproductgroups + Determines whether or not to automatically create groups + when new products are created. If this is on, the groups will be + used for querying bugs. + +usevisibilitygroups + If selected, user visibility will be restricted to members of + groups, as selected in the group configuration settings. + Each user-defined group can be allowed to see members of selected + other groups. + For details on configuring groups (including the visibility + restrictions) see :ref:`edit-groups`. + +querysharegroup + The name of the group of users who are allowed to share saved + searches with one another. For more information on using + saved searches, see :ref:`savedsearches`. + +.. _bzldap: + +LDAP Authentication +=================== + +LDAP authentication is a module for Bugzilla's plugin +authentication architecture. This page contains all the parameters +necessary to configure Bugzilla for use with LDAP authentication. + +The existing authentication +scheme for Bugzilla uses email addresses as the primary user ID, and a +password to authenticate that user. All places within Bugzilla that +require a user ID (e.g assigning a bug) use the email +address. The LDAP authentication builds on top of this scheme, rather +than replacing it. The initial log-in is done with a username and +password for the LDAP directory. Bugzilla tries to bind to LDAP using +those credentials and, if successful, tries to map this account to a +Bugzilla account. If an LDAP mail attribute is defined, the value of this +attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP +username to form a full email address. If an account for this address +already exists in the Bugzilla installation, it will log in to that account. +If no account for that email address exists, one is created at the time +of login. (In this case, Bugzilla will attempt to use the "displayName" +or "cn" attribute to determine the user's full name.) After +authentication, all other user-related tasks are still handled by email +address, not LDAP username. For example, bugs are still assigned by +email address and users are still queried by email address. + +.. caution:: Because the Bugzilla account is not created until the first time + a user logs in, a user who has not yet logged is unknown to Bugzilla. + This means they cannot be used as an assignee or QA contact (default or + otherwise), added to any CC list, or any other such operation. One + possible workaround is the :file:`bugzilla_ldapsync.rb` + script in the :file:`contrib` + directory. Another possible solution is fixing + `bug + 201069 `_. + +Parameters required to use LDAP Authentication: + +user_verify_class + If you want to list ``LDAP`` here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + well, you may otherwise not be able to log back in to Bugzilla once + you log out. + If this happens to you, you will need to manually edit + :file:`data/params` and set user_verify_class to + ``DB``. + +LDAPserver + This parameter should be set to the name (and optionally the + port) of your LDAP server. If no port is specified, it assumes + the default LDAP port of 389. + For example: ``ldap.company.com`` + or ``ldap.company.com:3268`` + You can also specify a LDAP URI, so as to use other + protocols, such as LDAPS or LDAPI. If port was not specified in + the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' + schemes respectively. + + .. tip:: In order to use SSL with LDAP, specify a URI with "ldaps://". + This will force the use of SSL over port 636. + For example, normal LDAP: + ``ldap://ldap.company.com``, LDAP over SSL: + ``ldaps://ldap.company.com`` or LDAP over a UNIX + domain socket ``ldapi://%2fvar%2flib%2fldap_sock``. + +LDAPbinddn \[Optional] + Some LDAP servers will not allow an anonymous bind to search + the directory. If this is the case with your configuration you + should set the LDAPbinddn parameter to the user account Bugzilla + should use instead of the anonymous bind. + Ex. ``cn=default,cn=user:password`` + +LDAPBaseDN + The LDAPBaseDN parameter should be set to the location in + your LDAP tree that you would like to search for email addresses. + Your uids should be unique under the DN specified here. + Ex. ``ou=People,o=Company`` + +LDAPuidattribute + The LDAPuidattribute parameter should be set to the attribute + which contains the unique UID of your users. The value retrieved + from this attribute will be used when attempting to bind as the + user to confirm their password. + Ex. ``uid`` + +LDAPmailattribute + The LDAPmailattribute parameter should be the name of the + attribute which contains the email address your users will enter + into the Bugzilla login boxes. + Ex. ``mail`` + +.. _bzradius: + +RADIUS Authentication +===================== + +RADIUS authentication is a module for Bugzilla's plugin +authentication architecture. This page contains all the parameters +necessary for configuring Bugzilla to use RADIUS authentication. + +.. note:: Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. See :ref:`bzldap` for details. + +Parameters required to use RADIUS Authentication: + +user_verify_class + If you want to list ``RADIUS`` here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + well, you may otherwise not be able to log back in to Bugzilla once + you log out. + If this happens to you, you will need to manually edit + :file:`data/params` and set user_verify_class to + ``DB``. + +RADIUS_server + This parameter should be set to the name (and optionally the + port) of your RADIUS server. + +RADIUS_secret + This parameter should be set to the RADIUS server's secret. + +RADIUS_email_suffix + Bugzilla needs an e-mail address for each user account. + Therefore, it needs to determine the e-mail address corresponding + to a RADIUS user. + Bugzilla offers only a simple way to do this: it can concatenate + a suffix to the RADIUS user name to convert it into an e-mail + address. + You can specify this suffix in the RADIUS_email_suffix parameter. + If this simple solution does not work for you, you'll + probably need to modify + :file:`Bugzilla/Auth/Verify/RADIUS.pm` to match your + requirements. + +.. _param-email: + +Email +===== + +This page contains all of the parameters for configuring how +Bugzilla deals with the email notifications it sends. See below +for a summary of important options. + +mail_delivery_method + This is used to specify how email is sent, or if it is sent at + all. There are several options included for different MTAs, + along with two additional options that disable email sending. + "Test" does not send mail, but instead saves it in + :file:`data/mailer.testfile` for later review. + "None" disables email sending entirely. + +mailfrom + This is the email address that will appear in the "From" field + of all emails sent by this Bugzilla installation. Some email + servers require mail to be from a valid email address, therefore + it is recommended to choose a valid email address here. + +smtpserver + This is the SMTP server address, if the ``mail_delivery_method`` + parameter is set to SMTP. Use "localhost" if you have a local MTA + running, otherwise use a remote SMTP server. Append ":" and the port + number, if a non-default port is needed. + +smtp_username + Username to use for SASL authentication to the SMTP server. Leave + this parameter empty if your server does not require authentication. + +smtp_password + Password to use for SASL authentication to the SMTP server. This + parameter will be ignored if the ``smtp_username`` + parameter is left empty. + +smtp_ssl + Enable SSL support for connection to the SMTP server. + +smtp_debug + This parameter allows you to enable detailed debugging output. + Log messages are printed the web server's error log. + +whinedays + Set this to the number of days you want to let bugs go + in the CONFIRMED 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). + +globalwatcher + This allows you to define specific users who will + receive notification each time a new bug in entered, or when + an existing bug changes, according to the normal groupset + permissions. It may be useful for sending notifications to a + mailing-list, for instance. + +.. _param-patchviewer: + +Patch Viewer +============ + +This page contains configuration parameters for the CVS server, +Bonsai server and LXR server that Bugzilla will use to enable the +features of the Patch Viewer. Bonsai is a tool that enables queries +to a CVS tree. LXR is a tool that can cross reference and index source +code. + +.. _param-querydefaults: + +Query Defaults +============== + +This page controls the default behavior of Bugzilla in regards to +several aspects of querying bugs. Options include what the default +query options are, what the "My Bugs" page returns, whether users +can freely add bugs to the quip list, and how many duplicate bugs are +needed to add a bug to the "most frequently reported" list. + +.. _param-shadowdatabase: + +Shadow Database +=============== + +This page controls whether a shadow database is used, and all the +parameters associated with the shadow database. Versions of Bugzilla +prior to 3.2 used the MyISAM table type, which supports +only table-level write locking. With MyISAM, any time someone is making a change to +a bug, the entire table is locked until the write operation is complete. +Locking for write also blocks reads until the write is complete. + +The ``shadowdb`` 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. + +.. note:: As of version 3.2, Bugzilla no longer uses the MyISAM table type. + Instead, InnoDB is used, which can do transaction-based locking. + Therefore, the limitations the Shadow Database feature was designed + to workaround no longer exist. + +.. _admin-usermatching: + +User Matching +============= + +The settings on this page control how users are selected and queried +when adding a user to a bug. For example, users need to be selected +when choosing who the bug is assigned to, adding to the CC list or +selecting a QA contact. With the "usemenuforusers" parameter, it is +possible to configure Bugzilla to +display a list of users in the fields instead of an empty text field. +This should only be used in Bugzilla installations with a small number +of users. If users are selected via a text box, this page also +contains parameters for how user names can be queried and matched +when entered. + +Another setting called 'ajax_user_autocompletion' enables certain +user fields to display a list of matched user names as a drop down after typing +a few characters. Note that it is recommended to use mod_perl when +enabling 'ajax_user_autocompletion'. + +.. _useradmin: + +User Administration +################### + +.. _defaultuser: + +Creating the Default User +========================= + +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. + +.. tip:: If you wish to add more administrative users, add them to + the "admin" group and, optionally, edit the tweakparams, editusers, + creategroups, editcomponents, and editkeywords groups to add the + entire admin group to those groups (which is the case by default). + +.. _manageusers: + +Managing Other Users +==================== + +.. _user-account-search: + +Searching for existing users +---------------------------- + +If you have ``editusers`` privileges or if you are allowed +to grant privileges for some groups, the ``Users`` link +will appear in the Administration page. + +The first screen is a search form to search for existing user +accounts. You can run searches based either on the user ID, real +name or login name (i.e. the email address, or just the first part +of the email address if the "emailsuffix" parameter is set). +The search can be conducted +in different ways using the listbox to the right of the text entry +box. You can match by case-insensitive substring (the default), +regular expression, a *reverse* regular expression +match (which finds every user name which does NOT match the regular +expression), or the exact string if you know exactly who you are +looking for. The search can be restricted to users who are in a +specific group. By default, the restriction is turned off. + +The search returns a list of +users matching your criteria. User properties can be edited by clicking +the login name. The Account History of a user can be viewed by clicking +the "View" link in the Account History column. The Account History +displays changes that have been made to the user account, the time of +the change and the user who made the change. For example, the Account +History page will display details of when a user was added or removed +from a group. + +.. _createnewusers: + +Creating new users +------------------ + +.. _self-registration: + +Self-registration +~~~~~~~~~~~~~~~~~ + +By default, 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). If you want to disable +this self-registration, or if you want to restrict who can create his +own user account, you have to edit the ``createemailregexp`` +parameter in the ``Configuration`` page, see +:ref:`parameters`. + +.. _user-account-creation: + +Accounts created by an administrator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users with ``editusers`` privileges, such as administrators, +can create user accounts for other users: + +#. After logging in, click the "Users" link at the footer of + the query page, and then click "Add a new user". + +#. Fill out the form presented. This page is self-explanatory. + When done, click "Submit". + + .. note:: Adding a user this way will *not* + 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 ``New Account`` + button to create users, as it will pre-populate all the + required fields and also notify the user of her account name + and password. + +.. _modifyusers: + +Modifying Users +--------------- + +Once you have found your user, you can change the following +fields: + +- *Login Name*: + This is generally the user's full email address. However, if you + have are using the ``emailsuffix`` parameter, this may + just be the user's login name. Note that users can now change their + login names themselves (to any valid email address). + +- *Real Name*: The user's real name. Note that + Bugzilla does not require this to create an account. + +- *Password*: + 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. + +- *Bugmail Disabled*: + Mark this checkbox to disable bugmail and whinemail completely + for this account. This checkbox replaces the data/nomail file + which existed in older versions of Bugzilla. + +- *Disable Text*: + 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. + Users with disabled accounts will continue to receive + mail from Bugzilla; furthermore, they will not be able + to log in themselves to change their own preferences and + stop it. If you want an account (disabled or active) to + stop receiving mail, simply check the + ``Bugmail Disabled`` checkbox above. + + .. note:: Even users whose accounts have been disabled can still + submit bugs via the e-mail gateway, if one exists. + The e-mail gateway should *not* be + enabled for secure installations of Bugzilla. + + .. warning:: Don't disable all the administrator accounts! + +- **: + 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. The first checkbox gives the + user the ability to add and remove other users as members of + this group. The second checkbox adds the user himself as a member + of the group. + +- *canconfirm*: + 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). + +- *creategroups*: + This option will allow a user to create and destroy groups in + Bugzilla. + +- *editbugs*: + 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. + +- *editcomponents*: + 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. + +- *editkeywords*: + 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. + +- *editusers*: + 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. + +- *tweakparams*: + This flag allows a user to change Bugzilla's Params + (using :file:`editparams.cgi`.) + +- **: + This allows an administrator to specify the products + in which a user can see bugs. If you turn on the + ``makeproductgroups`` parameter in + the Group Security Panel in the Parameters page, + then Bugzilla creates one group per product (at the time you create + the product), and this group has exactly the same name as the + product itself. Note that for products that already exist when + the parameter is turned on, the corresponding group will not be + created. The user must still have the ``editbugs`` + privilege to edit bugs in these products. + +.. _user-account-deletion: + +Deleting Users +-------------- + +If the ``allowuserdeletion`` parameter is turned on, see +:ref:`parameters`, then you can also delete user accounts. +Note that this is most of the time not the best thing to do. If only +a warning in a yellow box is displayed, then the deletion is safe. +If a warning is also displayed in a red box, then you should NOT try +to delete the user account, else you will get referential integrity +problems in your database, which can lead to unexpected behavior, +such as bugs not appearing in bug lists anymore, or data displaying +incorrectly. You have been warned! + +.. _impersonatingusers: + +Impersonating Users +------------------- + +There may be times when an administrator would like to do something as +another user. The :command:`sudo` feature may be used to do +this. + +.. note:: To use the sudo feature, you must be in the + *bz_sudoers* group. By default, all + administrators are in this group. + +If you have access to this feature, you may start a session by +going to the Edit Users page, Searching for a user and clicking on +their login. You should see a link below their login name titled +"Impersonate this user". Click on the link. This will take you +to a page where you will see a description of the feature and +instructions for using it. After reading the text, simply +enter the login of the user you would like to impersonate, provide +a short message explaining why you are doing this, and press the +button. + +As long as you are using this feature, everything you do will be done +as if you were logged in as the user you are impersonating. + +.. warning:: The user you are impersonating will not be told about what you are + doing. If you do anything that results in mail being sent, that + mail will appear to be from the user you are impersonating. You + should be extremely careful while using this feature. + +.. _classifications: + +Classifications +############### + +Classifications tend to be used in order to group several related +products into one distinct entity. + +The classifications layer is disabled by default; it can be turned +on or off using the useclassification parameter, +in the *Bug Fields* section of the edit parameters screen. + +Access to the administration of classifications is controlled using +the *editclassifications* system group, which defines +a privilege for creating, destroying, and editing classifications. + +When activated, classifications will introduce an additional +step when filling bugs (dedicated to classification selection), and they +will also appear in the advanced search form. + +.. _products: + +Products +######## + +Products typically represent real-world +shipping products. Products can be given +:ref:`classifications`. +For example, if a company makes computer games, +they could have a classification of "Games", and a separate +product for each game. This company might also have a +``Common`` product for units of technology used +in multiple games, and perhaps a few special products that +represent items that are not actually shipping products +(for example, "Website", or "Administration"). + +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 CONFIRMED status. + +When creating or editing products the following options are +available: + +Product + The name of the product + +Description + A brief description of the product + +Default milestone + Select the default milestone for this product. + +Closed for bug entry + Select this box to prevent new bugs from being + entered against this product. + +Maximum votes per person + Maximum votes a user is allowed to give for this + product + +Maximum votes a person can put on a single bug + Maximum votes a user is allowed to give for this + product in a single bug + +Confirmation threshold + Number of votes needed to automatically remove any + bug against this product from the UNCONFIRMED state + +Version + Specify which version of the product bugs will be + entered against. + +Create chart datasets for this product + Select to make chart datasets available for this product. + +When editing a product there is also a link to edit Group Access Controls, +see :ref:`product-group-controls`. + +.. _create-product: + +Creating New Products +===================== + +To create a new product: + +#. Select ``Administration`` from the footer and then + choose ``Products`` from the main administration page. + +#. Select the ``Add`` link in the bottom right. + +#. Enter the name of the product and a description. The + Description field may contain HTML. + +#. When the product is created, Bugzilla will give a message + stating that a component must be created before any bugs can + be entered against the new product. Follow the link to create + a new component. See :ref:`components` for more + information. + +.. _edit-products: + +Editing Products +================ + +To edit an existing product, click the "Products" link from the +"Administration" page. If the 'useclassification' parameter is +turned on, a table of existing classifications is displayed, +including an "Unclassified" category. The table indicates how many products +are in each classification. Click on the classification name to see its +products. If the 'useclassification' parameter is not in use, the table +lists all products directly. The product table summarizes the information +about the product defined +when the product was created. Click on the product name to edit these +properties, and to access links to other product attributes such as the +product's components, versions, milestones, and group access controls. + +.. _comps-vers-miles-products: + +Adding or Editing Components, Versions and Target Milestones +============================================================ + +To edit existing, or add new, Components, Versions or Target Milestones +to a Product, select the "Edit Components", "Edit Versions" or "Edit +Milestones" links from the "Edit Product" page. A table of existing +Components, Versions or Milestones is displayed. Click on a item name +to edit the properties of that item. Below the table is a link to add +a new Component, Version or Milestone. + +For more information on components, see :ref:`components`. + +For more information on versions, see :ref:`versions`. + +For more information on milestones, see :ref:`milestones`. + +.. _product-group-controls: + +Assigning Group Controls to Products +==================================== + +On the ``Edit Product`` page, there is a link called +``Edit Group Access Controls``. The settings on this page +control the relationship of the groups to the product being edited. + +Group Access Controls are an important aspect of using groups for +isolating products and restricting access to bugs filed against those +products. For more information on groups, including how to create, edit +add users to, and alter permission of, see :ref:`groups`. + +After selecting the "Edit Group Access Controls" link from the "Edit +Product" page, a table containing all user-defined groups for this +Bugzilla installation is displayed. The system groups that are created +when Bugzilla is installed are not applicable to Group Access Controls. +Below is description of what each of these fields means. + +Groups may be applicable (e.g bugs in this product can be associated +with this group) , default (e.g. bugs in this product are in this group +by default), and mandatory (e.g. bugs in this product must be associated +with this group) for each product. Groups can also control access +to bugs for a given product, or be used to make bugs for a product +totally read-only unless the group restrictions are met. The best way to +understand these relationships is by example. See +:ref:`group-control-examples` for examples of +product and group relationships. + +.. note:: Products and Groups are not limited to a one-to-one relationship. + Multiple groups can be associated with the same product, and groups + can be associated with more than one product. + +If any group has *Entry* selected, then the +product will restrict bug entry to only those users +who are members of *all* the groups with +*Entry* selected. + +If any group has *Canedit* selected, +then the product will be read-only for any users +who are not members of *all* of the groups with +*Canedit* selected. *Only* users who +are members of all the *Canedit* groups +will be able to edit bugs for this product. This is an additional +restriction that enables finer-grained control over products rather +than just all-or-nothing access levels. + +The following settings let you +choose privileges on a *per-product basis*. +This is a convenient way to give privileges to +some users for some products only, without having +to give them global privileges which would affect +all products. + +Any group having *editcomponents* +selected allows users who are in this group to edit all +aspects of this product, including components, milestones +and versions. + +Any group having *canconfirm* selected +allows users who are in this group to confirm bugs +in this product. + +Any group having *editbugs* selected allows +users who are in this group to edit all fields of +bugs in this product. + +The *MemberControl* and +*OtherControl* are used in tandem to determine which +bugs will be placed in this group. The only allowable combinations of +these two parameters are listed in a table on the "Edit Group Access Controls" +page. Consult this table for details on how these fields can be used. +Examples of different uses are described below. + +.. _group-control-examples: + +Common Applications of Group Controls +===================================== + +The use of groups is best explained by providing examples that illustrate +configurations for common use cases. The examples follow a common syntax: +*Group: Entry, MemberControl, OtherControl, CanEdit, +EditComponents, CanConfirm, EditBugs*. Where "Group" is the name +of the group being edited for this product. The other fields all +correspond to the table on the "Edit Group Access Controls" page. If any +of these options are not listed, it means they are not checked. + +Basic Product/Group Restriction +------------------------------- + +Suppose there is a product called "Bar". The +"Bar" product can only have bugs entered against it by users in the +group "Foo". Additionally, bugs filed against product "Bar" must stay +restricted to users to "Foo" at all times. Furthermore, only members +of group "Foo" can edit bugs filed against product "Bar", even if other +users could see the bug. This arrangement would achieved by the +following: + +:: + + Product Bar: + foo: ENTRY, MANDATORY/MANDATORY, CANEDIT + +Perhaps such strict restrictions are not needed for product "Bar". A +more lenient way to configure product "Bar" and group "Foo" would be: + +:: + + Product Bar: + foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS + +The above indicates that for product "Bar", members of group "Foo" can +enter bugs. Any one with permission to edit a bug against product "Bar" +can put the bug +in group "Foo", even if they themselves are not in "Foo". Anyone in group +"Foo" can edit all aspects of the components of product "Bar", can confirm +bugs against product "Bar", and can edit all fields of any bug against +product "Bar". + +General User Access With Security Group +--------------------------------------- + +To permit any user to file bugs against "Product A", +and to permit any user to submit those bugs into a +group called "Security": + +:: + + Product A: + security: SHOWN/SHOWN + +General User Access With A Security Product +------------------------------------------- + +To permit any user to file bugs against product called "Security" +while keeping those bugs from becoming visible to anyone +outside the group "SecurityWorkers" (unless a member of the +"SecurityWorkers" group removes that restriction): + +:: + + Product Security: + securityworkers: DEFAULT/MANDATORY + +Product Isolation With a Common Group +------------------------------------- + +To permit users of "Product A" to access the bugs for +"Product A", users of "Product B" to access the bugs for +"Product B", and support staff, who are members of the "Support +Group" to access both, three groups are needed: + +#. Support Group: Contains members of the support staff. + +#. AccessA Group: Contains users of product A and the Support group. + +#. AccessB Group: Contains users of product B and the Support group. + +Once these three groups are defined, the product group controls +can be set to: + +:: + + Product A: + AccessA: ENTRY, MANDATORY/MANDATORY + Product B: + AccessB: ENTRY, MANDATORY/MANDATORY + +Perhaps the "Support Group" wants more control. For example, +the "Support Group" could be permitted to make bugs inaccessible to +users of both groups "AccessA" and "AccessB". +Then, the "Support Group" could be permitted to publish +bugs relevant to all users in a third product (let's call it +"Product Common") that is read-only +to anyone outside the "Support Group". In this way the "Support Group" +could control bugs that should be seen by both groups. +That configuration would be: + +:: + + Product A: + AccessA: ENTRY, MANDATORY/MANDATORY + Support: SHOWN/NA + Product B: + AccessB: ENTRY, MANDATORY/MANDATORY + Support: SHOWN/NA + Product Common: + Support: ENTRY, DEFAULT/MANDATORY, CANEDIT + +Make a Product Read Only +------------------------ + +Sometimes a product is retired and should no longer have +new bugs filed against it (for example, an older version of a software +product that is no longer supported). A product can be made read-only +by creating a group called "readonly" and adding products to the +group as needed: + +:: + + Product A: + ReadOnly: ENTRY, NA/NA, CANEDIT + +.. note:: For more information on Groups outside of how they relate to products + see :ref:`groups`. + +.. _components: + +Components +########## + +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. + +Each component has a default assignee and (if you turned it on in the parameters), +a QA Contact. The default assignee should be the primary person who fixes bugs in +that component. The QA Contact should be the person who will ensure +these bugs are completely fixed. The Assignee, QA Contact, and Reporter +will get email when new bugs are created in this Component and when +these bugs change. Default Assignee and Default QA Contact fields only +dictate the +*default assignments*; +these can be changed on bug submission, or at any later point in +a bug's life. + +To create a new Component: + +#. Select the ``Edit components`` link + from the ``Edit product`` page + +#. Select the ``Add`` link in the bottom right. + +#. Fill out the ``Component`` field, a + short ``Description``, the + ``Default Assignee``, ``Default CC List`` + and ``Default QA Contact`` (if enabled). + The ``Component Description`` field may contain a + limited subset of HTML tags. The ``Default Assignee`` + field must be a login name already existing in the Bugzilla database. + +.. _versions: + +Versions +######## + +Versions are the revisions of the product, such as "Flinders +3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select +field; the usual practice is to select the earliest version known to have +the bug. + +To create and edit Versions: + +#. From the "Edit product" screen, select "Edit Versions" + +#. You will notice that the product already has the default + version "undefined". Click the "Add" link in the bottom right. + +#. Enter the name of the Version. This field takes text only. + Then click the "Add" button. + +.. _milestones: + +Milestones +########## + +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. + +.. note:: Milestone options will only appear for a Product if you turned + on the "usetargetmilestone" parameter in the "Bug Fields" tab of the + "Parameters" page. + +To create new Milestones, and set Default Milestones: + +#. Select "Edit milestones" from the "Edit product" page. + +#. Select "Add" in the bottom right corner. + +#. Enter the name of the Milestone in the "Milestone" field. You + can optionally set the "sortkey", which is a positive or negative + number (-32768 to 32767) that defines where in the list this particular + milestone appears. This is because milestones often do not + occur in alphanumeric order For example, "Future" might be + after "Release 1.2". Select "Add". + +.. _flags-overview: + +Flags +##### + +Flags are a way to attach a specific status to a bug or attachment, +either ``+`` or ``-``. The meaning of these symbols depends on the text +the flag itself, but contextually they could mean pass/fail, +accept/reject, approved/denied, or even a simple yes/no. If your site +allows requestable flags, then users may set a flag to ``?`` as a +request to another user that they look at the bug/attachment, and set +the flag to its correct status. + +.. _flags-simpleexample: + +A Simple Example +================ + +A developer might want to ask their manager, +``Should we fix this bug before we release version 2.0?`` +They might want to do this for a *lot* of bugs, +so it would be nice to streamline the process... + +In Bugzilla, it would work this way: + +#. The Bugzilla administrator creates a flag type called + ``blocking2.0`` that shows up on all bugs in + your product. + It shows up on the ``Show Bug`` screen + as the text ``blocking2.0`` with a drop-down box next + to it. The drop-down box contains four values: an empty space, + ``?``, ``-``, and ``+``. + +#. The developer sets the flag to ``?``. + +#. The manager sees the ``blocking2.0`` + flag with a ``?`` value. + +#. If the manager thinks the feature should go into the product + before version 2.0 can be released, he sets the flag to + ``+``. Otherwise, he sets it to ``-``. + +#. Now, every Bugzilla user who looks at the bug knows whether or + not the bug needs to be fixed before release of version 2.0. + +.. _flags-about: + +About Flags +=========== + +.. _flag-values: + +Values +------ + +Flags can have three values: + +``?`` + A user is requesting that a status be set. (Think of it as 'A question is being asked'.) + +``-`` + The status has been set negatively. (The question has been answered ``no``.) + +``+`` + The status has been set positively. + (The question has been answered ``yes``.) + +Actually, there's a fourth value a flag can have -- +``unset`` -- which shows up as a blank space. This +just means that nobody has expressed an opinion (or asked +someone else to express an opinion) about this bug or attachment. + +.. _flag-askto: + +Using flag requests +=================== + +If a flag has been defined as 'requestable', and a user has enough privileges +to request it (see below), the user can set the flag's status to ``?``. +This status indicates that someone (a.k.a. ``the requester``) is asking +someone else to set the flag to either ``+`` or ``-``. + +If a flag has been defined as 'specifically requestable', +a text box will appear next to the flag into which the requester may +enter a Bugzilla username. That named person (a.k.a. ``the requestee``) +will receive an email notifying them of the request, and pointing them +to the bug/attachment in question. + +If a flag has *not* been defined as 'specifically requestable', +then no such text-box will appear. A request to set this flag cannot be made of +any specific individual, but must be asked ``to the wind``. +A requester may ``ask the wind`` on any flag simply by leaving the text-box blank. + +.. _flag-types: + +Two Types of Flags +================== + +Flags can go in two places: on an attachment, or on a bug. + +.. _flag-type-attachment: + +Attachment Flags +---------------- + +Attachment flags are used to ask a question about a specific +attachment on a bug. + +Many Bugzilla installations use this to +request that one developer ``review`` another +developer's code before they check it in. They attach the code to +a bug report, and then set a flag on that attachment called +``review`` to +``review?boss@domain.com``. +boss@domain.com is then notified by email that +he has to check out that attachment and approve it or deny it. + +For a Bugzilla user, attachment flags show up in three places: + +#. On the list of attachments in the ``Show Bug`` + screen, you can see the current state of any flags that + have been set to ?, +, or -. You can see who asked about + the flag (the requester), and who is being asked (the + requestee). + +#. When you ``Edit`` an attachment, you can + see any settable flag, along with any flags that have + already been set. This ``Edit Attachment`` + screen is where you set flags to ?, -, +, or unset them. + +#. Requests are listed in the ``Request Queue``, which + is accessible from the ``My Requests`` link (if you are + logged in) or ``Requests`` link (if you are logged out) + visible in the footer of all pages. + +.. _flag-type-bug: + +Bug Flags +--------- + +Bug flags are used to set a status on the bug itself. You can +see Bug Flags in the ``Show Bug`` and ``Requests`` +screens, as described above. + +Only users with enough privileges (see below) may set flags on bugs. +This doesn't necessarily include the assignee, reporter, or users with the +``editbugs`` permission. + +.. _flags-admin: + +Administering Flags +=================== + +If you have the ``editcomponents`` permission, you can +edit Flag Types from the main administration page. Clicking the +``Flags`` link will bring you to the ``Administer +Flag Types`` page. Here, you can select whether you want +to create (or edit) a Bug flag, or an Attachment flag. + +No matter which you choose, the interface is the same, so we'll +just go over it once. + +.. _flags-edit: + +Editing a Flag +-------------- + +To edit a flag's properties, just click the flag's name. +That will take you to the same +form as described below (:ref:`flags-create`). + +.. _flags-create: + +Creating a Flag +--------------- + +When you click on the ``Create a Flag Type for...`` +link, you will be presented with a form. Here is what the fields in +the form mean: + +.. _flags-create-field-name: + +Name +~~~~ + +This is the name of the flag. This will be displayed +to Bugzilla users who are looking at or setting the flag. +The name may contain any valid Unicode characters except commas +and spaces. + +.. _flags-create-field-description: + +Description +~~~~~~~~~~~ + +The description describes the flag in more detail. It is visible +in a tooltip when hovering over a flag either in the ``Show Bug`` +or ``Edit Attachment`` pages. This field can be as +long as you like, and can contain any character you want. + +.. _flags-create-field-category: + +Category +~~~~~~~~ + +Default behaviour for a newly-created flag is to appear on +products and all components, which is why ``__Any__:__Any__`` +is already entered in the ``Inclusions`` box. +If this is not your desired behaviour, you must either set some +exclusions (for products on which you don't want the flag to appear), +or you must remove ``__Any__:__Any__`` from the Inclusions box +and define products/components specifically for this flag. + +To create an Inclusion, select a Product from the top drop-down box. +You may also select a specific component from the bottom drop-down box. +(Setting ``__Any__`` for Product translates to, +``all the products in this Bugzilla``. +Selecting ``__Any__`` in the Component field means +``all components in the selected product.``) +Selections made, press ``Include``, and your +Product/Component pairing will show up in the ``Inclusions`` box on the right. + +To create an Exclusion, the process is the same; select a Product from the +top drop-down box, select a specific component if you want one, and press +``Exclude``. The Product/Component pairing will show up in the +``Exclusions`` box on the right. + +This flag *will* and *can* be set for any +products/components that appearing in the ``Inclusions`` box +(or which fall under the appropriate ``__Any__``). +This flag *will not* appear (and therefore cannot be set) on +any products appearing in the ``Exclusions`` box. +*IMPORTANT: Exclusions override inclusions.* + +You may select a Product without selecting a specific Component, +but you can't select a Component without a Product, or to select a +Component that does not belong to the named Product. If you do so, +Bugzilla will display an error message, even if all your products +have a component by that name. + +*Example:* Let's say you have a product called +``Jet Plane`` that has thousands of components. You want +to be able to ask if a problem should be fixed in the next model of +plane you release. We'll call the flag ``fixInNext``. +But, there's one component in ``Jet Plane,`` +called ``Pilot.`` It doesn't make sense to release a +new pilot, so you don't want to have the flag show up in that component. +So, you include ``Jet Plane:__Any__`` and you exclude +``Jet Plane:Pilot``. + +.. _flags-create-field-sortkey: + +Sort Key +~~~~~~~~ + +Flags normally show up in alphabetical order. If you want them to +show up in a different order, you can use this key set the order on each flag. +Flags with a lower sort key will appear before flags with a higher +sort key. Flags that have the same sort key will be sorted alphabetically, +but they will still be after flags with a lower sort key, and before flags +with a higher sort key. + +*Example:* I have AFlag (Sort Key 100), BFlag (Sort Key 10), +CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in +the order: DFlag, BFlag, CFlag, AFlag. + +.. _flags-create-field-active: + +Active +~~~~~~ + +Sometimes, you might want to keep old flag information in the +Bugzilla database, but stop users from setting any new flags of this type. +To do this, uncheck ``active``. Deactivated +flags will still show up in the UI if they are ?, +, or -, but they +may only be cleared (unset), and cannot be changed to a new value. +Once a deactivated flag is cleared, it will completely disappear from a +bug/attachment, and cannot be set again. + +.. _flags-create-field-requestable: + +Requestable +~~~~~~~~~~~ + +New flags are, by default, ``requestable``, meaning that they +offer users the ``?`` option, as well as ``+`` +and ``-``. +To remove the ? option, uncheck ``requestable``. + +.. _flags-create-field-specific: + +Specifically Requestable +~~~~~~~~~~~~~~~~~~~~~~~~ + +By default this box is checked for new flags, meaning that users may make +flag requests of specific individuals. Unchecking this box will remove the +text box next to a flag; if it is still requestable, then requests may +only be made ``to the wind.`` Removing this after specific +requests have been made will not remove those requests; that data will +stay in the database (though it will no longer appear to the user). + +.. _flags-create-field-multiplicable: + +Multiplicable +~~~~~~~~~~~~~ + +Any flag with ``Multiplicable`` set (default for new flags is 'on') +may be set more than once. After being set once, an unset flag +of the same type will appear below it with ``addl.`` (short for +``additional``) before the name. There is no limit to the number of +times a Multiplicable flags may be set on the same bug/attachment. + +.. _flags-create-field-cclist: + +CC List +~~~~~~~ + +If you want certain users to be notified every time this flag is +set to ?, -, +, or unset, add them here. This is a comma-separated +list of email addresses that need not be restricted to Bugzilla usernames. + +.. _flags-create-grant-group: + +Grant Group +~~~~~~~~~~~ + +When this field is set to some given group, only users in the group +can set the flag to ``+`` and ``-``. This +field does not affect who can request or cancel the flag. For that, +see the ``Request Group`` field below. If this field +is left blank, all users can set or delete this flag. This field is +useful for restricting which users can approve or reject requests. + +.. _flags-create-request-group: + +Request Group +~~~~~~~~~~~~~ + +When this field is set to some given group, only users in the group +can request or cancel this flag. Note that this field has no effect +if the ``grant group`` field is empty. You can set the +value of this field to a different group, but both fields have to be +set to a group for this field to have an effect. + +.. COMMENT: flags-create + +.. _flags-delete: + +Deleting a Flag +--------------- + +When you are at the ``Administer Flag Types`` screen, +you will be presented with a list of Bug flags and a list of Attachment +Flags. + +To delete a flag, click on the ``Delete`` link next to +the flag description. + +.. warning:: Once you delete a flag, it is *gone* from + your Bugzilla. All the data for that flag will be deleted. + Everywhere that flag was set, it will disappear, + and you cannot get that data back. If you want to keep flag data, + but don't want anybody to set any new flags or change current flags, + unset ``active`` in the flag Edit form. + +.. COMMENT: flags-admin + +.. COMMENT: XXX We should add a "Uses of Flags" section, here, with examples. + +.. COMMENT: flags + +.. _keywords: + +Keywords +######## + +The administrator can define keywords which can be used to tag and +categorise bugs. For example, the keyword "regression" is commonly used. +A company might have a policy stating all regressions +must be fixed by the next release - this keyword can make tracking those +bugs much easier. + +Keywords are global, rather than per-product. If the administrator changes +a keyword currently applied to any bugs, the keyword cache must be rebuilt +using the :ref:`sanitycheck` script. Currently keywords cannot +be marked obsolete to prevent future usage. + +Keywords can be created, edited or deleted by clicking the "Keywords" +link in the admin page. There are two fields for each keyword - the keyword +itself and a brief description. Once created, keywords can be selected +and applied to individual bugs in that bug's "Details" section. + +.. _custom-fields: + +Custom Fields +############# + +The release of Bugzilla 3.0 added the ability to create Custom Fields. +Custom Fields are treated like any other field - they can be set in bugs +and used for search queries. Administrators should keep in mind that +adding too many fields can make the user interface more complicated and +harder to use. Custom Fields should be added only when necessary and with +careful consideration. + +.. tip:: Before adding a Custom Field, make sure that Bugzilla cannot already + do the desired behavior. Many Bugzilla options are not enabled by + default, and many times Administrators find that simply enabling + certain options that already exist is sufficient. + +Administrators can manage Custom Fields using the +``Custom Fields`` link on the Administration page. The Custom +Fields administration page displays a list of Custom Fields, if any exist, +and a link to "Add a new custom field". + +.. _add-custom-fields: + +Adding Custom Fields +==================== + +To add a new Custom Field, click the "Add a new custom field" link. This +page displays several options for the new field, described below. + +The following attributes must be set for each new custom field: + +- *Name:* + The name of the field in the database, used internally. This name + MUST begin with ``cf_`` to prevent confusion with + standard fields. If this string is omitted, it will + be automatically added to the name entered. + +- *Description:* + A brief string which is used as the label for this Custom Field. + That is the string that users will see, and should be + short and explicit. + +- *Type:* + The type of field to create. There are + several types available: + + Bug ID: + A field where you can enter the ID of another bug from + the same Bugzilla installation. To point to a bug in a remote + installation, use the See Also field instead. + Large Text Box: + A multiple line box for entering free text. + Free Text: + A single line box for entering free text. + Multiple-Selection Box: + A list box where multiple options + can be selected. After creating this field, it must be edited + to add the selection options. See + :ref:`edit-values-list` for information about + editing legal values. + Drop Down: + A list box where only one option can be selected. + After creating this field, it must be edited to add the + selection options. See + :ref:`edit-values-list` for information about + editing legal values. + Date/Time: + A date field. This field appears with a + calendar widget for choosing the date. + +- *Sortkey:* + Integer that determines in which order Custom Fields are + displayed in the User Interface, especially when viewing a bug. + Fields with lower values are displayed first. + +- *Reverse Relationship Description:* + When the custom field is of type ``Bug ID``, you can + enter text here which will be used as label in the referenced + bug to list bugs which point to it. This gives you the ability + to have a mutual relationship between two bugs. + +- *Can be set on bug creation:* + Boolean that determines whether this field can be set on + bug creation. If not selected, then a bug must be created + before this field can be set. See :ref:`bugreports` + for information about filing bugs. + +- *Displayed in bugmail for new bugs:* + Boolean that determines whether the value set on this field + should appear in bugmail when the bug is filed. This attribute + has no effect if the field cannot be set on bug creation. + +- *Is obsolete:* + Boolean that determines whether this field should + be displayed at all. Obsolete Custom Fields are hidden. + +- *Is mandatory:* + Boolean that determines whether this field must be set. + For single and multi-select fields, this means that a (non-default) + value must be selected, and for text and date fields, some text + must be entered. + +- *Field only appears when:* + A custom field can be made visible when some criteria is met. + For instance, when the bug belongs to one or more products, + or when the bug is of some given severity. If left empty, then + the custom field will always be visible, in all bugs. + +- *Field that controls the values that appear in this field:* + When the custom field is of type ``Drop Down`` or + ``Multiple-Selection Box``, you can restrict the + availability of the values of the custom field based on the + value of another field. This criteria is independent of the + criteria used in the ``Field only appears when`` + setting. For instance, you may decide that some given value + ``valueY`` is only available when the bug status + is RESOLVED while the value ``valueX`` should + always be listed. + Once you have selected the field which should control the + availability of the values of this custom field, you can + edit values of this custom field to set the criteria, see + :ref:`edit-values-list`. + +.. _edit-custom-fields: + +Editing Custom Fields +===================== + +As soon as a Custom Field is created, its name and type cannot be +changed. If this field is a drop down menu, its legal values can +be set as described in :ref:`edit-values-list`. All +other attributes can be edited as described above. + +.. _delete-custom-fields: + +Deleting Custom Fields +====================== + +Only custom fields which are marked as obsolete, and which never +have been used, can be deleted completely (else the integrity +of the bug history would be compromised). For custom fields marked +as obsolete, a "Delete" link will appear in the ``Action`` +column. If the custom field has been used in the past, the deletion +will be rejected. But marking the field as obsolete is sufficient +to hide it from the user interface entirely. + +.. _edit-values: + +Legal Values +############ + +Legal values for the operating system, platform, bug priority and +severity, custom fields of type ``Drop Down`` and +``Multiple-Selection Box`` (see :ref:`custom-fields`), +as well as the list of valid bug statuses and resolutions can be +customized from the same interface. You can add, edit, disable and +remove values which can be used with these fields. + +.. _edit-values-list: + +Viewing/Editing legal values +============================ + +Editing legal values requires ``admin`` privileges. +Select "Field Values" from the Administration page. A list of all +fields, both system fields and Custom Fields, for which legal values +can be edited appears. Click a field name to edit its legal values. + +There is no limit to how many values a field can have, but each value +must be unique to that field. The sortkey is important to display these +values in the desired order. + +When the availability of the values of a custom field is controlled +by another field, you can select from here which value of the other field +must be set for the value of the custom field to appear. + +.. _edit-values-delete: + +Deleting legal values +===================== + +Legal values from Custom Fields can be deleted, but only if the +following two conditions are respected: + +#. The value is not used by default for the field. + +#. No bug is currently using this value. + +If any of these conditions is not respected, the value cannot be deleted. +The only way to delete these values is to reassign bugs to another value +and to set another value as default for the field. + +.. _bug_status_workflow: + +Bug Status Workflow +################### + +The bug status workflow is no longer hardcoded but can be freely customized +from the web interface. Only one bug status cannot be renamed nor deleted, +UNCONFIRMED, but the workflow involving it is free. The configuration +page displays all existing bug statuses twice, first on the left for bug +statuses we come from and on the top for bug statuses we move to. +If the checkbox is checked, then the transition between the two bug statuses +is legal, else it's forbidden independently of your privileges. The bug status +used for the "duplicate_or_move_bug_status" parameter must be part of the +workflow as that is the bug status which will be used when duplicating or +moving a bug, so it must be available from each bug status. + +When the workflow is set, the "View Current Triggers" link below the table +lets you set which transitions require a comment from the user. + +.. _voting: + +Voting +###### + +All of the code for voting in Bugzilla has been moved into an +extension, called "Voting", in the :file:`extensions/Voting/` +directory. To enable it, you must remove the :file:`disabled` +file from that directory, and run :file:`checksetup.pl`. + +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 +"CONFIRMED", users of the bug system can help high-priority bugs garner +attention so they don't sit for a long time awaiting triage. + +To modify Voting settings: + +#. Navigate to the "Edit product" screen for the Product you + wish to modify + +#. *Maximum Votes per person*: + Setting this field to "0" disables voting. + +#. *Maximum Votes a person can put on a single + bug*: + 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. + +#. *Number of votes a bug in this product needs to + automatically get out of the UNCONFIRMED state*: + Setting this field to "0" disables the automatic move of + bugs from UNCONFIRMED to CONFIRMED. + +#. Once you have adjusted the values to your preference, click + "Update". + +.. _quips: + +Quips +##### + +Quips are small text messages that can be configured to appear +next to search results. A Bugzilla installation can have its own specific +quips. Whenever a quip needs to be displayed, a random selection +is made from the pool of already existing quips. + +Quip submission is controlled by the *quip_list_entry_control* +parameter. It has several possible values: open, moderated, or closed. +In order to enable quips approval you need to set this parameter to +"moderated". In this way, users are free to submit quips for addition +but an administrator must explicitly approve them before they are +actually used. + +In order to see the user interface for the quips, it is enough to click +on a quip when it is displayed together with the search results. Or +it can be seen directly in the browser by visiting the quips.cgi URL +(prefixed with the usual web location of the Bugzilla installation). +Once the quip interface is displayed, it is enough to click the +"view and edit the whole quip list" in order to see the administration +page. A page with all the quips available in the database will +be displayed. + +Next to each quip there is a checkbox, under the +"Approved" column. Quips who have this checkbox checked are +already approved and will appear next to the search results. +The ones that have it unchecked are still preserved in the +database but they will not appear on search results pages. +User submitted quips have initially the checkbox unchecked. + +Also, there is a delete link next to each quip, +which can be used in order to permanently delete a quip. + +Display of quips is controlled by the *display_quips* +user preference. Possible values are "on" and "off". + +.. _groups: + +Groups and Group Security +######################### + +Groups allow for separating bugs into logical divisions. +Groups are typically used +to isolate bugs that should only be seen by certain people. For +example, a company might create a different group for each one of its customers +or partners. Group permissions could be set so that each partner or customer would +only have access to their own bugs. Or, groups might be used to create +variable access controls for different departments within an organization. +Another common use of groups is to associate groups with products, +creating isolation and access control on a per-product basis. + +Groups and group behaviors are controlled in several places: + +#. The group configuration page. To view or edit existing groups, or to + create new groups, access the "Groups" link from the "Administration" + page. This section of the manual deals primarily with the aspect of + group controls accessed on this page. + +#. Global configuration parameters. Bugzilla has several parameters + that control the overall default group behavior and restriction + levels. For more information on the parameters that control + group behavior globally, see :ref:`param-group-security`. + +#. Product association with groups. Most of the functionality of groups + and group security is controlled at the product level. Some aspects + of group access controls for products are discussed in this section, + but for more detail see :ref:`product-group-controls`. + +#. Group access for users. See :ref:`users-and-groups` for + details on how users are assigned group access. + +Group permissions are such that if a bug belongs to a group, only members +of that group can see the bug. If a bug is in more than one group, only +members of *all* the groups that the bug is in can see +the bug. For information on granting read-only access to certain people and +full edit access to others, see :ref:`product-group-controls`. + +.. note:: By default, bugs can also be seen by the Assignee, the Reporter, and + by everyone on the CC List, regardless of whether or not the bug would + typically be viewable by them. Visibility to the Reporter and CC List can + be overridden (on a per-bug basis) by bringing up the bug, finding the + section that starts with ``Users in the roles selected below...`` + and un-checking the box next to either 'Reporter' or 'CC List' (or both). + +.. _create-groups: + +Creating Groups +=============== + +To create a new group, follow the steps below: + +#. Select the ``Administration`` link in the page footer, + and then select the ``Groups`` link from the + Administration page. + +#. A table of all the existing groups is displayed. Below the table is a + description of all the fields. To create a new group, select the + ``Add Group`` link under the table of existing groups. + +#. There are five fields to fill out. These fields are documented below + the form. Choose a name and description for the group. Decide whether + this group should be used for bugs (in all likelihood this should be + selected). Optionally, choose a regular expression that will + automatically add any matching users to the group, and choose an + icon that will help identify user comments for the group. The regular + expression can be useful, for example, to automatically put all users + from the same company into one group (if the group is for a specific + customer or partner). + + .. note:: If ``User RegExp`` is filled out, users whose email + addresses match the regular expression will automatically be + members of the group as long as their email addresses continue + to match the regular expression. If their email address changes + and no longer matches the regular expression, they will be removed + from the group. Versions 2.16 and older of Bugzilla did not automatically + remove users who's email addresses no longer matched the RegExp. + + .. warning:: If specifying a domain in the regular expression, end + the regexp with a "$". Otherwise, when granting access to + "@mycompany\\.com", access will also be granted to + 'badperson@mycompany.com.cracker.net'. Use the syntax, + '@mycompany\\.com$' for the regular expression. + +#. After the new group is created, it can be edited for additional options. + The "Edit Group" page allows for specifying other groups that should be included + in this group and which groups should be permitted to add and delete + users from this group. For more details, see :ref:`edit-groups`. + +.. _edit-groups: + +Editing Groups and Assigning Group Permissions +============================================== + +To access the "Edit Groups" page, select the +``Administration`` link in the page footer, +and then select the ``Groups`` link from the Administration page. +A table of all the existing groups is displayed. Click on a group name +you wish to edit or control permissions for. + +The "Edit Groups" page contains the same five fields present when +creating a new group. Below that are two additional sections, "Group +Permissions," and "Mass Remove". The "Mass Remove" option simply removes +all users from the group who match the regular expression entered. The +"Group Permissions" section requires further explanation. + +The "Group Permissions" section on the "Edit Groups" page contains four sets +of permissions that control the relationship of this group to other +groups. If the 'usevisibilitygroups' parameter is in use (see +:ref:`parameters`) two additional sets of permissions are displayed. +Each set consists of two select boxes. On the left, a select box +with a list of all existing groups. On the right, a select box listing +all groups currently selected for this permission setting (this box will +be empty for new groups). The way these controls allow groups to relate +to one another is called *inheritance*. +Each of the six permissions is described below. + +*Groups That Are a Member of This Group* + Members of any groups selected here will automatically have + membership in this group. In other words, members of any selected + group will inherit membership in this group. + +*Groups That This Group Is a Member Of* + Members of this group will inherit membership to any group + selected here. For example, suppose the group being edited is + an Admin group. If there are two products (Product1 and Product2) + and each product has its + own group (Group1 and Group2), and the Admin group + should have access to both products, + simply select both Group1 and Group2 here. + +*Groups That Can Grant Membership in This Group* + The members of any group selected here will be able add users + to this group, even if they themselves are not in this group. + +*Groups That This Group Can Grant Membership In* + Members of this group can add users to any group selected here, + even if they themselves are not in the selected groups. + +*Groups That Can See This Group* + Members of any selected group can see the users in this group. + This setting is only visible if the 'usevisibilitygroups' parameter + is enabled on the Bugzilla Configuration page. See + :ref:`parameters` for information on configuring Bugzilla. + +*Groups That This Group Can See* + Members of this group can see members in any of the selected groups. + This setting is only visible if the 'usevisibilitygroups' parameter + is enabled on the the Bugzilla Configuration page. See + :ref:`parameters` for information on configuring Bugzilla. + +.. _users-and-groups: + +Assigning Users to Groups +========================= + +A User can become a member of a group in several ways: + +#. The user can be explicitly placed in the group by editing + the user's profile. This can be done by accessing the "Users" page + from the "Administration" page. Use the search form to find the user + you want to edit group membership for, and click on their email + address in the search results to edit their profile. The profile + page lists all the groups, and indicates if the user is a member of + the group either directly or indirectly. More information on indirect + group membership is below. For more details on User administration, + see :ref:`useradmin`. + +#. The group can include another group of which the user is + a member. This is indicated by square brackets around the checkbox + next to the group name in the user's profile. + See :ref:`edit-groups` for details on group inheritance. + +#. The user's email address can match the regular expression + that has been specified to automatically grant membership to + the group. This is indicated by "\*" around the check box by the + group name in the user's profile. + See :ref:`create-groups` for details on + the regular expression option when creating groups. + +Assigning Group Controls to Products +==================================== + +The primary functionality of groups is derived from the relationship of +groups to products. The concepts around segregating access to bugs with +product group controls can be confusing. For details and examples on this +topic, see :ref:`product-group-controls`. + +.. _sanitycheck: + +Checking and Maintaining Database Integrity +########################################### + +Over time it is possible for the Bugzilla database to become corrupt +or to have anomalies. +This could happen through normal usage of Bugzilla, manual database +administration outside of the Bugzilla user interface, or from some +other unexpected event. Bugzilla includes a "Sanity Check" script that +can perform several basic database checks, and repair certain problems or +inconsistencies. + +To run the "Sanity Check" script, log in as an Administrator and click the +"Sanity Check" link in the admin page. Any problems that are found will be +displayed in red letters. If the script is capable of fixing a problem, +it will present a link to initiate the fix. If the script cannot +fix the problem it will require manual database administration or recovery. + +The "Sanity Check" script can also be run from the command line via the perl +script :file:`sanitycheck.pl`. The script can also be run as +a :command:`cron` job. Results will be delivered by email. + +The "Sanity Check" script should be run on a regular basis as a matter of +best practice. + +.. warning:: The "Sanity Check" script is no substitute for a competent database + administrator. It is only designed to check and repair basic database + problems. + + diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py new file mode 100644 index 000000000..159226809 --- /dev/null +++ b/docs/en/rst/conf.py @@ -0,0 +1,246 @@ +# -*- coding: utf-8 -*- +# +# Bugzilla documentation build configuration file, created by +# sphinx-quickstart on Tue Sep 3 16:11:00 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Bugzilla' +copyright = u'2013, The Bugzilla Team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.5' +# The full version, including alpha/beta/rc tags. +release = '4.5' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Bugzilladoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Bugzilla.tex', u'Bugzilla Documentation', + u'The Bugzilla Team', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'bugzilla', u'Bugzilla Documentation', + [u'The Bugzilla Team'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Bugzilla', u'Bugzilla Documentation', + u'The Bugzilla Team', 'Bugzilla', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +definitions = "../../definitions.rst" +if os.path.exists(definitions): + execfile(definitions) diff --git a/docs/en/rst/customization.rst b/docs/en/rst/customization.rst new file mode 100644 index 000000000..4238f1650 --- /dev/null +++ b/docs/en/rst/customization.rst @@ -0,0 +1,481 @@ + + +.. _customization: + +==================== +Customizing Bugzilla +==================== + +.. _extensions: + +Bugzilla Extensions +################### + +One of the best ways to customize Bugzilla is by writing a Bugzilla +Extension. Bugzilla Extensions let you modify both the code and +UI of Bugzilla in a way that can be distributed to other Bugzilla +users and ported forward to future versions of Bugzilla with minimal +effort. + +See the `Bugzilla Extension +documentation <../html/api/Bugzilla/Extension.html>`_ for information on how to write an Extension. + +.. _cust-skins: + +Custom Skins +############ + +Bugzilla allows you to have multiple skins. These are custom CSS and possibly +also custom images for Bugzilla. To create a new custom skin, you have two +choices: + +- Make a single CSS file, and put it in the + :file:`skins/contrib` directory. + +- Make a directory that contains all the same CSS file + names as :file:`skins/standard/`, and put + your directory in :file:`skins/contrib/`. + +After you put the file or the directory there, make sure to run checksetup.pl +so that it can reset the file permissions correctly. + +After you have installed the new skin, it will show up as an option in the +user's General Preferences. If you would like to force a particular skin on all +users, just select it in the Default Preferences and then uncheck "Enabled" on +the preference. + +.. _cust-templates: + +Template Customization +###################### + +Administrators can configure the look and feel of Bugzilla without +having to edit Perl files or face the nightmare of massive merge +conflicts when they upgrade to a newer version in the future. + +Templatization also makes localized versions of Bugzilla possible, +for the first time. It's possible to have Bugzilla's UI language +determined by the user's browser. More information is available in +:ref:`template-http-accept`. + +.. _template-directory: + +Template Directory Structure +============================ + +The template directory structure starts with top level directory +named :file:`template`, which contains a directory +for each installed localization. The next level defines the +language used in the templates. Bugzilla comes with English +templates, so the directory name is :file:`en`, +and we will discuss :file:`template/en` throughout +the documentation. Below :file:`template/en` is the +:file:`default` directory, which contains all the +standard templates shipped with Bugzilla. + +.. warning:: A directory :file:`data/templates` also exists; + this is where Template Toolkit puts the compiled versions of + the templates from either the default or custom directories. + *Do not* directly edit the files in this + directory, or all your changes will be lost the next time + Template Toolkit recompiles the templates. + +.. _template-method: + +Choosing a Customization Method +=============================== + +If you want to edit Bugzilla's templates, the first decision +you must make is how you want to go about doing so. There are two +choices, and which you use depends mainly on the scope of your +modifications, and the method you plan to use to upgrade Bugzilla. + +The first method of making customizations is to directly edit the +templates found in :file:`template/en/default`. +This is probably the best way to go about it if you are going to +be upgrading Bugzilla through Bzr, because if you then execute +a :command:`bzr update`, any changes you have made will +be merged automagically with the updated versions. + +.. note:: If you use this method, and Bzr conflicts occur during an + update, the conflicted templates (and possibly other parts + of your installation) will not work until they are resolved. + +The second method is to copy the templates to be modified +into a mirrored directory structure under +:file:`template/en/custom`. Templates in this +directory structure automatically override any identically-named +and identically-located templates in the +:file:`default` directory. + +.. note:: The :file:`custom` directory does not exist + at first and must be created if you want to use it. + +The second method of customization should be used if you +use the overwriting method of upgrade, because otherwise +your changes will be lost. This method may also be better if +you are using the Bzr 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. + +Using this method, your installation may break if incompatible +changes are made to the template interface. Such changes should +be documented in the release notes, provided you are using a +stable release of Bugzilla. If you use using unstable code, you will +need to deal with this one yourself, although if possible the changes +will be mentioned before they occur in the deprecations section of the +previous stable release's release notes. + +.. note:: Regardless of which method you choose, it is recommended that + you run :command:`./checksetup.pl` after + editing any templates in the :file:`template/en/default` + directory, and after creating or editing any templates in + the :file:`custom` directory. + +.. warning:: It is *required* that you run :command:`./checksetup.pl` after + creating a new + template in the :file:`custom` directory. Failure + to do so will raise an incomprehensible error message. + +.. _template-edit: + +How To Edit Templates +===================== + +.. note:: 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 + `Developers' + Guide `_. + +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 +`Template Toolkit home +page `_. + +One thing you should take particular care about is the need +to properly HTML filter data that has been passed into the template. +This means that if the data can possibly contain special HTML characters +such as <, and the data was not intended to be HTML, they need to be +converted to entity form, i.e. <. You use the 'html' filter in the +Template Toolkit to do this (or the 'uri' filter to encode special +characters in URLs). If you forget, you may open up your installation +to cross-site scripting attacks. + +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. + +.. _template-formats: + +Template Formats and Types +========================== + +Some CGI's have the ability to use more than one template. For example, +:file:`buglist.cgi` can output itself as RDF, or as two +formats of HTML (complex and simple). The mechanism that provides this +feature is extensible. + +Bugzilla can support different types of output, which again can have +multiple formats. In order to request a certain type, you can append +the &ctype= (such as rdf or html) to the +:file:`.cgi` URL. If you would like to +retrieve a certain format, you can use the &format= +(such as simple or complex) in the URL. + +To see if a CGI supports multiple output formats and types, grep the +CGI for ``get_format``. If it's not present, adding +multiple format/type support isn't too hard - see how it's done in +other CGIs, e.g. config.cgi. + +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. + +Write your template in whatever markup or text style is appropriate. + +You now need to decide what content type you want your template +served as. The content types are defined in the +:file:`Bugzilla/Constants.pm` file in the +:file:`contenttypes` +constant. If your content type is not there, add it. Remember +the three- or four-letter tag assigned to your content type. +This tag will be part of the template filename. + +.. note:: After adding or changing a content type, it's suitable to + edit :file:`Bugzilla/Constants.pm` in order to reflect + the changes. Also, the file should be kept up to date after an + upgrade if content types have been customized in the past. + +Save the template as :file:`-..tmpl`. +Try out the template by calling the CGI as +:file:`.cgi?format=&ctype=` . + +.. _template-specific: + +Particular Templates +==================== + +There are a few templates you may be particularly interested in +customizing for your installation. + +:command:`index.html.tmpl`: +This is the Bugzilla front page. + +:command:`global/header.html.tmpl`: +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. + +:command:`global/banner.html.tmpl`: +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. + +:command:`global/footer.html.tmpl`: +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. + +:command:`global/variables.none.tmpl`: +This defines a list of terms that may be changed in order to +``brand`` the Bugzilla instance In this way, terms +like ``bugs`` can be replaced with ``issues`` +across the whole Bugzilla installation. The name +``Bugzilla`` and other words can be customized as well. + +:command:`list/table.html.tmpl`: +This template controls the appearance of the bug lists created +by Bugzilla. Editing this template allows per-column control of +the width and title of a column, the maximum display length of +each entry, and the wrap behaviour of long entries. +For long bug lists, Bugzilla inserts a 'break' every 100 bugs by +default; this behaviour is also controlled by this template, and +that value can be modified here. + +:command:`bug/create/user-message.html.tmpl`: +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. + +:command:`bug/process/midair.html.tmpl`: +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. + +:command:`bug/create/create.html.tmpl` and +:command:`bug/create/comment.txt.tmpl`: +You may not wish to go to the effort of creating custom fields in +Bugzilla, yet you want to make sure that each bug report contains +a number of pieces of important information for which there is not +a special field. The bug entry system has been designed in an +extensible fashion to enable you to add arbitrary HTML widgets, +such as drop-down lists or textboxes, to the bug entry page +and have their values appear formatted in the initial comment. +A hidden field that indicates the format should be added inside +the form in order to make the template functional. Its value should +be the suffix of the template filename. For example, if the file +is called :file:`create-cust.html.tmpl`, then + +:: + + + +should be used inside the form. + +An example of this is the mozilla.org +`guided +bug submission form <|landfillbase|enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla +distribution as an example for you to copy. It can be found in the +files +:file:`create-guided.html.tmpl` and +:file:`comment-guided.html.tmpl`. + +So to use this feature, create a custom template for +:file:`enter_bug.cgi`. The default template, on which you +could base it, is +:file:`custom/bug/create/create.html.tmpl`. +Call it :file:`create-.html.tmpl`, and +in it, add widgets for each piece of information you'd like +collected - such as a build number, or set of steps to reproduce. + +Then, create a template like +:file:`custom/bug/create/comment.txt.tmpl`, and call it +:file:`comment-.txt.tmpl`. This +template should reference the form fields you have created using +the syntax :file:`[% form. %]`. When a +bug report is +submitted, the initial comment attached to the bug report will be +formatted according to the layout of this template. + +For example, if your custom enter_bug template had a field + +:: + + + +and then your comment.txt.tmpl had + +:: + + BuildID: \[% form.buildid %] + +then something like + +:: + + BuildID: 20020303 + +would appear in the initial comment. + +.. _template-http-accept: + +Configuring Bugzilla to Detect the User's Language +================================================== + +Bugzilla honours the user's Accept: HTTP header. You can install +templates in other languages, and Bugzilla will pick the most appropriate +according to a priority order defined by you. Many +language templates can be obtained from ``_. Instructions +for submitting new languages are also available from that location. + +.. _cust-change-permissions: + +Customizing Who Can Change What +############################### + +.. warning:: This feature should be considered experimental; the Bugzilla code you + will be changing is not stable, and could change or move between + versions. Be aware that if you make modifications as outlined here, + you may have + to re-make them or port them if Bugzilla changes internally between + versions, and you upgrade. + +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. + +By default, assignees, QA owners and users +with *editbugs* privileges can edit all fields of bugs, +except group restrictions (unless they are members of the groups they +are trying to change). Bug reporters also have the ability to edit some +fields, but in a more restrictive manner. Other users, without +*editbugs* privileges, cannot edit +bugs, except to comment and add themselves to the CC list. + +For maximum flexibility, customizing this means editing Bugzilla's Perl +code. This gives the administrator complete control over exactly who is +allowed to do what. The relevant method is called +:file:`check_can_change_field()`, +and is found in :file:`Bug.pm` in your +Bugzilla/ directory. If you open that file and search for +``sub check_can_change_field``, you'll find it. + +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: + +:: + + # Allow the assignee to change anything. + if ($ownerid eq $whoid) { + return 1; + } + +It's fairly obvious what this piece of code does. + +So, how does one go about changing this function? Well, simple changes +can be made just by removing pieces - for example, if you wanted to +prevent any user adding a comment to a bug, just remove the lines marked +``Allow anyone to change comments.`` If you don't want the +Reporter to have any special rights on bugs they have filed, just +remove the entire section that deals with the Reporter. + +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.: + +:: + + if ($field eq "qacontact") { + if (Bugzilla->user->in_group("quality_assurance")) { + return 1; + } + else { + return 0; + } + } + +This says that only users in the group "quality_assurance" can change +the QA Contact field of a bug. + +Getting more weird: + +:: + + if (($field eq "priority") && + (Bugzilla->user->email =~ /.*\\@example\\.com$/)) + { + if ($oldvalue eq "P1") { + return 1; + } + else { + return 0; + } + } + +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. + +.. warning:: If you are modifying :file:`process_bug.cgi` in any + way, do not change the code that is bounded by DO_NOT_CHANGE blocks. + Doing so could compromise security, or cause your installation to + stop working entirely. + +For a list of possible field names, look at the bugs table in the +database. If you need help writing custom rules for your organization, +ask in the newsgroup. + +.. _integration: + +Integrating Bugzilla with Third-Party Tools +########################################### + +Many utilities and applications can integrate with Bugzilla, +either on the client- or server-side. None of them are maintained +by the Bugzilla community, nor are they tested during our +QA tests, so use them at your own risk. They are listed at +``_. + + diff --git a/docs/en/rst/gfdl.rst b/docs/en/rst/gfdl.rst new file mode 100644 index 000000000..4c831a1d4 --- /dev/null +++ b/docs/en/rst/gfdl.rst @@ -0,0 +1,408 @@ + + +.. _gfdl: + +============================== +GNU Free Documentation License +============================== + +.. COMMENT: - GNU Project - Free Software Foundation (FSF) + +.. COMMENT: LINK REV="made" HREF="mailto:webmasters@gnu.org" + +.. COMMENT: section> + GNU Free Documentation License`_. + +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. + +.. _gfdl-howto: + +How to use this License for your documents +########################################## + +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: + + 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". + +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. + +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. + diff --git a/docs/en/rst/glossary.rst b/docs/en/rst/glossary.rst new file mode 100644 index 000000000..e89dea743 --- /dev/null +++ b/docs/en/rst/glossary.rst @@ -0,0 +1,325 @@ + + +.. _glossary: + +======== +Glossary +======== + +0-9, high ascii +############### + +.htaccess + Apache web server, and other NCSA-compliant web servers, + observe the convention of using files in directories called + :file:`.htaccess` + to restrict access to certain files. In Bugzilla, they are used + to keep secret files which would otherwise + compromise your installation - e.g. the + :file:`localconfig` + file contains the password to your database. + curious. + +.. _gloss-a: + +A +# + +Apache + 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 + ``a patchy`` + version of the original + NCSA + world-wide-web server. + + Useful Directives when configuring Bugzilla + + ```AddHandler `_`` + Tell Apache that it's OK to run CGI scripts. + ```AllowOverride `_``, ```Options `_`` + 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 :file:`.htaccess` + overrides. + ```DirectoryIndex `_`` + Used to tell Apache what files are indexes. If you can + not add :file:`index.cgi` to the list of valid files, + you'll need to set ``$index_html`` to + 1 in :file:`localconfig` so + :command:`./checksetup.pl` will create an + :file:`index.html` that redirects to + :file:`index.cgi`. + ```ScriptInterpreterSource `_`` + Used when running Apache on windows so the shebang line + doesn't have to be changed in every Bugzilla script. + + For more information about how to configure Apache for Bugzilla, + see :ref:`http-apache`. + +.. _gloss-b: + +B +# + +Bug + A + ``bug`` + in Bugzilla refers to an issue entered into the database which has an + associated number, assignments, comments, etc. Some also refer to a + ``tickets`` + or + ``issues``; + in the context of Bugzilla, they are synonymous. + +Bug Number + 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. + +Bugzilla + Bugzilla is the world-leading free software bug tracking system. + +.. _gloss-c: + +C +# + +Common Gateway Interface (CGI) + CGI 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 CGI application. + +Component + 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). + +Comprehensive Perl Archive Network (CPAN) + CPAN + stands for the + ``Comprehensive Perl Archive Network``. + CPAN maintains a large number of extremely useful + Perl + modules - encapsulated chunks of code for performing a + particular task. + + The :file:`contrib` directory is + a location to put scripts that have been contributed to Bugzilla but + are not a part of the official distribution. These scripts are written + by third parties and may be in languages other than perl. For those + that are in perl, there may be additional modules or other requirements + than those of the official distribution. + + .. note:: Scripts in the :file:`contrib` + directory are not officially supported by the Bugzilla team and may + break in between versions. + +.. _gloss-d: + +D +# + +daemon + 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. + mysqld, + the MySQL server, and + apache, + a web server, are generally run as daemons. + +DOS Attack + A DOS, or Denial of Service attack, is when a user attempts to + deny access to a web server by repeatedly accessing a page or sending + malformed requests to a webserver. A D-DOS, or + Distributed Denial of Service attack, is when these requests come + from multiple sources at the same time. Unfortunately, these are much + more difficult to defend against. + +.. _gloss-g: + +G +# + +Groups + The word + ``Groups`` + 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 + Products + in the + Bugzilla + database. + +.. _gloss-j: + +J +# + +JavaScript + JavaScript is cool, we should talk about it. + +.. _gloss-m: + +M +# + +Message Transport Agent (MTA) + A Message Transport Agent is used to control the flow of email on a system. + The `Email::Send `_ + Perl module, which Bugzilla uses to send email, can be configured to + use many different underlying implementations for actually sending the + mail using the ``mail_delivery_method`` parameter. + +MySQL + MySQL is one of the supported + RDBMS for Bugzilla. MySQL + can be downloaded from ``_. While you + should familiarize yourself with all of the documentation, some high + points are: + + `Backup `_ + Methods for backing up your Bugzilla database. + `Option Files `_ + Information about how to configure MySQL using + :file:`my.cnf`. + `Privilege System `_ + Information about how to protect your MySQL server. + +.. _gloss-p: + +P +# + +Perl Package Manager (PPM) + ``_ + +Product + 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. + +Perl + 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. + Bugzilla + is maintained in Perl. + +.. _gloss-q: + +Q +# + +QA + ``QA``, + ``Q/A``, and + ``Q.A.`` + are short for + ``Quality Assurance``. + 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 + ``QA Contact`` + field in a bug. + +.. _gloss-r: + +R +# + +Relational DataBase Management System (RDBMS) + A relational database management system is a database system + that stores information in tables that are related to each other. + +Regular Expression (regexp) + A regular expression is an expression used for pattern matching. + `Documentation `_ + +.. _gloss-s: + +S +# + +Service + In Windows NT environment, a boot-time background application + is referred to as a service. These are generally managed through the + control panel while logged in as an account with + ``Administrator`` level capabilities. For more + information, consult your Windows manual or the MSKB. + + SGML + stands for + ``Standard Generalized Markup Language``. + Created in the 1980's to provide an extensible means to maintain + documentation based upon content instead of presentation, + SGML + has withstood the test of time as a robust, powerful language. + XML + is the + ``baby brother`` + of SGML; any valid + XML + document it, by definition, a valid + SGML + document. The document you are reading is written and maintained in + SGML, + and is also valid + XML + if you modify the Document Type Definition. + +.. _gloss-t: + +T +# + +Target Milestone + Target Milestones are Product goals. They are configurable on a + per-Product basis. Most software development houses have a concept of + ``milestones`` + 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. + +Tool Command Language (TCL) + 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. + +.. _gloss-z: + +Z +# + +Zarro Boogs Found + 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: + + *Terry Weissman*: + 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. + 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... + diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst new file mode 100644 index 000000000..d7d7bf94c --- /dev/null +++ b/docs/en/rst/index.rst @@ -0,0 +1,32 @@ +.. Bugzilla documentation master file, created by + sphinx-quickstart on Tue Sep 3 16:11:00 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Bugzilla Documentation +====================== + +Contents: + +.. toctree:: + :maxdepth: 3 + :numbered: + + about + installation + administration + security + using + customization + troubleshooting + patches + modules + gfdl + glossary + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/en/rst/installation.rst b/docs/en/rst/installation.rst new file mode 100644 index 000000000..9d92c0971 --- /dev/null +++ b/docs/en/rst/installation.rst @@ -0,0 +1,1870 @@ + + +.. _installing-bugzilla: + +=================== +Installing Bugzilla +=================== + +.. _installation: + +Installation +############ + +.. note:: If you just want to *use* Bugzilla, + you do not need to install it. None of this chapter is relevant to + you. Ask your Bugzilla administrator for the URL to access it from + your web browser. + +The Bugzilla server software is usually installed on Linux or +Solaris. +If you are installing on another OS, check :ref:`os-specific` +before you start your installation to see if there are any special +instructions. + +This guide assumes that you have administrative access to the +Bugzilla machine. It not possible to +install and run Bugzilla itself without administrative access except +in the very unlikely event that every single prerequisite is +already installed. + +.. warning:: The installation process may make your machine insecure for + short periods of time. Make sure there is a firewall between you + and the Internet. + +You are strongly recommended to make a backup of your system +before installing Bugzilla (and at regular intervals thereafter :-). + +In outline, the installation proceeds as follows: + +#. :ref:`Install Perl ` + (|min-perl-ver| or above) + +#. :ref:`Install a Database Engine ` + +#. :ref:`Install a Webserver ` + +#. :ref:`Install Bugzilla ` + +#. :ref:`Install Perl modules ` + +#. :ref:`Install a Mail Transfer Agent ` + (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) + +#. Configure all of the above. + +.. _install-perl: + +Perl +==== + +Installed Version Test: +:: + + perl -v + +Any machine that doesn't have Perl on it is a sad machine indeed. +If you don't have it and your OS doesn't provide official packages, +visit ``_. +Although Bugzilla runs with Perl |min-perl-ver|, +it's a good idea to be using the latest stable version. + +.. _install-database: + +Database Engine +=============== + +Bugzilla supports MySQL, PostgreSQL and Oracle as database servers. +You only require one of these systems to make use of Bugzilla. + +.. _install-mysql: + +MySQL +----- + +Installed Version Test: +:: + + mysql -V + +If you don't have it and your OS doesn't provide official packages, +visit ``_. You need MySQL version +5.0.15 or higher. + +.. note:: Many of the binary + versions of MySQL store their data files in :file:`/var`. + On some Unix systems, this is part of a smaller root partition, + and may not have room for your bug database. To change the data + directory, you have to build MySQL from source yourself, and + set it as an option to :file:`configure`. + +If you install from something other than a packaging/installation +system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe +(Windows Executable), or .msi (Windows Installer), make sure the MySQL +server is started when the machine boots. + +.. _install-pg: + +PostgreSQL +---------- + +Installed Version Test: +:: + + psql -V + +If you don't have it and your OS doesn't provide official packages, +visit ``_. You need PostgreSQL +version 8.03.0000 or higher. + +If you install from something other than a packaging/installation +system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe +(Windows Executable), or .msi (Windows Installer), make sure the +PostgreSQL server is started when the machine boots. + +.. _install-oracle: + +Oracle +------ + +Installed Version Test: +:: + + select * from v$version + +(you first have to log in into your DB) + +If you don't have it and your OS doesn't provide official packages, +visit ``_. You need Oracle +version 10.02.0 or higher. + +If you install from something other than a packaging/installation +system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe +(Windows Executable), or .msi (Windows Installer), make sure the +Oracle server is started when the machine boots. + +.. _install-webserver: + +Web Server +========== + +Installed Version Test: view the default welcome page at +`http:///` . + +You have freedom of choice here, pretty much any web server that +is capable of running CGI +scripts will work. +However, we strongly recommend using the Apache web server +(either 1.3.x or 2.x), and the installation instructions usually assume +you are using it. If you have got Bugzilla working using another web server, +please share your experiences with us by filing a bug in +`Bugzilla Documentation `_. + +If you don't have Apache and your OS doesn't provide official packages, +visit ``_. + +.. _install-bzfiles: + +Bugzilla +======== + +`Download a Bugzilla tarball `_ +(or `check it out from Bzr `_) +and place it in a suitable directory, accessible by the default web server user +(probably ``apache`` or ``www``). +Good locations are either directly in the web server's document directories or +in :file:`/usr/local` with a symbolic link to the web server's +document directories or an alias in the web server's configuration. + +.. caution:: The default Bugzilla distribution is NOT designed to be placed + in a :file:`cgi-bin` directory. This + includes any directory which is configured using the + ``ScriptAlias`` directive of Apache. + +Once all the files are in a web accessible directory, make that +directory writable by your web server's user. This is a temporary step +until you run the +:file:`checksetup.pl` +script, which locks down your installation. + +.. _install-perlmodules: + +Perl Modules +============ + +Bugzilla's installation process is based +on a script called :file:`checksetup.pl`. +The first thing it checks is whether you have appropriate +versions of all the required +Perl modules. The aim of this section is to pass this check. +When it passes, proceed to :ref:`configuration`. + +At this point, you need to :file:`su` to root. You should +remain as root until the end of the install. To check you have the +required modules, run: + +:: + + bash# ./checksetup.pl --check-modules + +:file:`checksetup.pl` will print out a list of the +required and optional Perl modules, together with the versions +(if any) installed on your machine. +The list of required modules is reasonably long; however, you +may already have several of them installed. + +The preferred way to install missing Perl modules is to use the package +manager provided by your operating system (e.g ``rpm`` or +``yum`` on Linux distros, or ``ppm`` on Windows +if using ActivePerl, see :ref:`win32-perl-modules`). +If some Perl modules are still missing or are too old, then we recommend +using the :file:`install-module.pl` script (doesn't work +with ActivePerl on Windows). If for some reason you really need to +install the Perl modules manually, see +:ref:`install-perlmodules-manual`. For instance, on Unix, +you invoke :file:`install-module.pl` as follows: + +:: + + bash# perl install-module.pl + +.. tip:: Many people complain that Perl modules will not install for + them. Most times, the error messages complain that they are missing a + file in + ``@INC``. + 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 + *are* + the local UNIX sysadmin, please consult the newsgroup/mailing list + for further assistance or hire someone to help you out. + +.. note:: If you are using a package-based system, and attempting to install the + Perl modules from CPAN, you may need to install the "development" packages for + MySQL and GD before attempting to install the related Perl modules. The names of + these packages will vary depending on the specific distribution you are using, + but are often called :file:`-devel`. + +Here is a complete list of modules and their minimum versions. +Some modules have special installation notes, which follow. + +Required Perl modules: + +#. CGI (|min-cgi-ver|) + +#. Date::Format (|min-date-format-ver|) + +#. DateTime (|min-datetime-ver|) + +#. DateTime::TimeZone (|min-datetime-timezone-ver|) + +#. DBI (|min-dbi-ver|) + +#. DBD::mysql (|min-dbd-mysql-ver|) if using MySQL + +#. DBD::Pg (|min-dbd-pg-ver|) if using PostgreSQL + +#. DBD::Oracle (|min-dbd-oracle-ver|) if using Oracle + +#. Digest::SHA (|min-digest-sha-ver|) + +#. Email::Send (|min-email-send-ver|) + +#. Email::MIME (|min-email-mime-ver|) + +#. Template (|min-template-ver|) + +#. URI (|min-uri-ver|) + +Optional Perl modules: + +#. GD (|min-gd-ver|) for bug charting + +#. Template::Plugin::GD::Image + (|min-template-plugin-gd-image-ver|) for Graphical Reports + +#. Chart::Lines (|min-chart-lines-ver|) for bug charting + +#. GD::Graph (|min-gd-graph-ver|) for bug charting + +#. GD::Text (|min-gd-text-ver|) for bug charting + +#. XML::Twig (|min-xml-twig-ver|) for bug import/export + +#. MIME::Parser (|min-mime-parser-ver|) for bug import/export + +#. LWP::UserAgent + (|min-lwp-useragent-ver|) for Automatic Update Notifications + +#. PatchReader (|min-patchreader-ver|) for pretty HTML view of patches + +#. Net::LDAP + (|min-net-ldap-ver|) for LDAP Authentication + +#. Authen::SASL + (|min-authen-sasl-ver|) for SASL Authentication + +#. Authen::Radius + (|min-authen-radius-ver|) for RADIUS Authentication + +#. SOAP::Lite (|min-soap-lite-ver|) for the web service interface + +#. JSON::RPC + (|min-json-rpc-ver|) for the JSON-RPC interface + +#. Test::Taint + (|min-test-taint-ver|) for the web service interface + +#. HTML::Parser + (|min-html-parser-ver|) for More HTML in Product/Group Descriptions + +#. HTML::Scrubber + (|min-html-scrubber-ver|) for More HTML in Product/Group Descriptions + +#. Email::Reply + (|min-email-reply-ver|) for Inbound Email + +#. TheSchwartz + (|min-theschwartz-ver|) for Mail Queueing + +#. Daemon::Generic + (|min-daemon-generic-ver|) for Mail Queueing + +#. mod_perl2 + (|min-mod_perl2-ver|) for mod_perl + +.. _install-MTA: + +Mail Transfer Agent (MTA) +========================= + +Bugzilla is dependent on the availability of an e-mail system for its +user authentication and for other tasks. + +.. note:: This is not entirely true. It is possible to completely disable + email sending, or to have Bugzilla store email messages in a + file instead of sending them. However, this is mainly intended + for testing, as disabling or diverting email on a production + machine would mean that users could miss important events (such + as bug changes or the creation of new accounts). + For more information, see the ``mail_delivery_method`` parameter + in :ref:`parameters`. + +On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will +suffice. Sendmail, Postfix, qmail and Exim are examples of common +MTAs. Sendmail is the original Unix MTA, but the others are easier to +configure, and therefore many people replace Sendmail with Postfix or +Exim. They are drop-in replacements, so Bugzilla will not +distinguish between them. + +If you are using Sendmail, version 8.7 or higher is required. +If you are using a Sendmail-compatible MTA, it must be congruent with +at least version 8.7 of Sendmail. + +Consult the manual for the specific MTA you choose for detailed +installation instructions. Each of these programs will have their own +configuration files where you must configure certain parameters to +ensure that the mail is delivered properly. They are implemented +as services, and you should ensure that the MTA is in the auto-start +list of services for the machine. + +If a simple mail sent with the command-line 'mail' program +succeeds, then Bugzilla should also be fine. + +.. _using-mod_perl-with-bugzilla: + +Installing Bugzilla on mod_perl +=============================== + +It is now possible to run the Bugzilla software under ``mod_perl`` on +Apache. ``mod_perl`` has some additional requirements to that of running +Bugzilla under ``mod_cgi`` (the standard and previous way). + +Bugzilla requires ``mod_perl`` to be installed, which can be +obtained from ``_ - Bugzilla requires +version 1.999022 (AKA 2.0.0-RC5) to be installed. + +.. _configuration: + +Configuration +############# + +.. warning:: Poorly-configured MySQL and Bugzilla installations have + given attackers full access to systems in the past. Please take the + security parts of these guidelines seriously, even for Bugzilla + machines hidden away behind your firewall. Be certain to + read :ref:`security` for some important security tips. + +.. _localconfig: + +localconfig +=========== + +You should now run :file:`checksetup.pl` again, this time +without the ``--check-modules`` switch. + +:: + + bash# ./checksetup.pl + +This time, :file:`checksetup.pl` should tell you that all +the correct modules are installed and will display a message about, and +write out a file called, :file:`localconfig`. This file +contains the default settings for a number of Bugzilla parameters. + +Load this file in your editor. The only two values you +*need* to change are $db_driver and $db_pass, +respectively the type of the database and the password for +the user you will create for your database. Pick a strong +password (for simplicity, it should not contain single quote +characters) and put it here. $db_driver can be either 'mysql', +'Pg', 'Oracle' or 'Sqlite'. + +.. note:: In Oracle, ``$db_name`` should actually be + the SID name of your database (e.g. "XE" if you are using Oracle XE). + +You may need to change the value of +*webservergroup* if your web server does not +run in the "apache" group. On Debian, for example, Apache runs in +the "www-data" group. If you are going to run Bugzilla on a +machine where you do not have root access (such as on a shared web +hosting account), you will need to leave +*webservergroup* empty, ignoring the warnings +that :file:`checksetup.pl` will subsequently display +every time it is run. + +.. caution:: If you are using suexec, you should use your own primary group + for *webservergroup* rather than leaving it + empty, and see the additional directions in the suexec section :ref:`suexec`. + +The other options in the :file:`localconfig` file +are documented by their accompanying comments. If you have a slightly +non-standard database setup, you may wish to change one or more of +the other "$db_*" parameters. + +.. _database-engine: + +Database Server +=============== + +This section deals with configuring your database server for use +with Bugzilla. Currently, MySQL (:ref:`mysql`), +PostgreSQL (:ref:`postgresql`), Oracle (:ref:`oracle`) +and SQLite (:ref:`sqlite`) are available. + +.. _database-schema: + +Bugzilla Database Schema +------------------------ + +The Bugzilla database schema is available at +`Ravenbrook `_. +This very valuable tool can generate a written description of +the Bugzilla database schema for any version of Bugzilla. It +can also generate a diff between two versions to help someone +see what has changed. + +.. _mysql: + +MySQL +----- + +.. caution:: MySQL's default configuration is insecure. + We highly recommend to run :file:`mysql_secure_installation` + on Linux or the MySQL installer on Windows, and follow the instructions. + Important points to note are: + +#. Be sure that the root account has a secure password set. +#. Do not create an anonymous account, and if it exists, say "yes" + to remove it. +#. If your web server and MySQL server are on the same machine, + you should disable the network access. + +.. _mysql-max-allowed-packet: + +Allow large attachments and many comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, MySQL will only allow you to insert things +into the database that are smaller than 1MB. Attachments +may be larger than this. Also, Bugzilla combines all comments +on a single bug into one field for full-text searching, and the +combination of all comments on a single bug could in some cases +be larger than 1MB. + +To change MySQL's default, you need to edit your MySQL +configuration file, which is usually :file:`/etc/my.cnf` +on Linux. We recommend that you allow at least 4MB packets by +adding the "max_allowed_packet" parameter to your MySQL +configuration in the "\[mysqld]" section, like this: + +:: + + [mysqld] + # Allow packets up to 4MB + max_allowed_packet=4M + +Allow small words in full-text indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, words must be at least four characters in length +in order to be indexed by MySQL's full-text indexes. This causes +a lot of Bugzilla specific words to be missed, including "cc", +"ftp" and "uri". + +MySQL can be configured to index those words by setting the +ft_min_word_len param to the minimum size of the words to index. +This can be done by modifying the :file:`/etc/my.cnf` +according to the example below: + +:: + + [mysqld] + # Allow small words in full-text indexes + ft_min_word_len=2 + +Rebuilding the indexes can be done based on documentation found at +``_. + +.. _install-setupdatabase-adduser: + +Add a user to MySQL +~~~~~~~~~~~~~~~~~~~ + +You need to add a new MySQL user for Bugzilla to use. +(It's not safe to have Bugzilla use the MySQL root account.) +The following instructions assume the defaults in +:file:`localconfig`; if you changed those, +you need to modify the SQL command appropriately. You will +need the $db_pass password you +set in :file:`localconfig` in +:ref:`localconfig`. + +We use an SQL :command:`GRANT` command to create +a ``bugs`` user. This also restricts the +``bugs`` user to operations within a database +called ``bugs``, and only allows the account +to connect from ``localhost``. Modify it to +reflect your setup if you will be connecting from another +machine or as a different user. + +Run the :file:`mysql` command-line client and enter: + +:: + + mysql> GRANT SELECT, INSERT, + UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, + CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* + TO bugs@localhost IDENTIFIED BY '$db_pass'; + mysql> FLUSH PRIVILEGES; + +Permit attachments table to grow beyond 4GB +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, MySQL will limit the size of a table to 4GB. +This limit is present even if the underlying filesystem +has no such limit. To set a higher limit, follow these +instructions. + +After you have completed the rest of the installation (or at least the +database setup parts), you should run the :file:`MySQL` +command-line client and enter the following, replacing ``$bugs_db`` +with your Bugzilla database name (*bugs* by default): + +:: + + mysql> use $bugs_db + mysql> ALTER TABLE attachments + AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; + +The above command will change the limit to 20GB. Mysql will have +to make a temporary copy of your entire table to do this. Ideally, +you should do this when your attachments table is still small. + +.. note:: This does not affect Big Files, attachments that are stored directly + on disk instead of in the database. + +.. _postgresql: + +PostgreSQL +---------- + +Add a User to PostgreSQL +~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to add a new user to PostgreSQL for the Bugzilla +application to use when accessing the database. The following instructions +assume the defaults in :file:`localconfig`; if you +changed those, you need to modify the commands appropriately. You will +need the $db_pass password you +set in :file:`localconfig` in +:ref:`localconfig`. + +On most systems, to create the user in PostgreSQL, you will need to +login as the root user, and then + +:: + + bash# su - postgres + +As the postgres user, you then need to create a new user: + +:: + + bash$ createuser -U postgres -dRSP bugs + +When asked for a password, provide the password which will be set as +$db_pass in :file:`localconfig`. +The created user will not be a superuser (-S) and will not be able to create +new users (-R). He will only have the ability to create databases (-d). + +Configure PostgreSQL +~~~~~~~~~~~~~~~~~~~~ + +Now, you will need to edit :file:`pg_hba.conf` which is +usually located in :file:`/var/lib/pgsql/data/`. In this file, +you will need to add a new line to it as follows: + +``host all bugs 127.0.0.1 255.255.255.255 md5`` + +This means that for TCP/IP (host) connections, allow connections from +'127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use +password authentication (md5) for that user. + +Now, you will need to restart PostgreSQL, but you will need to fully +stop and start the server rather than just restarting due to the possibility +of a change to :file:`postgresql.conf`. After the server has +restarted, you will need to edit :file:`localconfig`, finding +the ``$db_driver`` variable and setting it to +``Pg`` and changing the password in ``$db_pass`` +to the one you picked previously, while setting up the account. + +.. _oracle: + +Oracle +------ + +Create a New Tablespace +~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the existing tablespace or create a new one for Bugzilla. +To create a new tablespace, run the following command: + +:: + + CREATE TABLESPACE bugs + DATAFILE '*$path_to_datafile*' SIZE 500M + AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED + +Here, the name of the tablespace is 'bugs', but you can +choose another name. *$path_to_datafile* is +the path to the file containing your database, for instance +:file:`/u01/oradata/bugzilla.dbf`. +The initial size of the database file is set in this example to 500 Mb, +with an increment of 30 Mb everytime we reach the size limit of the file. + +Add a User to Oracle +~~~~~~~~~~~~~~~~~~~~ + +The user name and password must match what you set in +:file:`localconfig` (``$db_user`` +and ``$db_pass``, respectively). Here, we assume that +the user name is 'bugs' and the tablespace name is the same +as above. + +:: + + CREATE USER bugs + IDENTIFIED BY "$db_pass" + DEFAULT TABLESPACE bugs + TEMPORARY TABLESPACE TEMP + PROFILE DEFAULT; + -- GRANT/REVOKE ROLE PRIVILEGES + GRANT CONNECT TO bugs; + GRANT RESOURCE TO bugs; + -- GRANT/REVOKE SYSTEM PRIVILEGES + GRANT UNLIMITED TABLESPACE TO bugs; + GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs; + +Configure the Web Server +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you use Apache, append these lines to :file:`httpd.conf` +to set ORACLE_HOME and LD_LIBRARY_PATH. For instance: + +:: + + SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/ + SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/ + +When this is done, restart your web server. + +.. _sqlite: + +SQLite +------ + +.. caution:: Due to SQLite's `concurrency + limitations `_ we recommend SQLite only for small and development + Bugzilla installations. + +No special configuration is required to run Bugzilla on SQLite. +The database will be stored in :file:`data/db/$db_name`, +where ``$db_name`` is the database name defined +in :file:`localconfig`. + +checksetup.pl +============= + +Next, rerun :file:`checksetup.pl`. It reconfirms +that all the modules are present, and notices the altered +localconfig file, which it assumes you have edited to your +satisfaction. It compiles the UI templates, +connects to the database using the 'bugs' +user you created and the password you defined, and creates the +'bugs' database and the tables therein. + +After that, it asks for details of an administrator account. Bugzilla +can have multiple administrators - you can create more later - but +it needs one to start off with. +Enter the email address of an administrator, his or her full name, +and a suitable Bugzilla password. + +:file:`checksetup.pl` will then finish. You may rerun +:file:`checksetup.pl` at any time if you wish. + +.. _http: + +Web server +========== + +Configure your web server according to the instructions in the +appropriate section. (If it makes a difference in your choice, +the Bugzilla Team recommends Apache.) To check whether your web server +is correctly configured, try to access :file:`testagent.cgi` +from your web server. If "OK" is displayed, then your configuration +is successful. Regardless of which web server +you are using, however, ensure that sensitive information is +not remotely available by properly applying the access controls in +:ref:`security-webserver-access`. You can run +:file:`testserver.pl` to check if your web server serves +Bugzilla files as expected. + +.. _http-apache: + +Bugzilla using Apache +--------------------- + +You have two options for running Bugzilla under Apache - +:ref:`mod_cgi ` (the default) and +:ref:`mod_perl ` (new in Bugzilla +2.23) + +.. _http-apache-mod_cgi: + +Apache *httpd* with mod_cgi +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure your Apache web server to work with Bugzilla while using +mod_cgi, do the following: + +#. Load :file:`httpd.conf` in your editor. + In Fedora and Red Hat Linux, this file is found in + :file:`/etc/httpd/conf`. + +#. Apache uses ```` + directives to permit fine-grained permission setting. Add the + following lines to a directive that applies to the location + of your Bugzilla installation. (If such a section does not + exist, you'll want to add one.) In this example, Bugzilla has + been installed at :file:`/var/www/html/bugzilla`. + + :: + + AddHandler cgi-script .cgi + Options +ExecCGI + DirectoryIndex index.cgi index.html + AllowOverride Limit FileInfo Indexes Options + + + These instructions: allow apache to run .cgi files found + within the bugzilla directory; instructs the server to look + for a file called :file:`index.cgi` or, if not + found, :file:`index.html` if someone + only types the directory name into the browser; and allows + Bugzilla's :file:`.htaccess` files to override + some global permissions. + + .. note:: It is possible to make these changes globally, or to the + directive controlling Bugzilla's parent directory (e.g. + ````). + Such changes would also apply to the Bugzilla directory... + but they would also apply to many other places where they + may or may not be appropriate. In most cases, including + this one, it is better to be as restrictive as possible + when granting extra access. + + .. note:: On Windows, you may have to also add the + ``ScriptInterpreterSource Registry-Strict`` + line, see :ref:`Windows specific notes `. + +#. :file:`checksetup.pl` can set tighter permissions + on Bugzilla's files and directories if it knows what group the + web server runs as. Find the ``Group`` + line in :file:`httpd.conf`, place the value found + there in the *$webservergroup* variable + in :file:`localconfig`, then rerun :file:`checksetup.pl`. + +#. Optional: If Bugzilla does not actually reside in the webspace + directory, but instead has been symbolically linked there, you + will need to add the following to the + ``Options`` line of the Bugzilla + ```` directive + (the same one as in the step above): + + :: + +FollowSymLinks + + Without this directive, Apache will not follow symbolic links + to places outside its own directory structure, and you will be + unable to run Bugzilla. + +.. _http-apache-mod_perl: + +Apache *httpd* with mod_perl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some configuration is required to make Bugzilla work with Apache +and mod_perl + +#. Load :file:`httpd.conf` in your editor. + In Fedora and Red Hat Linux, this file is found in :file:`/etc/httpd/conf`. + +#. Add the following information to your httpd.conf file, substituting + where appropriate with your own local paths. + + .. note:: This should be used instead of the block + shown above. This should also be above any other ``mod_perl`` + directives within the :file:`httpd.conf` and must be specified + in the order as below. + + .. warning:: You should also ensure that you have disabled ``KeepAlive`` + support in your Apache install when utilizing Bugzilla under mod_perl + + :: + PerlSwitches -w -T + PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl + +#. :file:`checksetup.pl` can set tighter permissions + on Bugzilla's files and directories if it knows what group the + web server runs as. Find the ``Group`` + line in :file:`httpd.conf`, place the value found + there in the *$webservergroup* variable + in :file:`localconfig`, then rerun :file:`checksetup.pl`. + +On restarting Apache, Bugzilla should now be running within the +mod_perl environment. Please ensure you have run checksetup.pl to set +permissions before you restart Apache. + +.. note:: Please bear the following points in mind when looking at using + Bugzilla under mod_perl: + + - mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be + looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM. + The more RAM you can get, the better. mod_perl is basically trading RAM for + speed. At least 2GB total system RAM is recommended for running Bugzilla under + mod_perl. + - Under mod_perl, you have to restart Apache if you make any manual change to + any Bugzilla file. You can't just reload--you have to actually + *restart* the server (as in make sure it stops and starts + again). You *can* change localconfig and the params file + manually, if you want, because those are re-read every time you load a page. + - You must run in Apache's Prefork MPM (this is the default). The Worker MPM + may not work--we haven't tested Bugzilla's mod_perl support under threads. + (And, in fact, we're fairly sure it *won't* work.) + - Bugzilla generally expects to be the only mod_perl application running on + your entire server. It may or may not work if there are other applications also + running under mod_perl. It does try its best to play nice with other mod_perl + applications, but it still may have conflicts. + - It is recommended that you have one Bugzilla instance running under mod_perl + on your server. Bugzilla has not been tested with more than one instance running. + +.. _http-iis: + +Microsoft *Internet Information Services* +----------------------------------------- + +If you are running Bugzilla on Windows and choose to use +Microsoft's *Internet Information Services* +or *Personal Web Server* you will need +to perform a number of other configuration steps as explained below. +You may also want to refer to the following Microsoft Knowledge +Base articles: +`245225 - HOW TO: Configure and Test a PERL Script with IIS 4.0, +5.0, and 5.1 `_ +(for *Internet Information Services*) and +`231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web +Server on Windows 95/98 `_ +(for *Personal Web Server*). + +You will need to create a virtual directory for the Bugzilla +install. Put the Bugzilla files in a directory that is named +something *other* than what you want your +end-users accessing. That is, if you want your users to access +your Bugzilla installation through +``http:///Bugzilla``, then do +*not* put your Bugzilla files in a directory +named ``Bugzilla``. Instead, place them in a different +location, and then use the IIS Administration tool to create a +Virtual Directory named "Bugzilla" that acts as an alias for the +actual location of the files. When creating that virtual directory, +make sure you add the ``Execute (such as ISAPI applications or +CGI)`` access permission. + +You will also need to tell IIS how to handle Bugzilla's +.cgi files. Using the IIS Administration tool again, open up +the properties for the new virtual directory and select the +Configuration option to access the Script Mappings. Create an +entry mapping .cgi to: + +:: + + \perl.exe -x -wT "%s" %s + +For example: + +:: + + c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s + +.. note:: The ActiveState install may have already created an entry for + .pl files that is limited to ``GET,HEAD,POST``. If + so, this mapping should be *removed* as + Bugzilla's .pl files are not designed to be run via a web server. + +IIS will also need to know that the index.cgi should be treated +as a default document. On the Documents tab page of the virtual +directory properties, you need to add index.cgi as a default +document type. If you wish, you may remove the other default +document types for this particular virtual directory, since Bugzilla +doesn't use any of them. + +Also, and this can't be stressed enough, make sure that files +such as :file:`localconfig` and your +:file:`data` directory are +secured as described in :ref:`security-webserver-access`. + +.. _install-config-bugzilla: + +Bugzilla +======== + +Your Bugzilla should now be working. Access +:file:`http:///` - +you should see the Bugzilla +front page. If not, consult the Troubleshooting section, +:ref:`troubleshooting`. + +.. note:: The URL above may be incorrect if you installed Bugzilla into a + subdirectory or used a symbolic link from your web site root to + the Bugzilla directory. + +Log in with the administrator account you defined in the last +:file:`checksetup.pl` run. You should go through +the Parameters page and see if there are any you wish to change. +They key parameters are documented in :ref:`parameters`; +you should certainly alter +:command:`maintainer` and :command:`urlbase`; +you may also want to alter +:command:`cookiepath` or :command:`requirelogin`. + +Bugzilla has several optional features which require extra +configuration. You can read about those in +:ref:`extraconfig`. + +.. _extraconfig: + +Optional Additional Configuration +################################# + +Bugzilla has a number of optional features. This section describes how +to configure or enable them. + +Bug Graphs +========== + +If you have installed the necessary Perl modules you +can start collecting statistics for the nifty Bugzilla +graphs. + +:: + + bash# crontab -e + +This should bring up the crontab file in your editor. +Add a cron entry like this to run +:file:`collectstats.pl` +daily at 5 after midnight: + +:: + + 5 0 * * * cd && ./collectstats.pl + +After two days have passed you'll be able to view bug graphs from +the Reports page. + +.. note:: Windows does not have 'cron', but it does have the Task + Scheduler, which performs the same duties. There are also + third-party tools that can be used to implement cron, such as + `nncron `_. + +.. _installation-whining-cron: + +The Whining Cron +================ + +What good are +bugs if they're not annoying? To help make them more so you +can set up Bugzilla's automatic whining system to complain at engineers +which leave their bugs in the CONFIRMED state without triaging them. + +This can be done by adding the following command as a daily +crontab entry, in the same manner as explained above for bug +graphs. This example runs it at 12.55am. + +:: + + 55 0 * * * cd && ./whineatnews.pl + +.. note:: Windows does not have 'cron', but it does have the Task + Scheduler, which performs the same duties. There are also + third-party tools that can be used to implement cron, such as + `nncron `_. + +.. _installation-whining: + +Whining +======= + +As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy +them at regular intervals, by having Bugzilla execute saved searches +at certain times and emailing the results to the user. This is known +as "Whining". The process of configuring Whining is described +in :ref:`whining`, but for it to work a Perl script must be +executed at regular intervals. + +This can be done by adding the following command as a daily +crontab entry, in the same manner as explained above for bug +graphs. This example runs it every 15 minutes. + +:: + + */15 * * * * cd && ./whine.pl + +.. note:: Whines can be executed as often as every 15 minutes, so if you specify + longer intervals between executions of whine.pl, some users may not + be whined at as often as they would expect. Depending on the person, + this can either be a very Good Thing or a very Bad Thing. + +.. note:: Windows does not have 'cron', but it does have the Task + Scheduler, which performs the same duties. There are also + third-party tools that can be used to implement cron, such as + `nncron `_. + +.. _apache-addtype: + +Serving Alternate Formats with the right MIME type +================================================== + +Some Bugzilla pages have alternate formats, other than just plain +HTML. In particular, a few Bugzilla pages can +output their contents as either XUL (a special +Mozilla format, that looks like a program GUI) +or RDF (a type of structured XML +that can be read by various programs). + +In order for your users to see these pages correctly, Apache must +send them with the right MIME type. To do this, +add the following lines to your Apache configuration, either in the +```` section for your +Bugzilla, or in the ```` +section for your Bugzilla: + +:: + + AddType application/vnd.mozilla.xul+xml .xul + AddType application/rdf+xml .rdf + +.. _multiple-bz-dbs: + +Multiple Bugzilla databases with a single installation +###################################################### + +The previous instructions referred to a standard installation, with +one unique Bugzilla database. However, you may want to host several +distinct installations, without having several copies of the code. This is +possible by using the PROJECT environment variable. When accessed, +Bugzilla checks for the existence of this variable, and if present, uses +its value to check for an alternative configuration file named +:file:`localconfig.` in the same location as +the default one (:file:`localconfig`). It also checks for +customized templates in a directory named +:file:`` in the same location as the +default one (:file:`template/`). By default +this is :file:`template/en/default` so PROJECT's templates +would be located at :file:`template/en/PROJECT`. + +To set up an alternate installation, just export PROJECT=foo before +running :command:`checksetup.pl` for the first time. It will +result in a file called :file:`localconfig.foo` instead of +:file:`localconfig`. Edit this file as described above, with +reference to a new database, and re-run :command:`checksetup.pl` +to populate it. That's all. + +Now you have to configure the web server to pass this environment +variable when accessed via an alternate URL, such as virtual host for +instance. The following is an example of how you could do it in Apache, +other Webservers may differ. +:: + + + ServerName foo.bar.baz + SetEnv PROJECT foo + Alias /bugzilla /var/www/bugzilla + + +Don't forget to also export this variable before accessing Bugzilla +by other means, such as cron tasks for instance. + +.. _os-specific: + +OS-Specific Installation Notes +############################## + +Many aspects of the Bugzilla installation can be affected by the +operating system you choose to install it on. Sometimes it can be made +easier and others more difficult. This section will attempt to help you +understand both the difficulties of running on specific operating systems +and the utilities available to make it easier. + +If you have anything to add or notes for an operating system not covered, +please file a bug in `Bugzilla Documentation `_. + +.. _os-win32: + +Microsoft Windows +================= + +Making Bugzilla work on Windows is more difficult than making it +work on Unix. For that reason, we still recommend doing so on a Unix +based system such as GNU/Linux. That said, if you do want to get +Bugzilla running on Windows, you will need to make the following +adjustments. A detailed step-by-step +`installation guide for Windows `_ is also available +if you need more help with your installation. + +.. _win32-perl: + +Win32 Perl +---------- + +Perl for Windows can be obtained from +`ActiveState `_. +You should be able to find a compiled binary at ``_. +The following instructions assume that you are using version +|min-perl-ver| of ActiveState. + +.. note:: These instructions are for 32-bit versions of Windows. If you are + using a 64-bit version of Windows, you will need to install 32-bit + Perl in order to install the 32-bit modules as described below. + +.. _win32-perl-modules: + +Perl Modules on Win32 +--------------------- + +Bugzilla on Windows requires the same perl modules found in +:ref:`install-perlmodules`. The main difference is that +windows uses PPM instead +of CPAN. ActiveState provides a GUI to manage Perl modules. We highly +recommend that you use it. If you prefer to use ppm from the +command-line, type: + +:: + + C:\perl> ppm install + +If you are using Perl |min-perl-ver|, the best source for the Windows PPM modules +needed for Bugzilla is probably the theory58S website, which you can add +to your list of repositories as follows: + +:: + + ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/ + +If you are using Perl 5.12 or newer, you no longer need to add +this repository. All modules you need are already available from +the ActiveState repository. + +.. note:: The PPM repository stores modules in 'packages' that may have + a slightly different name than the module. If retrieving these + modules from there, you will need to pay attention to the information + provided when you run :command:`checksetup.pl` as it will + tell you what package you'll need to install. + +.. tip:: If you are behind a corporate firewall, you will need to let the + ActiveState PPM utility know how to get through it to access + the repositories by setting the HTTP_proxy system environmental + variable. For more information on setting that variable, see + the ActiveState documentation. + +.. _win32-http: + +Serving the web pages +--------------------- + +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 :ref:`security-webserver-access`. More +information on configuring specific web servers can be found +in :ref:`http`. + +.. note:: The web server looks at :file:`/usr/bin/perl` to + call Perl. If you are using Apache on windows, you can set the + `ScriptInterpreterSource `_ + directive in your Apache config file to make it look at the + right place: insert the line + + :: + ScriptInterpreterSource Registry-Strict + + into your :file:`httpd.conf` file, and create the key + + :: + HKEY_CLASSES_ROOT\\.cgi\\Shell\\ExecCGI\\Command + + with ``C:\\Perl\\bin\\perl.exe -T`` as value (adapt to your + path if needed) in the registry. When this is done, restart Apache. + +.. _win32-email: + +Sending Email +------------- + +To enable Bugzilla to send email on Windows, the server running the +Bugzilla code must be able to connect to, or act as, an SMTP server. + +.. _os-macosx: + +*Mac OS X* +========== + +Making Bugzilla work on Mac OS X requires the following +adjustments. + +.. _macosx-sendmail: + +Sendmail +-------- + +In Mac OS X 10.3 and later, +`Postfix `_ +is used as the built-in email server. Postfix provides an executable +that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can +find it. Bugzilla is able to find the fake sendmail executable without +any assistance. + +.. _macosx-libraries: + +Libraries & Perl Modules on Mac OS X +------------------------------------ + +Apple does not include the GD library with Mac OS X. Bugzilla +needs this for bug graphs. + +You can use MacPorts (``_) +or Fink (``_), both +of which are similar in nature to the CPAN installer, but install +common unix programs. + +Follow the instructions for setting up MacPorts or Fink. +Once you have one installed, you'll want to use it to install the +:file:`gd2` package. + +Fink will prompt you for a number of dependencies, type 'y' and hit +enter to install all of the dependencies and then watch it work. You will +then be able to use CPAN to +install the GD Perl module. + +.. note:: To prevent creating conflicts with the software that Apple + installs by default, Fink creates its own directory tree at :file:`/sw` + where it installs most of + the software that it installs. This means your libraries and headers + will be at :file:`/sw/lib` and :file:`/sw/include` instead + of :file:`/usr/lib` and :file:`/usr/include`. When the + Perl module config script asks where your :file:`libgd` + is, be sure to tell it :file:`/sw/lib`. + +Also available via MacPorts and Fink is +:file:`expat`. After installing the expat package, you +will be able to install XML::Parser using CPAN. If you use fink, there +is one caveat. Unlike recent versions of +the GD module, XML::Parser doesn't prompt for the location of the +required libraries. When using CPAN, you will need to use the following +command sequence: + +:: + + # perl -MCPAN -e'look XML::Parser' + # perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include + # make; make test; make install + # exit + +The :command:`look` command will download the module and spawn +a new shell with the extracted files as the current working directory. + +You should watch the output from these :command:`make` commands, +especially ``make test`` as errors may prevent +XML::Parser from functioning correctly with Bugzilla. + +The :command:`exit` command will return you to your original shell. + +.. _os-linux: + +Linux Distributions +=================== + +Many Linux distributions include Bugzilla and its +dependencies in their native package management systems. +Installing Bugzilla with root access on any Linux system +should be as simple as finding the Bugzilla package in the +package management application and installing it using the +normal command syntax. Several distributions also perform +the proper web server configuration automatically on installation. + +Please consult the documentation of your Linux +distribution for instructions on how to install packages, +or for specific instructions on installing Bugzilla with +native package management tools. There is also a +`Bugzilla Wiki Page `_ for distro-specific installation +notes. + +.. _nonroot: + +UNIX (non-root) Installation Notes +################################## + +Introduction +============ + +If you are running a \*NIX OS as non-root, either due +to lack of access (web hosts, for example) or for security +reasons, this will detail how to install Bugzilla on such +a setup. It is recommended that you read through the +:ref:`installation` +first to get an idea on the installation steps required. +(These notes will reference to steps in that guide.) + +MySQL +===== + +You may have MySQL installed as root. If you're +setting up an account with a web host, a MySQL account +needs to be set up for you. From there, you can create +the bugs account, or use the account given to you. + +.. warning:: You may have problems trying to set up :command:`GRANT` + permissions to the database. + If you're using a web host, chances are that you have a + separate database which is already locked down (or one big + database with limited/no access to the other areas), but you + may want to ask your system administrator what the security + settings are set to, and/or run the :command:`GRANT` + command for you. + Also, you will probably not be able to change the MySQL + root user password (for obvious reasons), so skip that + step. + +Running MySQL as Non-Root +------------------------- + +The Custom Configuration Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create a file .my.cnf in your +home directory (using /home/foo in this example) +as follows.... + +:: + + [mysqld] + datadir=/home/foo/mymysql + socket=/home/foo/mymysql/thesock + port=8081 + [mysql] + socket=/home/foo/mymysql/thesock + port=8081 + [mysql.server] + user=mysql + basedir=/var/lib + [safe_mysqld] + err-log=/home/foo/mymysql/the.log + pid-file=/home/foo/mymysql/the.pid + +The Custom Built Method +~~~~~~~~~~~~~~~~~~~~~~~ + +You can install MySQL as a not-root, if you really need to. +Build it with PREFIX set to :file:`/home/foo/mysql`, +or use pre-installed executables, specifying that you want +to put all of the data files in :file:`/home/foo/mysql/data`. +If there is another MySQL server running on the system that you +do not own, use the -P option to specify a TCP port that is not +in use. + +Starting the Server +~~~~~~~~~~~~~~~~~~~ + +After your mysqld program is built and any .my.cnf file is +in place, you must initialize the databases (ONCE). + +:: + + bash$ mysql_install_db + +Then start the daemon with + +:: + + bash$ safe_mysql & + +After you start mysqld the first time, you then connect to +it as "root" and :command:`GRANT` permissions to other +users. (Again, the MySQL root account has nothing to do with +the \*NIX root account.) + +.. note:: You will need to start the daemons yourself. You can either + ask your system administrator to add them to system startup files, or + add a crontab entry that runs a script to check on these daemons + and restart them if needed. + +.. warning:: Do NOT run daemons or other services on a server without first + consulting your system administrator! Daemons use up system resources + and running one may be in violation of your terms of service for any + machine on which you are a user! + +Perl +==== + +On the extremely rare chance that you don't have Perl on +the machine, you will have to build the sources +yourself. The following commands should get your system +installed with your own personal version of Perl: + +:: + + bash$ wget http://perl.org/CPAN/src/stable.tar.gz + bash$ tar zvxf stable.tar.gz + bash$ cd perl-|min-perl-ver| + bash$ sh Configure -de -Dprefix=/home/foo/perl + bash$ make && make test && make install + +Once you have Perl installed into a directory (probably +in :file:`~/perl/bin`), you will need to +install the Perl Modules, described below. + +.. _install-perlmodules-nonroot: + +Perl Modules +============ + +Installing the Perl modules as a non-root user is accomplished by +running the :file:`install-module.pl` +script. For more details on this script, see the +`install-module.pl documentation <../html/api/install-module.html>`_. + +HTTP Server +=========== + +Ideally, this also needs to be installed as root and +run under a special web server account. As long as +the web server will allow the running of \*.cgi files outside of a +cgi-bin, and a way of denying web access to certain files (such as a +.htaccess file), you should be good in this department. + +Running Apache as Non-Root +-------------------------- + +You can run Apache as a non-root user, but the port will need +to be set to one above 1024. If you type :command:`httpd -V`, +you will get a list of the variables that your system copy of httpd +uses. One of those, namely HTTPD_ROOT, tells you where that +installation looks for its config information. + +From there, you can copy the config files to your own home +directory to start editing. When you edit those and then use the -d +option to override the HTTPD_ROOT compiled into the web server, you +get control of your own customized web server. + +.. note:: You will need to start the daemons yourself. You can either + ask your system administrator to add them to system startup files, or + add a crontab entry that runs a script to check on these daemons + and restart them if needed. + +.. warning:: Do NOT run daemons or other services on a server without first + consulting your system administrator! Daemons use up system resources + and running one may be in violation of your terms of service for any + machine on which you are a user! + +Bugzilla +======== + +When you run :command:`./checksetup.pl` to create +the :file:`localconfig` file, it will list the Perl +modules it finds. If one is missing, go back and double-check the +module installation from :ref:`install-perlmodules-nonroot`, +then delete the :file:`localconfig` file and try again. + +.. warning:: One option in :file:`localconfig` you + might have problems with is the web server group. If you can't + successfully browse to the :file:`index.cgi` (like + a Forbidden error), you may have to relax your permissions, + and blank out the web server group. Of course, this may pose + as a security risk. Having a properly jailed shell and/or + limited access to shell accounts may lessen the security risk, + but use at your own risk. + +.. _suexec: + +suexec or shared hosting +------------------------ + +If you are running on a system that uses suexec (most shared +hosting environments do this), you will need to set the +*webservergroup* value in :file:`localconfig` +to match *your* primary group, rather than the one +the web server runs under. You will need to run the following +shell commands after running :command:`./checksetup.pl`, +every time you run it (or modify :file:`checksetup.pl` +to do them for you via the system() command). + +:: + + for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \\; ; done + for i in jpg gif css js png html rdf xul; do find . -name \\*.$i -exec chmod o+r {} \\; ; done + find . -name .htaccess -exec chmod o+r {} \\; + chmod o+x . data data/webdot + +Pay particular attention to the number of semicolons and dots. +They are all important. A future version of Bugzilla will +hopefully be able to do this for you out of the box. + +.. _upgrade: + +Upgrading to New Releases +######################### + +Upgrading to new Bugzilla releases is very simple. There is +a script named :file:`checksetup.pl` included with +Bugzilla that will automatically do all of the database migration +for you. + +The following sections explain how to upgrade from one +version of Bugzilla to another. Whether you are upgrading +from one bug-fix version to another (such as 4.2 to 4.2.1) +or from one major version to another (such as from 4.0 to 4.2), +the instructions are always the same. + +.. note:: Any examples in the following sections are written as though the + user were updating to version 4.2.1, but the procedures are the + same no matter what version you're updating to. Also, in the + examples, the user's Bugzilla installation is found + at :file:`/var/www/html/bugzilla`. If that is not the + same as the location of your Bugzilla installation, simply + substitute the proper paths where appropriate. + +.. _upgrade-before: + +Before You Upgrade +================== + +Before you start your upgrade, there are a few important +steps to take: + +#. Read the `Release + Notes `_ of the version you're upgrading to, + particularly the "Notes for Upgraders" section. + +#. View the Sanity Check (:ref:`sanitycheck`) page + on your installation before upgrading. Attempt to fix all warnings + that the page produces before you go any further, or you may + experience problems during your upgrade. + +#. Shut down your Bugzilla installation by putting some HTML or + text in the shutdownhtml parameter + (see :ref:`parameters`). + +#. Make a backup of the Bugzilla database. + *THIS IS VERY IMPORTANT*. If + anything goes wrong during the upgrade, your installation + can be corrupted beyond recovery. Having a backup keeps you safe. + + .. warning:: Upgrading is a one-way process. You cannot "downgrade" an + upgraded Bugzilla. If you wish to revert to the old Bugzilla + version for any reason, you will have to restore your database + from this backup. + + Here are some sample commands you could use to backup + your database, depending on what database system you're + using. You may have to modify these commands for your + particular setup. + + MySQL: + mysqldump --opt -u bugs -p bugs > bugs.sql + PostgreSQL: + pg_dump --no-privileges --no-owner -h localhost -U bugs + > bugs.sql + +.. _upgrade-files: + +Getting The New Bugzilla +======================== + +There are three ways to get the new version of Bugzilla. +We'll list them here briefly and then explain them +more later. + +Bzr (:ref:`upgrade-bzr`) + If you have :command:`bzr` installed on your machine + and you have Internet access, this is the easiest way to + upgrade, particularly if you have made modifications + to the code or templates of Bugzilla. + +Download the tarball (:ref:`upgrade-tarball`) + This is a very simple way to upgrade, and good if you + haven't made many (or any) modifications to the code or + templates of your Bugzilla. + +Patches (:ref:`upgrade-patches`) + If you have made modifications to your Bugzilla, and + you don't have Internet access or you don't want to use + bzr, then this is the best way to upgrade. + You can only do minor upgrades (such as 4.2 to 4.2.1 or + 4.2.1 to 4.2.2) with patches. + +.. _upgrade-modified: + +If you have modified your Bugzilla +---------------------------------- + +If you have modified the code or templates of your Bugzilla, +then upgrading requires a bit more thought and effort. +A discussion of the various methods of updating compared with +degree and methods of local customization can be found in +:ref:`template-method`. + +The larger the jump you are trying to make, the more difficult it +is going to be to upgrade if you have made local customizations. +Upgrading from 4.2 to 4.2.1 should be fairly painless even if +you are heavily customized, but going from 2.18 to 4.2 is going +to mean a fair bit of work re-writing your local changes to use +the new files, logic, templates, etc. If you have done no local +changes at all, however, then upgrading should be approximately +the same amount of work regardless of how long it has been since +your version was released. + +.. _upgrade-bzr: + +Upgrading using Bzr +------------------- + +This requires that you have bzr installed (most Unix machines do), +and requires that you are able to access +`bzr.mozilla.org `_, +which may not be an option if you don't have Internet access. + +The following shows the sequence of commands needed to update a +Bugzilla installation via Bzr, and a typical series of results. +These commands assume that you already have Bugzilla installed +using Bzr. + +.. warning:: If your installation is still using CVS, you must first convert + it to Bzr. A very detailed step by step documentation can be + found on `wiki.mozilla.org `_. + +:: + + bash$ cd /var/www/html/bugzilla + bash$ bzr switch 4.2 + (only run the previous command when not yet running 4.2) + bash$ bzr up -r tag:bugzilla-4.2.1 + +N extensions/MoreBugUrl/ + +N extensions/MoreBugUrl/Config.pm + +N extensions/MoreBugUrl/Extension.pm + ... + M Bugzilla/Attachment.pm + M Bugzilla/Attachment/PatchReader.pm + M Bugzilla/Bug.pm + ... + All changes applied successfully. + +.. caution:: If a line in the output from :command:`bzr up` mentions + a conflict, then that represents a file with local changes that + Bzr 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. + +.. _upgrade-tarball: + +Upgrading using the tarball +--------------------------- + +If you are unable (or unwilling) to use Bzr, another option that's +always available is to obtain the latest tarball from the `Download Page `_ and +create a new Bugzilla installation from that. + +This sequence of commands shows how to get the tarball from the +command-line; it is also possible to download it from the site +directly in a web browser. If you go that route, save the file +to the :file:`/var/www/html` +directory (or its equivalent, if you use something else) and +omit the first three lines of the example. + +:: + + bash$ cd /var/www/html + bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz + ... + bash$ tar xzvf bugzilla-4.2.1.tar.gz + bugzilla-4.2.1/ + bugzilla-4.2.1/colchange.cgi + ... + bash$ cd bugzilla-4.2.1 + bash$ cp ../bugzilla/localconfig* . + bash$ cp -r ../bugzilla/data . + bash$ cd .. + bash$ mv bugzilla bugzilla.old + bash$ mv bugzilla-4.2.1 bugzilla + +.. warning:: The :command:`cp` commands both end with periods which + is a very important detail--it means that the destination + directory is the current working directory. + +.. caution:: If you have some extensions installed, you will have to copy them + to the new bugzilla directory too. Extensions are located in :file:`bugzilla/extensions/`. + Only copy those you + installed, not those managed by the Bugzilla team. + +This upgrade method will give you a clean install of Bugzilla. +That's fine if you don't have any local customizations that you +want to maintain. If you do have customizations, then you will +need to reapply them by hand to the appropriate files. + +.. _upgrade-patches: + +Upgrading using patches +----------------------- + +A patch is a collection of all the bug fixes that have been made +since the last bug-fix release. + +If you are doing a bug-fix upgrade—that is, one where only the +last number of the revision changes, such as from 4.2 to +4.2.1—then you have the option of obtaining and applying a +patch file from the `Download Page `_. + +As above, this example starts with obtaining the file via the +command line. If you have already downloaded it, you can omit the +first two commands. + +:: + + bash$ cd /var/www/html/bugzilla + bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2-to-4.2.1.diff.gz + ... + bash$ gunzip bugzilla-4.2-to-4.2.1.diff.gz + bash$ patch -p1 < bugzilla-4.2-to-4.2.1.diff + patching file Bugzilla/Constants.pm + patching file enter_bug.cgi + ... + +.. warning:: Be aware that upgrading from a patch file does not change the + entries in your :file:`.bzr` directory. + This could make it more difficult to upgrade using Bzr + (:ref:`upgrade-bzr`) in the future. + +.. _upgrade-completion: + +Completing Your Upgrade +======================= + +Now that you have the new Bugzilla code, there are a few final +steps to complete your upgrade. + +#. If your new Bugzilla installation is in a different + directory or on a different machine than your old Bugzilla + installation, make sure that you have copied the + :file:`data` directory and the + :file:`localconfig` file from your old Bugzilla + installation. (If you followed the tarball instructions + above, this has already happened.) + +#. If this is a major update, check that the configuration + (:ref:`configuration`) for your new Bugzilla is + up-to-date. Sometimes the configuration requirements change + between major versions. + +#. If you didn't do it as part of the above configuration step, + now you need to run :command:`checksetup.pl`, which + will do everything required to convert your existing database + and settings for the new version: + + :: + bash$ :command:`cd /var/www/html/bugzilla` + bash$ :command:`./checksetup.pl` + + .. warning:: The period at the beginning of the + command :command:`./checksetup.pl` is important and cannot + be omitted. + + .. caution:: If this is a major upgrade (say, 3.6 to 4.2 or similar), + running :command:`checksetup.pl` on a large + installation (75,000 or more bugs) can take a long time, + possibly several hours. + +#. Clear any HTML or text that you put into the shutdownhtml + parameter, to re-activate Bugzilla. + +#. View the Sanity Check (:ref:`sanitycheck`) page in your + upgraded Bugzilla. + It is recommended that, if possible, you fix any problems + you see, immediately. Failure to do this may mean that Bugzilla + will not work correctly. Be aware that if the sanity check page + contains more errors after an upgrade, it doesn't necessarily + mean there are more errors in your database than there were + before, as additional tests are added to the sanity check over + time, and it is possible that those errors weren't being + checked for in the old version. + +.. _upgrade-notifications: + +Automatic Notifications of New Releases +======================================= + +Bugzilla 3.0 introduced the ability to automatically notify +administrators when new releases are available, based on the +``upgrade_notification`` parameter, see +:ref:`parameters`. Administrators will see these +notifications when they access the :file:`index.cgi` +page, i.e. generally when logging in. Bugzilla will check once per +day for new releases, unless the parameter is set to +``disabled``. If you are behind a proxy, you may have to set +the ``proxy_url`` parameter accordingly. If the proxy +requires authentication, use the +``http://user:pass@proxy_url/`` syntax. + + diff --git a/docs/en/rst/modules.rst b/docs/en/rst/modules.rst new file mode 100644 index 000000000..2dced86bc --- /dev/null +++ b/docs/en/rst/modules.rst @@ -0,0 +1,158 @@ + + +.. _install-perlmodules-manual: + +=================================== +Manual Installation of Perl Modules +=================================== + +.. _modules-manual-instructions: + +Instructions +############ + +If you need to install Perl modules manually, here's how it's done. +Download the module using the link given in the next section, and then +apply this magic incantation, as root: + +:: + + bash# tar -xzvf .tar.gz + bash# cd + bash# perl Makefile.PL + bash# make + bash# make test + bash# make install + +.. note:: In order to compile source code under Windows you will need to obtain + a 'make' utility. The :command:`nmake` utility provided with + Microsoft Visual C++ may be used. As an alternative, there is a + utility called :command:`dmake` available from CPAN which is + written entirely in Perl. + As described in :ref:`modules-manual-download`, however, most + packages already exist and are available from ActiveState or theory58S. + We highly recommend that you install them using the ppm GUI available with + ActiveState and to add the theory58S repository to your list of repositories. + +.. _modules-manual-download: + +Download Locations +################## + +.. note:: Running Bugzilla on Windows requires the use of ActiveState + Perl |min-perl-ver| or higher. Many modules already exist in the core + distribution of ActiveState Perl. Additional modules can be downloaded + from ``_ + if you use Perl |min-perl-ver|. + +CGI: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +Data-Dumper: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +Date::Format (part of TimeDate): + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +DBI: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +DBD::mysql: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +DBD::Pg: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +Template-Toolkit: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +GD: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +Template::Plugin::GD: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +MIME::Parser (part of MIME-tools): + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +.. _modules-manual-optional: + +Optional Modules +################ + +Chart::Lines: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +GD::Graph: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +GD::Text::Align (part of GD::Text::Util): + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +XML::Twig: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + +PatchReader: + +:: + + CPAN Download Page: ``_ + Documentation: ``_ + + diff --git a/docs/en/rst/patches.rst b/docs/en/rst/patches.rst new file mode 100644 index 000000000..688d17105 --- /dev/null +++ b/docs/en/rst/patches.rst @@ -0,0 +1,88 @@ + + +.. _patches: + +======= +Contrib +======= + +There are a number of unofficial Bugzilla add-ons in the +:file:`$BUGZILLA_ROOT/contrib/` +directory. This section documents them. + +.. _cmdline: + +Command-line Search Interface +############################# + +There are a suite of Unix utilities for searching Bugzilla from the +command line. They live in the +:file:`contrib/cmdline` directory. +There are three files - :file:`query.conf`, +:file:`buglist` and :file:`bugs`. + +.. warning:: These files pre-date the templatization work done as part of the + 2.16 release, and have not been updated. + +:file:`query.conf` 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``. + +:file:`buglist` is a shell script that 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=``. + +The column list is taken from the COLUMNLIST environment variable. +This is equivalent to the ``Change Columns`` option +that is available when you list bugs in buglist.cgi. If you have +already used Bugzilla, grep for COLUMNLIST in your cookies file +to see your current COLUMNLIST setting. + +:file:`bugs` is a simple shell script which calls +:file:`buglist` and extracts the +bug numbers from the output. Adding the prefix +``http://bugzilla.mozilla.org/buglist.cgi?bug_id=`` +turns the bug list into a working link if any bugs are found. +Counting bugs is easy. Pipe the results through +:command:`sed -e 's/,/ /g' | wc | awk '{printf $2 "\\n"}'` + +Akkana Peck says she has good results piping +:file:`buglist` output through +:command:`w3m -T text/html -dump` + +.. _cmdline-bugmail: + +Command-line 'Send Unsent Bug-mail' tool +######################################## + +Within the :file:`contrib` directory +exists a utility with the descriptive (if compact) name +of :file:`sendunsentbugmail.pl`. The purpose of this +script is, simply, to send out any bug-related mail that should +have been sent by now, but for one reason or another has not. + +To accomplish this task, :file:`sendunsentbugmail.pl` uses +the same mechanism as the :file:`sanitycheck.cgi` script; +it scans through the entire database looking for bugs with changes that +were made more than 30 minutes ago, but where there is no record of +anyone related to that bug having been sent mail. Having compiled a list, +it then uses the standard rules to determine who gets mail, and sends it +out. + +As the script runs, it indicates the bug for which it is currently +sending mail; when it has finished, it gives a numerical count of how +many mails were sent and how many people were excluded. (Individual +user names are not recorded or displayed.) If the script produces +no output, that means no unsent mail was detected. + +*Usage*: move the sendunsentbugmail.pl script +up into the main directory, ensure it has execute permission, and run it +from the command line (or from a cron job) with no parameters. + + diff --git a/docs/en/rst/security.rst b/docs/en/rst/security.rst new file mode 100644 index 000000000..4813ffe76 --- /dev/null +++ b/docs/en/rst/security.rst @@ -0,0 +1,167 @@ + + +.. _security: + +================= +Bugzilla Security +================= + +While some of the items in this chapter are related to the operating +system Bugzilla is running on or some of the support software required to +run Bugzilla, it is all related to protecting your data. This is not +intended to be a comprehensive guide to securing Linux, Apache, MySQL, or +any other piece of software mentioned. There is no substitute for active +administration and monitoring of a machine. The key to good security is +actually right in the middle of the word: *U R It*. + +While programmers in general always strive to write secure code, +accidents can and do happen. The best approach to security is to always +assume that the program you are working with isn't 100% secure and restrict +its access to other parts of your machine as much as possible. + +.. _security-os: + +Operating System +################ + +.. _security-os-ports: + +TCP/IP Ports +============ + +.. COMMENT: TODO: Get exact number of ports + +The TCP/IP standard defines more than 65,000 ports for sending +and receiving traffic. Of those, Bugzilla needs exactly one to operate +(different configurations and options may require up to 3). You should +audit your server and make sure that you aren't listening on any ports +you don't need to be. It's also highly recommended that the server +Bugzilla resides on, along with any other machines you administer, be +placed behind some kind of firewall. + +.. _security-os-accounts: + +System User Accounts +==================== + +Many daemons, such +as Apache's :file:`httpd` or MySQL's +:file:`mysqld`, run as either ``root`` or +``nobody``. This is even worse on Windows machines where the +majority of services +run as ``SYSTEM``. While running as ``root`` or +``SYSTEM`` introduces obvious security concerns, the +problems introduced by running everything as ``nobody`` may +not be so obvious. Basically, if you run every daemon as +``nobody`` and one of them gets compromised it can +compromise every other daemon running as ``nobody`` on your +machine. For this reason, it is recommended that you create a user +account for each daemon. + +.. note:: You will need to set the ``webservergroup`` option + in :file:`localconfig` to the group your web server runs + as. This will allow :file:`./checksetup.pl` to set file + permissions on Unix systems so that nothing is world-writable. + +.. _security-os-chroot: + +The :file:`chroot` Jail +======================= + +If your system supports it, you may wish to consider running +Bugzilla inside of a :file:`chroot` jail. This option +provides unprecedented security by restricting anything running +inside the jail from accessing any information outside of it. If you +wish to use this option, please consult the documentation that came +with your system. + +.. _security-webserver: + +Web server +########## + +.. _security-webserver-access: + +Disabling Remote Access to Bugzilla Configuration Files +======================================================= + +There are many files that are placed in the Bugzilla directory +area that should not be accessible from the web server. Because of the way +Bugzilla is currently layed out, the list of what should and should not +be accessible is rather complicated. A quick way is to run +:file:`testserver.pl` to check if your web server serves +Bugzilla files as expected. If not, you may want to follow the few +steps below. + +.. tip:: Bugzilla ships with the ability to create :file:`.htaccess` + files that enforce these rules. Instructions for enabling these + directives in Apache can be found in :ref:`http-apache` + +- In the main Bugzilla directory, you should: + - Block: :file:`*.pl`, :file:`*localconfig*` + +- In :file:`data`: + - Block everything + +- In :file:`data/webdot`: + + - If you use a remote webdot server: + + - Block everything + - But allow :file:`*.dot` + only for the remote webdot server + - Otherwise, if you use a local GraphViz: + + - Block everything + - But allow: :file:`*.png`, :file:`*.gif`, :file:`*.jpg`, :file:`*.map` + - And if you don't use any dot: + + - Block everything + +- In :file:`Bugzilla`: + - Block everything + +- In :file:`template`: + - Block everything + +Be sure to test that data that should not be accessed remotely is +properly blocked. Of particular interest is the localconfig file which +contains your database password. Also, be aware that many editors +create temporary and backup files in the working directory and that +those should also not be accessible. For more information, see +`bug 186383 `_ +or +`Bugtraq ID 6501 `_. +To test, simply run :file:`testserver.pl`, as said above. + +.. tip:: Be sure to check :ref:`http` for instructions + specific to the web server you use. + +.. _security-bugzilla: + +Bugzilla +######## + +.. _security-bugzilla-charset: + +Prevent users injecting malicious Javascript +============================================ + +If you installed Bugzilla version 2.22 or later from scratch, +then the *utf8* parameter is switched on by default. +This makes Bugzilla explicitly set the character encoding, following +`a +CERT advisory `_ recommending exactly this. +The following therefore does not apply to you; just keep +*utf8* turned on. + +If you've upgraded from an older version, then it may be possible +for a Bugzilla user to take advantage of character set encoding +ambiguities to inject HTML into Bugzilla comments. +This could include malicious scripts. +This is because due to internationalization concerns, we are unable to +turn the *utf8* parameter on by default for upgraded +installations. +Turning it on manually will prevent this problem. + + diff --git a/docs/en/rst/troubleshooting.rst b/docs/en/rst/troubleshooting.rst new file mode 100644 index 000000000..26899bc57 --- /dev/null +++ b/docs/en/rst/troubleshooting.rst @@ -0,0 +1,235 @@ + + +.. _troubleshooting: + +=============== +Troubleshooting +=============== + +This section gives solutions to common Bugzilla installation +problems. If none of the section headings seems to match your +problem, read the general advice. + +.. _general-advice: + +General Advice +############## + +If you can't get :file:`checksetup.pl` to run to +completion, it normally explains what's wrong and how to fix it. +If you can't work it out, or if it's being uncommunicative, post +the errors in the +`mozilla.support.bugzilla `_ +newsgroup. + +If you have made it all the way through +:ref:`installation` (Installation) and +:ref:`configuration` (Configuration) but accessing the Bugzilla +URL doesn't work, the first thing to do is to check your web server error +log. For Apache, this is often located at +:file:`/etc/logs/httpd/error_log`. The error messages +you see may be self-explanatory enough to enable you to diagnose and +fix the problem. If not, see below for some commonly-encountered +errors. If that doesn't help, post the errors to the newsgroup. + +Bugzilla can also log all user-based errors (and many code-based errors) +that occur, without polluting the web server's error log. To enable +Bugzilla error logging, create a file that Bugzilla can write to, named +:file:`errorlog`, in the Bugzilla :file:`data` +directory. Errors will be logged as they occur, and will include the type +of the error, the IP address and username (if available) of the user who +triggered the error, and the values of all environment variables; if a +form was being submitted, the data in the form will also be included. +To disable error logging, delete or rename the +:file:`errorlog` file. + +.. _trbl-testserver: + +The Apache web server is not serving Bugzilla pages +################################################### + +After you have run :command:`checksetup.pl` twice, +run :command:`testserver.pl http://yoursite.yourdomain/yoururl` +to confirm that your web server is configured properly for +Bugzilla. + +:: + + bash$ ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip + TEST-OK Webserver is running under group id in $webservergroup. + TEST-OK Got ant picture. + TEST-OK Webserver is executing CGIs. + TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig. + +.. _trbl-perlmodule: + +I installed a Perl module, but :file:`checksetup.pl` claims it's not installed! +############################################################################### + +This could be caused by one of two things: + +#. You have two versions of Perl on your machine. You are installing + modules into one, and Bugzilla is using the other. Rerun the CPAN + commands (or manual compile) using the full path to Perl from the + top of :file:`checksetup.pl`. This will make sure you + are installing the modules in the right place. + +#. The permissions on your library directories are set incorrectly. + They must, at the very least, be readable by the web server user or + group. It is recommended that they be world readable. + +.. _trbl-dbdSponge: + +DBD::Sponge::db prepare failed +############################## + +The following error message may appear due to a bug in DBD::mysql +(over which the Bugzilla team have no control): + +:: + + 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) + +To fix this, go to +:file:`/lib/DBD/sponge.pm` +in your Perl installation and replace + +:: + + my $numFields; + if ($attribs->{'NUM_OF_FIELDS'}) { + $numFields = $attribs->{'NUM_OF_FIELDS'}; + } elsif ($attribs->{'NAME'}) { + $numFields = @{$attribs->{NAME}}; + +with + +:: + + my $numFields; + if ($attribs->{'NUM_OF_FIELDS'}) { + $numFields = $attribs->{'NUM_OF_FIELDS'}; + } elsif ($attribs->{'NAMES'}) { + $numFields = @{$attribs->{NAMES}}; + +(note the S added to NAME.) + +.. _paranoid-security: + +cannot chdir(/var/spool/mqueue) +############################### + +If you are installing Bugzilla on SuSE Linux, or some other +distributions with ``paranoid`` security options, it is +possible that the checksetup.pl script may fail with the error: +:: + + cannot chdir(/var/spool/mqueue): Permission denied + +This is because your :file:`/var/spool/mqueue` +directory has a mode of ``drwx------``. +Type :command:`chmod 755 :file:`/var/spool/mqueue`` +as root to fix this problem. This will allow any process running on your +machine the ability to *read* the +:file:`/var/spool/mqueue` directory. + +.. _trbl-relogin-everyone: + +Everybody is constantly being forced to relogin +############################################### + +The most-likely cause is that the ``cookiepath`` parameter +is not set correctly in the Bugzilla configuration. You can change this (if +you're a Bugzilla administrator) from the editparams.cgi page via the web interface. + +The value of the cookiepath parameter should be the actual directory +containing your Bugzilla installation, *as seen by the end-user's +web browser*. Leading and trailing slashes are mandatory. You can +also set the cookiepath to any directory which is a parent of the Bugzilla +directory (such as '/', the root directory). But you can't put something +that isn't at least a partial match or it won't work. What you're actually +doing is restricting the end-user's browser to sending the cookies back only +to that directory. + +How do you know if you want your specific Bugzilla directory or the +whole site? + +If you have only one Bugzilla running on the server, and you don't +mind having other applications on the same server with it being able to see +the cookies (you might be doing this on purpose if you have other things on +your site that share authentication with Bugzilla), then you'll want to have +the cookiepath set to "/", or to a sufficiently-high enough directory that +all of the involved apps can see the cookies. + +.. _trbl-relogin-everyone-share: + +Examples of urlbase/cookiepath pairs for sharing login cookies +============================================================== + +| urlbase is http://bugzilla.mozilla.org/ +| cookiepath is / + + +| urlbase is http://tools.mysite.tld/bugzilla/ +| but you have http://tools.mysite.tld/someotherapp/ which shares +| authentication with your Bugzilla +| +| cookiepath is / + +On the other hand, if you have more than one Bugzilla running on the +server (some people do - we do on landfill) then you need to have the +cookiepath restricted enough so that the different Bugzillas don't +confuse their cookies with one another. + +.. _trbl-relogin-everyone-restrict: + +Examples of urlbase/cookiepath pairs to restrict the login cookie +================================================================= + +| urlbase is http://landfill.bugzilla.org/bugzilla-tip/ +| cookiepath is /bugzilla-tip/ + +| urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/ +| cookiepath is /bugzilla-4.0-branch/ + +If you had cookiepath set to ``/`` at any point in the +past and need to set it to something more restrictive +(i.e. ``/bugzilla/``), you can safely do this without +requiring users to delete their Bugzilla-related cookies in their +browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5). + +.. _trbl-index: + +:file:`index.cgi` doesn't show up unless specified in the URL +############################################################# + +You probably need to set up your web server in such a way that it +will serve the index.cgi page as an index page. + +If you are using Apache, you can do this by adding +:file:`index.cgi` to the end of the +``DirectoryIndex`` line +as mentioned in :ref:`http-apache`. + +.. _trbl-passwd-encryption: + +checksetup.pl reports "Client does not support authentication protocol requested by server..." +############################################################################################## + +This error is occurring because you are using the new password +encryption that comes with MySQL 4.1, while your +:file:`DBD::mysql` module was compiled against an +older version of MySQL. If you recompile :file:`DBD::mysql` +against the current MySQL libraries (or just obtain a newer version +of this module) then the error may go away. + +If that does not fix the problem, or if you cannot recompile the +existing module (e.g. you're running Windows) and/or don't want to +replace it (e.g. you want to keep using a packaged version), then a +workaround is available from the MySQL docs: +``_ + + diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst new file mode 100644 index 000000000..e5a16bfcb --- /dev/null +++ b/docs/en/rst/using.rst @@ -0,0 +1,1375 @@ + + +.. _using: + +============== +Using Bugzilla +============== + +.. _using-intro: + +Introduction +############ + +This section contains information for end-users of Bugzilla. There +is a Bugzilla test installation, called +`Landfill `_, which you are +welcome to play with (if it's up). However, not all of the Bugzilla +installations there will necessarily have all Bugzilla features enabled, +and different installations run different versions, so some things may not +quite work as this document describes. + +Frequently Asked Questions (FAQ) are available and answered on +`wiki.mozilla.org `_. +They may cover some questions you have which are left unanswered. + +.. _myaccount: + +Create a Bugzilla Account +######################### + +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: +`<|landfillbase|>`_. + +#. On the home page :file:`index.cgi`, click the + ``Open a new Bugzilla account`` link, or the + ``New Account`` link available in the footer of pages. + Now enter your email address, then click the ``Send`` + button. + + .. note:: If none of these links is available, this means that the + administrator of the installation has disabled self-registration. + This means that only an administrator can create accounts + for other users. One reason could be that this installation is + private. + + .. note:: Also, if only some users are allowed to create an account on + the installation, you may see these links but your registration + may fail if your email address doesn't match the ones accepted + by the installation. This is another way to restrict who can + access and edit bugs in this installation. + +#. Within moments, and if your registration is accepted, you should + receive an email to the address you provided, which contains your + login name (generally the same as the email address), and two URLs + with a token (a random string generated by the installation) to + confirm, respectively cancel, your registration. This is a way to + prevent users from abusing the generation of user accounts, for + instance by entering inexistent email addresses, or email addresses + which do not belong to them. + +#. By default, you have 3 days to confirm your registration. Past this + timeframe, the token is invalidated and the registration is + automatically canceled. You can also cancel this registration sooner + by using the appropriate URL in the email you got. + +#. If you confirm your registration, Bugzilla will ask you your real name + (optional, but recommended) and your password, which must be between + 3 and 16 characters long. + +#. Now all you need to do is to click the ``Log In`` + link in the footer at the bottom of the page in your browser, + enter your email address and password you just chose into the + login form, and click the ``Log in`` button. + +You are now logged in. Bugzilla uses cookies to remember you are +logged in so, unless you have cookies disabled or your IP address changes, +you should not have to log in again during your session. + +.. _bug_page: + +Anatomy of a Bug +################ + +The core of Bugzilla is the screen which displays a particular +bug. It's a good place to explain some Bugzilla concepts. +`Bug 1 on Landfill <|landfillbase|show_bug.cgi?id=1>`_ +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. + +#. *Product and Component*: + 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: + + Administration: + Administration of a Bugzilla installation. + Bugzilla-General: + Anything that doesn't fit in the other components, or spans + multiple components. + Creating/Changing Bugs: + Creating, changing, and viewing bugs. + Documentation: + The Bugzilla documentation, including The Bugzilla Guide. + Email: + Anything to do with email sent by Bugzilla. + Installation: + The installation process of Bugzilla. + Query/Buglist: + Anything to do with searching for bugs and viewing the + buglists. + Reporting/Charting: + Getting reports from Bugzilla. + User Accounts: + Anything about managing a user account from the user's perspective. + Saved queries, creating accounts, changing passwords, logging in, + etc. + User Interface: + General issues having to do with the user interface cosmetics (not + functionality) including cosmetic issues, HTML templates, + etc. + +#. *Status and Resolution:* + 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. + +#. *Assigned To:* + The person responsible for fixing the bug. + +#. *\*QA Contact:* + The person responsible for quality assurance on this bug. + +#. *\*URL:* + A URL associated with the bug, if any. + +#. *Summary:* + A one-sentence summary of the problem. + +#. *\*Status Whiteboard:* + (a.k.a. Whiteboard) A free-form text area for adding short notes + and tags to a bug. + +#. *\*Keywords:* + 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. + +#. *Platform and OS:* + These indicate the computing environment where the bug was + found. + +#. *Version:* + 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. + +#. *Priority:* + The bug assignee uses this field to prioritize his or her bugs. + It's a good idea not to change this on other people's bugs. + +#. *Severity:* + 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. + +#. *\*Target:* + (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. + +#. *Reporter:* + The person who filed the bug. + +#. *CC list:* + A list of people who get mail when the bug changes. + +#. *\*Time Tracking:* + This form can be used for time tracking. + To use this feature, you have to be blessed group membership + specified by the ``timetrackinggroup`` parameter. + + Orig. Est.: + This field shows the original estimated time. + Current Est.: + This field shows the current estimated time. + This number is calculated from ``Hours Worked`` + and ``Hours Left``. + Hours Worked: + This field shows the number of hours worked. + Hours Left: + This field shows the ``Current Est.`` - + ``Hours Worked``. + This value + ``Hours Worked`` will become the + new Current Est. + %Complete: + This field shows what percentage of the task is complete. + Gain: + This field shows the number of hours that the bug is ahead of the + ``Orig. Est.``. + Deadline: + This field shows the deadline for this bug. + +#. *Attachments:* + You can attach files (e.g. testcases or patches) to bugs. If there + are any attachments, they are listed in this section. + +#. *\*Dependencies:* + 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. + +#. *\*Votes:* + Whether this bug has any votes. + +#. *Additional Comments:* + You can add your two cents to the bug discussion here, if you have + something worthwhile to say. + +.. _lifecycle: + +Life Cycle of a Bug +################### + +The life cycle of a bug, also known as workflow, is customizable to match +the needs of your organization, see :ref:`bug_status_workflow`. +:ref:`lifecycle-image` contains a graphical representation of +the default workflow using the default bug statuses. If you wish to +customize this image for your site, the +`diagram file <../images/bzLifecycle.xml>`_ +is available in `Dia's `_ +native XML format. + +.. _lifecycle-image: + +Lifecycle of a Bugzilla Bug +=========================== + +.. image:: ../images/bzLifecycle.png + +.. _query: + +Searching for Bugs +################## + +The Bugzilla Search page is the interface where you can find +any bug report, comment, or patch currently in the Bugzilla system. You +can play with it here: +`<|landfillbase|query.cgi>`_. + +The Search page has controls for selecting different possible +values for all of the fields in a bug, as described above. For some +fields, multiple values can be selected. In those cases, Bugzilla +returns bugs where the content of the field matches any one of the selected +values. If none is selected, then the field can take any value. + +After a search is run, you can save it as a Saved Search, which +will appear in the page footer. If you are in the group defined +by the "querysharegroup" parameter, you may share your queries +with other users, see :ref:`savedsearches` for more details. + +.. _boolean: + +Boolean Charts +============== + +Highly advanced querying is done using Boolean Charts. + +The boolean charts further restrict the set of results +returned by a query. It is possible to search for bugs +based on elaborate combinations of criteria. + +The simplest boolean searches have only one term. These searches +permit the selected left *field* +to be compared using a +selectable *operator* to a +specified *value.* +Using the "And," "Or," and "Add Another Boolean Chart" buttons, +additional terms can be included in the query, further +altering the list of bugs returned by the query. + +There are three fields in each row of a boolean search. + +- *Field:* + the items being searched + +- *Operator:* + the comparison operator + +- *Value:* + the value to which the field is being compared + +.. _pronouns: + +Pronoun Substitution +-------------------- + +Sometimes, a query needs to compare a user-related field +(such as ReportedBy) with a role-specific user (such as the +user running the query or the user to whom each bug is assigned). +When the operator is either "equals" or "notequals", the value +can be "%reporter%", "%assignee%", "%qacontact%", or "%user%". +The user pronoun +refers to the user who is executing the query or, in the case +of whining reports, the user who will be the recipient +of the report. The reporter, assignee, and qacontact +pronouns refer to the corresponding fields in the bug. + +Boolean charts also let you type a group name in any user-related +field if the operator is either "equals", "notequals" or "anyexact". +This will let you query for any member belonging (or not) to the +specified group. The group name must be entered following the +"%group.foo%" syntax, where "foo" is the group name. +So if you are looking for bugs reported by any user being in the +"editbugs" group, then you can type "%group.editbugs%". + +.. _negation: + +Negation +-------- + +At first glance, negation seems redundant. Rather than +searching for + + NOT("summary" "contains the string" "foo"), + +one could search for + + ("summary" "does not contain the string" "foo"). + +However, the search + + ("CC" "does not contain the string" "@mozilla.org") + +would find every bug where anyone on the CC list did not contain +"@mozilla.org" while + + NOT("CC" "contains the string" "@mozilla.org") + +would find every bug where there was nobody on the CC list who +did contain the string. Similarly, the use of negation also permits +complex expressions to be built using terms OR'd together and then +negated. Negation permits queries such as + + NOT(("product" "equals" "update") OR + ("component" "equals" "Documentation")) + +to find bugs that are neither +in the update product or in the documentation component or + + NOT(("commenter" "equals" "%assignee%") OR + ("component" "equals" "Documentation")) + +to find non-documentation +bugs on which the assignee has never commented. + +.. _multiplecharts: + +Multiple Charts +--------------- + +The terms within a single row of a boolean chart are all +constraints on a single piece of data. If you are looking for +a bug that has two different people cc'd on it, then you need +to use two boolean charts. A search for + + ("cc" "contains the string" "foo@") AND + ("cc" "contains the string" "@mozilla.org") + +would return only bugs with "foo@mozilla.org" on the cc list. +If you wanted bugs where there is someone on the cc list +containing "foo@" and someone else containing "@mozilla.org", +then you would need two boolean charts. + + First chart: ("cc" "contains the string" "foo@") + Second chart: ("cc" "contains the string" "@mozilla.org") + +The bugs listed will be only the bugs where ALL the charts are true. + +.. _quicksearch: + +Quicksearch +=========== + +Quicksearch is a single-text-box query tool which uses +metacharacters to indicate what is to be searched. For example, typing +"``foo|bar``" +into Quicksearch would search for "foo" or "bar" in the +summary and status whiteboard of a bug; adding +"``:BazProduct``" would +search only in that product. +You can use it to find a bug by its number or its alias, too. + +You'll find the Quicksearch box in Bugzilla's footer area. +On Bugzilla's front page, there is an additional +`Help <../../page.cgi?id=quicksearch.html>`_ +link which details how to use it. + +.. _casesensitivity: + +Case Sensitivity in Searches +============================ + +Bugzilla queries are case-insensitive and accent-insensitive, when +used with either MySQL or Oracle databases. When using Bugzilla with +PostgreSQL, however, some queries are case-sensitive. This is due to +the way PostgreSQL handles case and accent sensitivity. + +.. _list: + +Bug Lists +========= + +If you run a search, a list of matching bugs will be returned. + +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: + +Long Format: + this gives you a large page with a non-editable summary of the fields + of each bug. + +XML: + get the buglist in the XML format. + +CSV: + get the buglist as comma-separated values, for import into e.g. + a spreadsheet. + +Feed: + get the buglist as an Atom feed. Copy this link into your + favorite feed reader. If you are using Firefox, you can also + save the list as a live bookmark by clicking the live bookmark + icon in the status bar. To limit the number of bugs in the feed, + add a limit=n parameter to the URL. + +iCalendar: + Get the buglist as an iCalendar file. Each bug is represented as a + to-do item in the imported calendar. + +Change Columns: + change the bug attributes which appear in the list. + +Change several bugs at once: + If your account is sufficiently empowered, and more than one bug + appear in the bug list, this link is displayed which lets you make + the same change to all the bugs in the list - for example, changing + their assignee. + +Send mail to bug assignees: + If more than one bug appear in the bug list and there are at least + two distinct bug assignees, this links is displayed which lets you + easily send a mail to the assignees of all bugs on the list. + +Edit Search: + 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. + +Remember Search As: + You can give a search a name and remember it; a link will appear + in your page footer giving you quick access to run it again later. + +.. _individual-buglists: + +Adding/removing tags to/from bugs +================================= + +You can add and remove tags from individual bugs, which let you find and +manage bugs more easily. Tags are per-user and so are only visible and editable +by the user who created them. You can then run queries using tags as a criteria, +either by using the Advanced Search form, or simply by typing "tag:my_tag_name" +in the QuickSearch box at the top (or bottom) of the page. Tags can also be +displayed in buglists. + +This feature is useful when you want to keep track of several bugs, but +for different reasons. Instead of adding yourself to the CC list of all +these bugs and mixing all these reasons, you can now store these bugs in +separate lists, e.g. ``Keep in mind``, ``Interesting bugs``, +or ``Triage``. One big advantage of this way to manage bugs +is that you can easily add or remove tags from bugs one by one. + +.. _bugreports: + +Filing Bugs +########### + +.. _fillingbugs: + +Reporting a New Bug +=================== + +Years of bug writing experience has been distilled for your +reading pleasure into the +`Bug Writing Guidelines <|landfillbase|page.cgi?id=bug-writing.html>`_. +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. + +The procedure for filing a bug is as follows: + +#. Click the ``New`` link available in the footer + of pages, or the ``Enter a new bug report`` link + displayed on the home page of the Bugzilla installation. + + .. note:: If you want to file a test bug to see how Bugzilla works, + you can do it on one of our test installations on + `the Landfill server <|landfillbase|>`_. + +#. You first have to select the product in which you found a bug. + +#. You now see a form where you can specify the component (part of + the product which is affected by the bug you discovered; if you have + no idea, just select ``General`` if such a component exists), + the version of the program you were using, the Operating System and + platform your program is running on and the severity of the bug (if the + bug you found crashes the program, it's probably a major or a critical + bug; if it's a typo somewhere, that's something pretty minor; if it's + something you would like to see implemented, then that's an enhancement). + +#. You now have to give a short but descriptive summary of the bug you found. + ``My program is crashing all the time`` is a very poor summary + and doesn't help developers at all. Try something more meaningful or + your bug will probably be ignored due to a lack of precision. + The next step is to give a very detailed list of steps to reproduce + the problem you encountered. Try to limit these steps to a minimum set + required to reproduce the problem. This will make the life of + developers easier, and the probability that they consider your bug in + a reasonable timeframe will be much higher. + + .. note:: Try to make sure that everything in the summary is also in the first + comment. Summaries are often updated and this will ensure your original + information is easily accessible. + +#. As you file the bug, you can also attach a document (testcase, patch, + or screenshot of the problem). + +#. Depending on the Bugzilla installation you are using and the product in + which you are filing the bug, you can also request developers to consider + your bug in different ways (such as requesting review for the patch you + just attached, requesting your bug to block the next release of the + product, and many other product specific requests). + +#. Now is a good time to read your bug report again. Remove all misspellings, + otherwise your bug may not be found by developers running queries for some + specific words, and so your bug would not get any attention. + Also make sure you didn't forget any important information developers + should know in order to reproduce the problem, and make sure your + description of the problem is explicit and clear enough. + When you think your bug report is ready to go, the last step is to + click the ``Commit`` button to add your report into the database. + +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. + +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. + +.. _cloningbugs: + +Clone an Existing Bug +===================== + +Starting with version 2.20, Bugzilla has a feature that allows you +to clone an existing bug. The newly created bug will inherit +most settings from the old bug. This allows you to track more +easily similar concerns in a new bug. To use this, go to the bug +that you want to clone, then click the ``Clone This Bug`` +link on the bug page. This will take you to the ``Enter Bug`` +page that is filled with the values that the old bug has. +You can change those values and/or texts if needed. + +.. _attachments: + +Attachments +########### + +You should use attachments, rather than comments, for large chunks of ASCII +data, such as trace, debugging output files, or log files. That way, it +doesn't bloat the bug for everyone who wants to read it, and cause people to +receive fat, useless mails. + +You should make sure to trim screenshots. There's no need to show the +whole screen if you are pointing out a single-pixel problem. + +Bugzilla stores and uses a Content-Type for each attachment +(e.g. text/html). To download an attachment as a different +Content-Type (e.g. application/xhtml+xml), you can override this +using a 'content_type' parameter on the URL, e.g. +:file:`&content_type=text/plain`. + +Also, you can enter the URL pointing to the attachment instead of +uploading the attachment itself. For example, this is useful if you want to +point to an external application, a website or a very large file. Note that +there is no guarantee that the source file will always be available, nor +that its content will remain unchanged. + +Another way to attach data is to paste text directly in the text field, +and Bugzilla will convert it into an attachment. This is pretty useful +when you do copy and paste, and you don't want to put the text in a temporary +file first. + +.. _patchviewer: + +Patch Viewer +============ + +Viewing and reviewing patches in Bugzilla is often difficult due to +lack of context, improper format and the inherent readability issues that +raw patches present. Patch Viewer is an enhancement to Bugzilla designed +to fix that by offering increased context, linking to sections, and +integrating with Bonsai, LXR and CVS. + +Patch viewer allows you to: + ++ View patches in color, with side-by-side view rather than trying + to interpret the contents of the patch. + ++ See the difference between two patches. + ++ Get more context in a patch. + ++ Collapse and expand sections of a patch for easy + reading. + ++ Link to a particular section of a patch for discussion or + review + ++ Go to Bonsai or LXR to see more context, blame, and + cross-references for the part of the patch you are looking at + ++ Create a rawtext unified format diff out of any patch, no + matter what format it came from + +.. _patchviewer_view: + +Viewing Patches in Patch Viewer +------------------------------- + +The main way to view a patch in patch viewer is to click on the +"Diff" link next to a patch in the Attachments list on a bug. You may +also do this within the edit window by clicking the "View Attachment As +Diff" button in the Edit Attachment screen. + +.. _patchviewer_diff: + +Seeing the Difference Between Two Patches +----------------------------------------- + +To see the difference between two patches, you must first view the +newer patch in Patch Viewer. Then select the older patch from the +dropdown at the top of the page ("Differences between \[dropdown] and +this patch") and click the "Diff" button. This will show you what +is new or changed in the newer patch. + +.. _patchviewer_context: + +Getting More Context in a Patch +------------------------------- + +To get more context in a patch, you put a number in the textbox at +the top of Patch Viewer ("Patch / File / \[textbox]") and hit enter. +This will give you that many lines of context before and after each +change. Alternatively, you can click on the "File" link there and it +will show each change in the full context of the file. This feature only +works against files that were diffed using "cvs diff". + +.. _patchviewer_collapse: + +Collapsing and Expanding Sections of a Patch +-------------------------------------------- + +To view only a certain set of files in a patch (for example, if a +patch is absolutely huge and you want to only review part of it at a +time), you can click the "(+)" and "(-)" links next to each file (to +expand it or collapse it). If you want to collapse all files or expand +all files, you can click the "Collapse All" and "Expand All" links at the +top of the page. + +.. _patchviewer_link: + +Linking to a Section of a Patch +------------------------------- + +To link to a section of a patch (for example, if you want to be +able to give someone a URL to show them which part you are talking +about) you simply click the "Link Here" link on the section header. The +resulting URL can be copied and used in discussion. + +.. _patchviewer_bonsai_lxr: + +Going to Bonsai and LXR +----------------------- + +To go to Bonsai to get blame for the lines you are interested in, +you can click the "Lines XX-YY" link on the section header you are +interested in. This works even if the patch is against an old +version of the file, since Bonsai stores all versions of the file. + +To go to LXR, you click on the filename on the file header +(unfortunately, since LXR only does the most recent version, line +numbers are likely to rot). + +.. _patchviewer_unified_diff: + +Creating a Unified Diff +----------------------- + +If the patch is not in a format that you like, you can turn it +into a unified diff format by clicking the "Raw Unified" link at the top +of the page. + +.. _hintsandtips: + +Hints and Tips +############## + +This section distills some Bugzilla tips and best practices +that have been developed. + +Autolinkification +================= + +Bugzilla comments are plain text - so typing will +produce less-than, U, greater-than rather than underlined text. +However, Bugzilla will automatically make hyperlinks out of certain +sorts of text in comments. For example, the text +"http://www.bugzilla.org" will be turned into a link: +``_. +Other strings which get linkified in the obvious manner are: + ++ bug 12345 + ++ comment 7 + ++ bug 23456, comment 53 + ++ attachment 4321 + ++ mailto:george@example.com + ++ george@example.com + ++ ftp://ftp.mozilla.org + ++ Most other sorts of URL + +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. + +.. _commenting: + +Comments +======== + +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. + +Don't use sigs in comments. Signing your name ("Bill") is acceptable, +if you do it out of habit, but full mail/news-style +four line ASCII art creations are not. + +.. _comment-wrapping: + +Server-Side Comment Wrapping +============================ + +Bugzilla stores comments unwrapped and wraps them at display time. This +ensures proper wrapping in all browsers. Lines beginning with the ">" +character are assumed to be quotes, and are not wrapped. + +.. _dependencytree: + +Dependency Tree +=============== + +On the ``Dependency tree`` page linked from each bug +page, you can see the dependency relationship from the bug as a +tree structure. + +You can change how much depth to show, and you can hide resolved bugs +from this page. You can also collaps/expand dependencies for +each bug on the tree view, using the \[-]/\[+] buttons that appear +before its summary. This option is not available for terminal +bugs in the tree (that don't have further dependencies). + +.. _timetracking: + +Time Tracking Information +######################### + +Users who belong to the group specified by the ``timetrackinggroup`` +parameter have access to time-related fields. Developers can see +deadlines and estimated times to fix bugs, and can provide time spent +on these bugs. Users who do not belong to this group can only see the deadline, +but not edit it. Other time-related fields remain invisible to them. + +At any time, a summary of the time spent by developers on bugs is +accessible either from bug lists when clicking the ``Time Summary`` +button or from individual bugs when clicking the ``Summarize time`` +link in the time tracking table. The :file:`summarize_time.cgi` +page lets you view this information either per developer or per bug, +and can be split on a month basis to have greater details on how time +is spent by developers. + +As soon as a bug is marked as RESOLVED, the remaining time expected +to fix the bug is set to zero. This lets QA people set it again for +their own usage, and it will be set to zero again when the bug will +be marked as CLOSED. + +.. _userpreferences: + +User Preferences +################ + +Once logged in, you can customize various aspects of +Bugzilla via the "Preferences" link in the page footer. +The preferences are split into five tabs: + +.. _generalpreferences: + +General Preferences +=================== + +This tab allows you to change several default settings of Bugzilla. + +- Bugzilla's general appearance (skin) - select which skin to use. + Bugzilla supports adding custom skins. + +- Quote the associated comment when you click on its reply link - sets + the behavior of the comment "Reply" link. Options include quoting the + full comment, just reference the comment number, or turn the link off. + +- Language used in email - select which language email will be sent in, + from the list of available languages. + +- After changing a bug - This controls what page is displayed after + changes to a bug are submitted. The options include to show the bug + just modified, to show the next bug in your list, or to do nothing. + +- Enable tags for bugs - turn bug tagging on or off. + +- Zoom textareas large when in use (requires JavaScript) - enable or + disable the automatic expanding of text areas when text is being + entered into them. + +- Field separator character for CSV files - + Select between a comma and semi-colon for exported CSV bug lists. + +- Automatically add me to the CC list of bugs I change - set default + behavior of CC list. Options include "Always", "Never", and "Only + if I have no role on them". + +- When viewing a bug, show comments in this order - + controls the order of comments. Options include "Oldest + to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the + bug description at the top". + +- Show a quip at the top of each bug list - controls + whether a quip will be shown on the Bug list page. + +.. _emailpreferences: + +Email Preferences +================= + +This tab allows you to enable or disable email notification on +specific events. + +In general, users have almost complete control over how much (or +how little) email Bugzilla sends them. If you want to receive the +maximum amount of email possible, click the ``Enable All +Mail`` button. If you don't want to receive any email from +Bugzilla at all, click the ``Disable All Mail`` button. + +.. note:: A Bugzilla administrator can stop a user from receiving + bugmail by clicking the ``Bugmail Disabled`` checkbox + when editing the user account. This is a drastic step + best taken only for disabled accounts, as it overrides + the user's individual mail preferences. + +There are two global options -- ``Email me when someone +asks me to set a flag`` and ``Email me when someone +sets a flag I asked for``. These define how you want to +receive bugmail with regards to flags. Their use is quite +straightforward; enable the checkboxes if you want Bugzilla to +send you mail under either of the above conditions. + +If you'd like to set your bugmail to something besides +'Completely ON' and 'Completely OFF', the +``Field/recipient specific options`` table +allows you to do just that. The rows of the table +define events that can happen to a bug -- things like +attachments being added, new comments being made, the +priority changing, etc. The columns in the table define +your relationship with the bug: + +- Reporter - Where you are the person who initially + reported the bug. Your name/account appears in the + ``Reporter:`` field. + +- Assignee - Where you are the person who has been + designated as the one responsible for the bug. Your + name/account appears in the ``Assigned To:`` + field of the bug. + +- QA Contact - You are one of the designated + QA Contacts for the bug. Your account appears in the + ``QA Contact:`` text-box of the bug. + +- CC - You are on the list CC List for the bug. + Your account appears in the ``CC:`` text box + of the bug. + +- Voter - You have placed one or more votes for the bug. + Your account appears only if someone clicks on the + ``Show votes for this bug`` link on the bug. + +.. note:: Some columns may not be visible for your installation, depending + on your site's configuration. + +To fine-tune your bugmail, decide the events for which you want +to receive bugmail; then decide if you want to receive it all +the time (enable the checkbox for every column), or only when +you have a certain relationship with a bug (enable the checkbox +only for those columns). For example: if you didn't want to +receive mail when someone added themselves to the CC list, you +could uncheck all the boxes in the ``CC Field Changes`` +line. As another example, if you never wanted to receive email +on bugs you reported unless the bug was resolved, you would +un-check all boxes in the ``Reporter`` column +except for the one on the ``The bug is resolved or +verified`` row. + +.. note:: Bugzilla adds the ``X-Bugzilla-Reason`` header to + all bugmail it sends, describing the recipient's relationship + (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug. + This header can be used to do further client-side filtering. + +Bugzilla has a feature called ``Users Watching``. +When you enter one or more comma-delineated user accounts (usually email +addresses) into the text entry box, you will receive a copy of all the +bugmail those users are sent (security settings permitting). +This powerful functionality enables seamless transitions as developers +change projects or users go on holiday. + +.. note:: The ability to watch other users may not be available in all + Bugzilla installations. If you don't see this feature, and feel + that you need it, speak to your administrator. + +Each user listed in the ``Users watching you`` field +has you listed in their ``Users to watch`` list +and can get bugmail according to your relationship to the bug and +their ``Field/recipient specific options`` setting. + +.. _savedsearches: + +Saved Searches +============== + +On this tab you can view and run any Saved Searches that you have +created, and also any Saved Searches that other members of the group +defined in the "querysharegroup" parameter have shared. +Saved Searches can be added to the page footer from this screen. +If somebody is sharing a Search with a group she or he is allowed to +:ref:`assign users to `, the sharer may opt to have +the Search show up in the footer of the group's direct members by default. + +.. _accountpreferences: + +Name and Password +================= + +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 +*current* password into the ``Password`` +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. + +.. _permissionsettings: + +Permissions +=========== + +This is a purely informative page which outlines your current +permissions on this installation of Bugzilla. + +A complete list of permissions is below. Only users with +*editusers* privileges can change the permissions +of other users. + +admin + Indicates user is an Administrator. + +bz_canusewhineatothers + Indicates user can configure whine reports for other users. + +bz_canusewhines + Indicates user can configure whine reports for self. + +bz_quip_moderators + Indicates user can moderate quips. + +bz_sudoers + Indicates user can perform actions as other users. + +bz_sudo_protect + Indicates user cannot be impersonated by other users. + +canconfirm + Indicates user can confirm a bug or mark it a duplicate. + +creategroups + Indicates user can create and destroy groups. + +editbugs + Indicates user can edit all bug fields. + +editclassifications + Indicates user can create, destroy, and edit classifications. + +editcomponents + Indicates user can create, destroy, and edit components. + +editkeywords + Indicates user can create, destroy, and edit keywords. + +editusers + Indicates user can edit or disable users. + +tweakparams + Indicates user can change Parameters. + +.. note:: For more information on how permissions work in Bugzilla (i.e. who can + change what), see :ref:`cust-change-permissions`. + +.. _reporting: + +Reports and Charts +################## + +As well as the standard buglist, Bugzilla has two more ways of +viewing sets of bugs. These are the reports (which give different +views of the current state of the database) and charts (which plot +the changes in particular sets of bugs over time.) + +.. _reports: + +Reports +======= + +A report is a view of the current state of the bug database. + +You can run either an HTML-table-based report, or a graphical +line/pie/bar-chart-based one. The two have different pages to +define them, but are close cousins - once you've defined and +viewed a report, you can switch between any of the different +views of the data at will. + +Both report types are based on the idea of defining a set of bugs +using the standard search interface, and then choosing some +aspect of that set to plot on the horizontal and/or vertical axes. +You can also get a form of 3-dimensional report by choosing to have +multiple images or tables. + +So, for example, you could use the search form to choose "all +bugs in the WorldControl product", and then plot their severity +against their component to see which component had had the largest +number of bad bugs reported against it. + +Once you've defined your parameters and hit "Generate Report", +you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie +is only available if you didn't define a vertical axis, as pie +charts don't have one.) The other controls are fairly self-explanatory; +you can change the size of the image if you find text is overwriting +other text, or the bars are too thin to see. + +.. _charts: + +Charts +====== + +A chart is a view of the state of the bug database over time. + +Bugzilla currently has two charting systems - Old Charts and New +Charts. Old Charts have been part of Bugzilla for a long time; they +chart each status and resolution for each product, and that's all. +They are deprecated, and going away soon - we won't say any more +about them. +New Charts are the future - they allow you to chart anything you +can define as a search. + +.. note:: Both charting forms require the administrator to set up the + data-gathering script. If you can't see any charts, ask them whether + they have done so. + +An individual line on a chart is called a data set. +All data sets are organised into categories and subcategories. The +data sets that Bugzilla defines automatically use the Product name +as a Category and Component names as Subcategories, but there is no +need for you to follow that naming scheme with your own charts if +you don't want to. + +Data sets may be public or private. Everyone sees public data sets in +the list, but only their creator sees private data sets. Only +administrators can make data sets public. +No two data sets, even two private ones, can have the same set of +category, subcategory and name. So if you are creating private data +sets, one idea is to have the Category be your username. + +Creating Charts +--------------- + +You create a chart by selecting a number of data sets from the +list, and pressing Add To List for each. In the List Of Data Sets +To Plot, you can define the label that data set will have in the +chart's legend, and also ask Bugzilla to Sum a number of data sets +(e.g. you could Sum data sets representing RESOLVED, VERIFIED and +CLOSED in a particular product to get a data set representing all +the resolved bugs in that product.) + +If you've erroneously added a data set to the list, select it +using the checkbox and click Remove. Once you add more than one +data set, a "Grand Total" line +automatically appears at the bottom of the list. If you don't want +this, simply remove it as you would remove any other line. + +You may also choose to plot only over a certain date range, and +to cumulate the results - that is, to plot each one using the +previous one as a baseline, so the top line gives a sum of all +the data sets. It's easier to try than to explain :-) + +Once a data set is in the list, one can also perform certain +actions on it. For example, one can edit the +data set's parameters (name, frequency etc.) if it's one you +created or if you are an administrator. + +Once you are happy, click Chart This List to see the chart. + +.. _charts-new-series: + +Creating New Data Sets +---------------------- + +You may also create new data sets of your own. To do this, +click the "create a new data set" link on the Create Chart page. +This takes you to a search-like interface where you can define +the search that Bugzilla will plot. At the bottom of the page, +you choose the category, sub-category and name of your new +data set. + +If you have sufficient permissions, you can make the data set public, +and reduce the frequency of data collection to less than the default +seven days. + +.. _flags: + +Flags +##### + +A flag is a kind of status that can be set on bugs or attachments +to indicate that the bugs/attachments are in a certain state. +Each installation can define its own set of flags that can be set +on bugs or attachments. + +If your installation has defined a flag, you can set or unset that flag, +and if your administrator has enabled requesting of flags, you can submit +a request for another user to set the flag. + +To set a flag, select either "+" or "-" from the drop-down menu next to +the name of the flag in the "Flags" list. The meaning of these values are +flag-specific and thus cannot be described in this documentation, +but by way of example, setting a flag named "review" to "+" may indicate +that the bug/attachment has passed review, while setting it to "-" +may indicate that the bug/attachment has failed review. + +To unset a flag, click its drop-down menu and select the blank value. +Note that marking an attachment as obsolete automatically cancels all +pending requests for the attachment. + +If your administrator has enabled requests for a flag, request a flag +by selecting "?" from the drop-down menu and then entering the username +of the user you want to set the flag in the text field next to the menu. + +A set flag appears in bug reports and on "edit attachment" pages with the +abbreviated username of the user who set the flag prepended to the +flag name. For example, if Jack sets a "review" flag to "+", it appears +as Jack: review [ + ] + +A requested flag appears with the user who requested the flag prepended +to the flag name and the user who has been requested to set the flag +appended to the flag name within parentheses. For example, if Jack +asks Jill for review, it appears as Jack: review [ ? ] (Jill). + +You can browse through open requests made of you and by you by selecting +'My Requests' from the footer. You can also look at open requests limited +by other requesters, requestees, products, components, and flag names from +this page. Note that you can use '-' for requestee to specify flags with +'no requestee' set. + +.. _whining: + +Whining +####### + +Whining is a feature in Bugzilla that can regularly annoy users at +specified times. Using this feature, users can execute saved searches +at specific times (i.e. the 15th of the month at midnight) or at +regular intervals (i.e. every 15 minutes on Sundays). The results of the +searches are sent to the user, either as a single email or as one email +per bug, along with some descriptive text. + +.. warning:: Throughout this section it will be assumed that all users are members + of the bz_canusewhines group, membership in which is required in order + to use the Whining system. You can easily make all users members of + the bz_canusewhines group by setting the User RegExp to ".*" (without + the quotes). + + Also worth noting is the bz_canusewhineatothers group. Members of this + group can create whines for any user or group in Bugzilla using a + extended form of the whining interface. Features only available to + members of the bz_canusewhineatothers group will be noted in the + appropriate places. + +.. note:: For whining to work, a special Perl script must be executed at regular + intervals. More information on this is available in :ref:`installation-whining`. + +.. note:: This section does not cover the whineatnews.pl script. + See :ref:`installation-whining-cron` for more information on + The Whining Cron. + +.. _whining-overview: + +The Event +========= + +The whining system defines an "Event" as one or more queries being +executed at regular intervals, with the results of said queries (if +there are any) being emailed to the user. Events are created by +clicking on the "Add new event" button. + +Once a new event is created, the first thing to set is the "Email +subject line". The contents of this field will be used in the subject +line of every email generated by this event. In addition to setting a +subject, space is provided to enter some descriptive text that will be +included at the top of each message (to help you in understanding why +you received the email in the first place). + +The next step is to specify when the Event is to be run (the Schedule) +and what searches are to be performed (the Searches). + +.. _whining-schedule: + +Whining Schedule +================ + +Each whining event is associated with zero or more schedules. A +schedule is used to specify when the search (specified below) is to be +run. A new event starts out with no schedules (which means it will +never run, as it is not scheduled to run). To add a schedule, press +the "Add a new schedule" button. + +Each schedule includes an interval, which you use to tell Bugzilla +when the event should be run. An event can be run on certain days of +the week, certain days of the month, during weekdays (defined as +Monday through Friday), or every day. + +.. warning:: Be careful if you set your event to run on the 29th, 30th, or 31st of + the month, as your event may not run exactly when expected. If you + want your event to run on the last day of the month, select "Last day + of the month" as the interval. + +Once you have specified the day(s) on which the event is to be run, you +should now specify the time at which the event is to be run. You can +have the event run at a certain hour on the specified day(s), or +every hour, half-hour, or quarter-hour on the specified day(s). + +If a single schedule does not execute an event as many times as you +would want, you can create another schedule for the same event. For +example, if you want to run an event on days whose numbers are +divisible by seven, you would need to add four schedules to the event, +setting the schedules to run on the 7th, 14th, 21st, and 28th (one day +per schedule) at whatever time (or times) you choose. + +.. note:: If you are a member of the bz_canusewhineatothers group, then you + will be presented with another option: "Mail to". Using this you + can control who will receive the emails generated by this event. You + can choose to send the emails to a single user (identified by email + address) or a single group (identified by group name). To send to + multiple users or groups, create a new schedule for each additional + user/group. + +.. _whining-query: + +Whining Searches +================ + +Each whining event is associated with zero or more searches. A search +is any saved search to be run as part of the specified schedule (see +above). You start out without any searches associated with the event +(which means that the event will not run, as there will never be any +results to return). To add a search, press the "Add a search" button. + +The first field to examine in your newly added search is the Sort field. +Searches are run, and results included, in the order specified by the +Sort field. Searches with smaller Sort values will run before searches +with bigger Sort values. + +The next field to examine is the Search field. This is where you +choose the actual search that is to be run. Instead of defining search +parameters here, you are asked to choose from the list of saved +searches (the same list that appears at the bottom of every Bugzilla +page). You are only allowed to choose from searches that you have +saved yourself (the default saved search, "My Bugs", is not a valid +choice). If you do not have any saved searches, you can take this +opportunity to create one (see :ref:`list`). + +.. note:: When running searches, the whining system acts as if you are the user + executing the search. This means that the whining system will ignore + bugs that match your search, but that you cannot access. + +Once you have chosen the saved search to be executed, give the search a +descriptive title. This title will appear in the email, above the +results of the search. If you choose "One message per bug", the search +title will appear at the top of each email that contains a bug matching +your search. + +Finally, decide if the results of the search should be sent in a single +email, or if each bug should appear in its own email. + +.. warning:: Think carefully before checking the "One message per bug" box. If + you create a search that matches thousands of bugs, you will receive + thousands of emails! + +Saving Your Changes +=================== + +Once you have defined at least one schedule, and created at least one +search, go ahead and "Update/Commit". This will save your Event and make +it available for immediate execution. + +.. note:: If you ever feel like deleting your event, you may do so using the + "Remove Event" button in the upper-right corner of each Event. You + can also modify an existing event, so long as you "Update/Commit" + after completing your modifications. + + diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml deleted file mode 100644 index 1017f559f..000000000 --- a/docs/en/xml/Bugzilla-Guide.xml +++ /dev/null @@ -1,135 +0,0 @@ - - - %myents; -]> - - - - - - - - - The Bugzilla Guide - &bz-ver; - <!-- BZ-DEVEL -->Development <!-- /BZ-DEVEL --> - Release - - - The Bugzilla Team - - - &bz-date; - - - - This is the documentation for Bugzilla, a - bug-tracking system from mozilla.org. - Bugzilla is an enterprise-class piece of software - that tracks millions of bugs and issues for hundreds of - organizations around the world. - - - - The most current version of this document can always be found on the - Bugzilla - Documentation Page. - - - - - - Bugzilla - Guide - installation - FAQ - administration - integration - MySQL - Mozilla - webtools - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml deleted file mode 100644 index 758b0b609..000000000 --- a/docs/en/xml/about.xml +++ /dev/null @@ -1,225 +0,0 @@ - - - - %myents; -]> - - -About This Guide - - - -
- Disclaimer - - No liability for the contents of this document can be accepted. - Follow the instructions herein at your own risk. - This document may contain errors - and inaccuracies that may damage your system, cause your partner - to leave you, your boss to fire you, your cats to - pee on your furniture and clothing, and global thermonuclear - war. Proceed with caution. - - - Naming of particular products or brands should not be seen as - endorsements, with the exception of the term "GNU/Linux". We - wholeheartedly endorse the use of GNU/Linux; it is an extremely - versatile, stable, - and robust operating system that offers an ideal operating - environment for Bugzilla. - - - Although the Bugzilla development team has taken great care to - ensure that all exploitable bugs have been fixed, security holes surely - exist in any piece of code. Great care should be taken both in - the installation and usage of this software. The Bugzilla development - team members assume no liability for your use of Bugzilla. You have - the source code, and are responsible for auditing it yourself to ensure - your security needs are met. - -
- - - -
- New Versions - - This is the &bz-ver; version of The Bugzilla Guide. It is so named - to match the current version of Bugzilla. - This version of the guide, like its associated Bugzilla version, is a - development version. - - - The latest version of this guide can always be found at . However, you should read - the version which came with the Bugzilla release you are using. - - - - In addition, there are Bugzilla template localization projects in - several languages. - They may have translated documentation available. If you would like to - volunteer to translate the Guide into additional languages, please visit the - Bugzilla L10n team - page. - -
- -
- Credits - - 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: - - - - - - Matthew P. Barnson mbarnson@sisna.com - - for the Herculean task of pulling together the Bugzilla Guide - and shepherding it to 2.14. - - - - - - Terry Weissman terry@mozilla.org - - for initially writing Bugzilla and creating the README upon - which the UNIX installation documentation is largely based. - - - - - - Tara Hernandez tara@tequilarists.org - - for keeping Bugzilla development going strong after Terry left - mozilla.org and for running landfill. - - - - - - Dave Lawrence dkl@redhat.com - - for providing insight into the key differences between Red - Hat's customized Bugzilla. - - - - - - Dawn Endico endico@mozilla.org - - for being a hacker extraordinaire and putting up with Matthew's - incessant questions and arguments on irc.mozilla.org in #mozwebtools - - - - - - Jacob Steenhagen jake@bugzilla.org - - for taking over documentation during the 2.17 development - period. - - - - - - Dave Miller justdave@bugzilla.org - - for taking over as project lead when Tara stepped down and - continually pushing for the documentation to be the best it can be. - - - - - - - - - Thanks also go to the following people for significant contributions - to this documentation: - - Kevin Brannen - Vlad Dascalu - Ben FrantzDale - Eric Hanson - Zach Lipton - Gervase Markham - Andrew Pearson - Joe Robins - Spencer Smith - Ron Teitelbaum - Shane Travis - Martin Wulffeld - . - - - - Also, thanks are due to the members of the - - mozilla.support.bugzilla - newsgroup (and its predecessor, netscape.public.mozilla.webtools). - Without your discussions, insight, suggestions, and patches, - this could never have happened. - -
- - - - - - diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml deleted file mode 100644 index 0d32cdb52..000000000 --- a/docs/en/xml/administration.xml +++ /dev/null @@ -1,3244 +0,0 @@ - - - - %myents; -]> - - - Administering Bugzilla - -
- Bugzilla Configuration - - - Bugzilla is configured by changing various parameters, accessed - from the "Parameters" link in the Administration page (the - Administration page can be found by clicking the "Administration" - link in the footer). The parameters are divided into several categories, - accessed via the menu on the left. Following is a description of the - different categories and important parameters within those categories. - - -
- Required Settings - - - The core required parameters for any Bugzilla installation are set - here. These parameters must be set before a new Bugzilla installation - can be used. Administrators should review this list before - deploying a new Bugzilla installation. - - - - - - - maintainer - - - - Email address of the person - responsible for maintaining this Bugzilla installation. - The address need not be that of a valid Bugzilla account. - - - - - - - urlbase - - - - Defines the fully qualified domain name and web - server path to this Bugzilla installation. - - - For example, if the Bugzilla query page is - http://www.foo.com/bugzilla/query.cgi, - the urlbase should be set - to http://www.foo.com/bugzilla/. - - - - - - - docs_urlbase - - - - Defines path to the Bugzilla documentation. This can be a fully - qualified domain name, or a path relative to "urlbase". - - - For example, if the "Bugzilla Configuration" page - of the documentation is - http://www.foo.com/bugzilla/docs/html/parameters.html, - set the docs_urlbase - to http://www.foo.com/bugzilla/docs/html/. - - - - - - - sslbase - - - - Defines the fully qualified domain name and web - server path for HTTPS (SSL) connections to this Bugzilla installation. - - - For example, if the Bugzilla main page is - https://www.foo.com/bugzilla/index.cgi, - the sslbase should be set - to https://www.foo.com/bugzilla/. - - - - - - - ssl_redirect - - - - If enabled, Bugzilla will force HTTPS (SSL) connections, by - automatically redirecting any users who try to use a non-SSL - connection. - - - - - - - cookiedomain - - - - Defines the domain for Bugzilla cookies. This is typically left blank. - If there are multiple hostnames that point to the same webserver, which - require the same cookie, then this parameter can be utilized. For - example, If your website is at - https://www.foo.com/, setting this to - .foo.com/ will also allow - bar.foo.com/ to access Bugzilla cookies. - - - - - - - cookiepath - - - - Defines a path, relative to the web server root, that Bugzilla - cookies will be restricted to. For example, if the - urlbase is set to - http://www.foo.com/bugzilla/, the - cookiepath should be set to - /bugzilla/. Setting it to "/" will allow all sites - served by this web server or virtual host to read Bugzilla cookies. - - - - - - - utf8 - - - - Determines whether to use UTF-8 (Unicode) encoding for all text in - Bugzilla. New installations should set this to true to avoid character - encoding problems. Existing databases should set this to true only - after the data has been converted from existing legacy character - encoding to UTF-8, using the - contrib/recode.pl script. - - - - If you turn this parameter from "off" to "on", you must re-run - checksetup.pl immediately afterward. - - - - - - - - shutdownhtml - - - - If there is any text in this field, this Bugzilla installation will - be completely disabled and this text will appear instead of all - Bugzilla pages for all users, including Admins. Used in the event - of site maintenance or outage situations. - - - - Although regular log-in capability is disabled while - shutdownhtml - is enabled, safeguards are in place to protect the unfortunate - admin who loses connection to Bugzilla. Should this happen to you, - go directly to the editparams.cgi (by typing - the URL in manually, if necessary). Doing this will prompt you to - log in, and your name/password will be accepted here (but nowhere - else). - - - - - - - - announcehtml - - - - Any text in this field will be displayed at the top of every HTML - page in this Bugzilla installation. The text is not wrapped in any - tags. For best results, wrap the text in a <div> - tag. Any style attributes from the CSS can be applied. For example, - to make the text green inside of a red box, add id=message - to the <div> tag. - - - - - - - proxy_url - - - - If this Bugzilla installation is behind a proxy, enter the proxy - information here to enable Bugzilla to access the Internet. Bugzilla - requires Internet access to utilize the - upgrade_notification parameter (below). If the - proxy requires authentication, use the syntax: - http://user:pass@proxy_url/. - - - - - - - upgrade_notification - - - - Enable or disable a notification on the homepage of this Bugzilla - installation when a newer version of Bugzilla is available. This - notification is only visible to administrators. Choose "disabled", - to turn off the notification. Otherwise, choose which version of - Bugzilla you want to be notified about: "development_snapshot" is the - latest release on the trunk; "latest_stable_release" is the most - recent release available on the most recent stable branch; - "stable_branch_release" the most recent release on the branch - this installation is based on. - - - - - - -
- -
- Administrative Policies - - This page contains parameters for basic administrative functions. - Options include whether to allow the deletion of bugs and users, - and whether to allow users to change their email address. - -
- -
- User Authentication - - This page contains the settings that control how this Bugzilla - installation will do its authentication. Choose what authentication - mechanism to use (the Bugzilla database, or an external source such - as LDAP), and set basic behavioral parameters. For example, choose - whether to require users to login to browse bugs, the management - of authentication cookies, and the regular expression used to - validate email addresses. Some parameters are highlighted below. - - - - - - - emailregexp - - - - Defines the regular expression used to validate email addresses - used for login names. The default attempts to match fully - qualified email addresses (i.e. 'user@example.com') in a slightly - more restrictive way than what is allowed in RFC 2822. - Some Bugzilla installations allow only local user names (i.e 'user' - instead of 'user@example.com'). In that case, this parameter - should be used to define the email domain. - - - - - - - emailsuffix - - - - This string is appended to login names when actually sending - email to a user. For example, - If emailregexp has been set to allow - local usernames, - then this parameter would contain the email domain for all users - (i.e. '@example.com'). - - - - - - -
- -
- Attachments - - This page allows for setting restrictions and other parameters - regarding attachments to bugs. For example, control size limitations - and whether to allow pointing to external files via a URI. - -
- -
- Bug Change Policies - - Set policy on default behavior for bug change events. For example, - choose which status to set a bug to when it is marked as a duplicate, - and choose whether to allow bug reporters to set the priority or - target milestone. Also allows for configuration of what changes - should require the user to make a comment, described below. - - - - - - - commenton* - - - - 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. - - - - 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. - - - - - 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!) - - - - - - - noresolveonopenblockers - - - - This option will prevent users from resolving bugs as FIXED if - they have unresolved dependencies. Only the FIXED resolution - is affected. Users will be still able to resolve bugs to - resolutions other than FIXED if they have unresolved dependent - bugs. - - - - - - -
- -
- Bug Fields - - The parameters in this section determine the default settings of - several Bugzilla fields for new bugs, and also control whether - certain fields are used. For example, choose whether to use the - "target milestone" field or the "status whiteboard" field. - - - - - - - useqacontact - - - - This allows you to define an email address for each component, - in addition to that of the default assignee, who will be sent - carbon copies of incoming bugs. - - - - - - - usestatuswhiteboard - - - - 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. - - - - - - -
- -
- Bug Moving - - This page controls whether this Bugzilla installation allows certain - users to move bugs to an external database. If bug moving is enabled, - there are a number of parameters that control bug moving behaviors. - For example, choose which users are allowed to move bugs, the location - of the external database, and the default product and component that - bugs moved from other bug databases to this - Bugzilla installation are assigned to. - - -
- -
- Graphs - - This page contains parameters to control how graphs are generated. - - - - - - - webdotbase - - - - This sets the location of a Web Dot server, or of the Web Dot - binary on the local system, that is used to generate dependency - graphs. Web Dot is a CGI program that creates images from - .dot graphic description files. If no Web Dot - server or binary is specified, then dependency graphs will be disabled. - - - - - - - font_file - - - - This defines the full path to a TrueType font file which will be - used to display text in charts and graphical reports. The recommended - font is Unifont which supports all languages in the Basic Multilingual - Plane. On Linux, the path is of the form - /usr/share/fonts/TTF/unifont/unifont-6.3.20131006.ttf - and on Windows, the path would be - C:\Windows\Fonts\unifont-6.3.20131006.ttf. - - - If you don't have this font installed, you can download it from the - Unifoundry.com - website and install it at the location specified above. This font - is free of charge and can be installed on all operating systems. - - - - - -
- -
- Group Security - - Bugzilla allows for the creation of different groups, with the - ability to restrict the visibility of bugs in a group to a set of - specific users. Specific products can also be associated with - groups, and users restricted to only see products in their groups. - Several parameters are described in more detail below. Most of the - configuration of groups and their relationship to products is done - on the "Groups" and "Product" pages of the "Administration" area. - The options on this page control global default behavior. - For more information on Groups and Group Security, see - - - - - - - - makeproductgroups - - - - Determines whether or not to automatically create groups - when new products are created. If this is on, the groups will be - used for querying bugs. - - - - - - - usevisibilitygroups - - - - If selected, user visibility will be restricted to members of - groups, as selected in the group configuration settings. - Each user-defined group can be allowed to see members of selected - other groups. - For details on configuring groups (including the visibility - restrictions) see . - - - - - - - querysharegroup - - - - The name of the group of users who are allowed to share saved - searches with one another. For more information on using - saved searches, see . - - - - - - -
- -
- LDAP Authentication - - LDAP authentication is a module for Bugzilla's plugin - authentication architecture. This page contains all the parameters - necessary to configure Bugzilla for use with LDAP authentication. - - - - The existing authentication - scheme for Bugzilla uses email addresses as the primary user ID, and a - password to authenticate that user. All places within Bugzilla that - require a user ID (e.g assigning a bug) use the email - address. The LDAP authentication builds on top of this scheme, rather - than replacing it. The initial log-in is done with a username and - password for the LDAP directory. Bugzilla tries to bind to LDAP using - those credentials and, if successful, tries to map this account to a - Bugzilla account. If an LDAP mail attribute is defined, the value of this - attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP - username to form a full email address. If an account for this address - already exists in the Bugzilla installation, it will log in to that account. - If no account for that email address exists, one is created at the time - of login. (In this case, Bugzilla will attempt to use the "displayName" - or "cn" attribute to determine the user's full name.) After - authentication, all other user-related tasks are still handled by email - address, not LDAP username. For example, bugs are still assigned by - email address and users are still queried by email address. - - - - Because the Bugzilla account is not created until the first time - a user logs in, a user who has not yet logged is unknown to Bugzilla. - This means they cannot be used as an assignee or QA contact (default or - otherwise), added to any CC list, or any other such operation. One - possible workaround is the bugzilla_ldapsync.rb - script in the - - contrib - directory. Another possible solution is fixing - bug - 201069. - - - - Parameters required to use LDAP Authentication: - - - - user_verify_class - - If you want to list LDAP here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - data/params and set user_verify_class to - DB. - - - - - - LDAPserver - - This parameter should be set to the name (and optionally the - port) of your LDAP server. If no port is specified, it assumes - the default LDAP port of 389. - - For example: ldap.company.com - or ldap.company.com:3268 - - You can also specify a LDAP URI, so as to use other - protocols, such as LDAPS or LDAPI. If port was not specified in - the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' - schemes respectively. - - - - In order to use SSL with LDAP, specify a URI with "ldaps://". - This will force the use of SSL over port 636. - - - For example, normal LDAP: - ldap://ldap.company.com, LDAP over SSL: - ldaps://ldap.company.com or LDAP over a UNIX - domain socket ldapi://%2fvar%2flib%2fldap_sock. - - - - - - LDAPbinddn [Optional] - - Some LDAP servers will not allow an anonymous bind to search - the directory. If this is the case with your configuration you - should set the LDAPbinddn parameter to the user account Bugzilla - should use instead of the anonymous bind. - - Ex. cn=default,cn=user:password - - - - - LDAPBaseDN - - The LDAPBaseDN parameter should be set to the location in - your LDAP tree that you would like to search for email addresses. - Your uids should be unique under the DN specified here. - - Ex. ou=People,o=Company - - - - - LDAPuidattribute - - The LDAPuidattribute parameter should be set to the attribute - which contains the unique UID of your users. The value retrieved - from this attribute will be used when attempting to bind as the - user to confirm their password. - - Ex. uid - - - - - LDAPmailattribute - - The LDAPmailattribute parameter should be the name of the - attribute which contains the email address your users will enter - into the Bugzilla login boxes. - - Ex. mail - - - - -
- -
- RADIUS Authentication - - - RADIUS authentication is a module for Bugzilla's plugin - authentication architecture. This page contains all the parameters - necessary for configuring Bugzilla to use RADIUS authentication. - - - - Most caveats that apply to LDAP authentication apply to RADIUS - authentication as well. See for details. - - - - Parameters required to use RADIUS Authentication: - - - - user_verify_class - - If you want to list RADIUS here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - data/params and set user_verify_class to - DB. - - - - - - RADIUS_server - - This parameter should be set to the name (and optionally the - port) of your RADIUS server. - - - - - - RADIUS_secret - - This parameter should be set to the RADIUS server's secret. - - - - - - RADIUS_email_suffix - - Bugzilla needs an e-mail address for each user account. - Therefore, it needs to determine the e-mail address corresponding - to a RADIUS user. - Bugzilla offers only a simple way to do this: it can concatenate - a suffix to the RADIUS user name to convert it into an e-mail - address. - You can specify this suffix in the RADIUS_email_suffix parameter. - - If this simple solution does not work for you, you'll - probably need to modify - Bugzilla/Auth/Verify/RADIUS.pm to match your - requirements. - - - - - -
- -
- Email - - This page contains all of the parameters for configuring how - Bugzilla deals with the email notifications it sends. See below - for a summary of important options. - - - - - - - mail_delivery_method - - - - This is used to specify how email is sent, or if it is sent at - all. There are several options included for different MTAs, - along with two additional options that disable email sending. - "Test" does not send mail, but instead saves it in - data/mailer.testfile for later review. - "None" disables email sending entirely. - - - - - - - mailfrom - - - - This is the email address that will appear in the "From" field - of all emails sent by this Bugzilla installation. Some email - servers require mail to be from a valid email address, therefore - it is recommended to choose a valid email address here. - - - - - - - smtpserver - - - - This is the SMTP server address, if the mail_delivery_method - parameter is set to SMTP. Use "localhost" if you have a local MTA - running, otherwise use a remote SMTP server. Append ":" and the port - number, if a non-default port is needed. - - - - - - - smtp_username - - - - Username to use for SASL authentication to the SMTP server. Leave - this parameter empty if your server does not require authentication. - - - - - - - smtp_password - - - - Password to use for SASL authentication to the SMTP server. This - parameter will be ignored if the smtp_username - parameter is left empty. - - - - - - - smtp_ssl - - - - Enable SSL support for connection to the SMTP server. - - - - - - - smtp_debug - - - - This parameter allows you to enable detailed debugging output. - Log messages are printed the web server's error log. - - - - - - - whinedays - - - - Set this to the number of days you want to let bugs go - in the CONFIRMED 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). - - - - - - - globalwatcher - - - - This allows you to define specific users who will - receive notification each time a new bug in entered, or when - an existing bug changes, according to the normal groupset - permissions. It may be useful for sending notifications to a - mailing-list, for instance. - - - - - - -
- -
- Patch Viewer - - This page contains configuration parameters for the CVS server, - Bonsai server and LXR server that Bugzilla will use to enable the - features of the Patch Viewer. Bonsai is a tool that enables queries - to a CVS tree. LXR is a tool that can cross reference and index source - code. - -
- -
- Query Defaults - - This page controls the default behavior of Bugzilla in regards to - several aspects of querying bugs. Options include what the default - query options are, what the "My Bugs" page returns, whether users - can freely add bugs to the quip list, and how many duplicate bugs are - needed to add a bug to the "most frequently reported" list. - -
- -
- Shadow Database - - This page controls whether a shadow database is used, and all the - parameters associated with the shadow database. Versions of Bugzilla - prior to 3.2 used the MyISAM table type, which supports - only table-level write locking. With MyISAM, any time someone is making a change to - a bug, the entire table is locked until the write operation is complete. - Locking for write also blocks reads until the write is complete. - - - The shadowdb 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. - - - - - As of version 3.2, Bugzilla no longer uses the MyISAM table type. - Instead, InnoDB is used, which can do transaction-based locking. - Therefore, the limitations the Shadow Database feature was designed - to workaround no longer exist. - - - -
- -
- User Matching - - The settings on this page control how users are selected and queried - when adding a user to a bug. For example, users need to be selected - when choosing who the bug is assigned to, adding to the CC list or - selecting a QA contact. With the "usemenuforusers" parameter, it is - possible to configure Bugzilla to - display a list of users in the fields instead of an empty text field. - This should only be used in Bugzilla installations with a small number - of users. If users are selected via a text box, this page also - contains parameters for how user names can be queried and matched - when entered. - - - Another setting called 'ajax_user_autocompletion' enables certain - user fields to display a list of matched user names as a drop down after typing - a few characters. Note that it is recommended to use mod_perl when - enabling 'ajax_user_autocompletion'. - -
- -
- -
- User Administration - -
- Creating the Default User - - 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. - - - If you wish to add more administrative users, add them to - the "admin" group and, optionally, edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups (which is the case by default). - - -
- -
- Managing Other Users - - - -
- Creating new users - -
- Self-registration - - - By default, 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). If you want to disable - this self-registration, or if you want to restrict who can create his - own user account, you have to edit the createemailregexp - parameter in the Configuration page, see - . - -
- -
- Accounts created by an administrator - - - Users with editusers privileges, such as administrators, - can create user accounts for other users: - - - - - After logging in, click the "Users" link at the footer of - the query page, and then click "Add a new user". - - - - Fill out the form presented. This page is self-explanatory. - When done, click "Submit". - - - Adding a user this way will not - 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 New Account - button to create users, as it will pre-populate all the - required fields and also notify the user of her account name - and password. - - - -
-
- -
- Modifying Users - - Once you have found your user, you can change the following - fields: - - - - - Login Name: - This is generally the user's full email address. However, if you - are using the emailsuffix parameter, this may - just be the user's login name. Note that users can now change their - login names themselves (to any valid email address). - - - - - - Real Name: The user's real name. Note that - Bugzilla does not require this to create an account. - - - - - Password: - 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. - - - - - - Bugmail Disabled: - Mark this checkbox to disable bugmail and whinemail completely - for this account. This checkbox replaces the data/nomail file - which existed in older versions of Bugzilla. - - - - - - Disable Text: - 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. - - - Users with disabled accounts will continue to receive - mail from Bugzilla; furthermore, they will not be able - to log in themselves to change their own preferences and - stop it. If you want an account (disabled or active) to - stop receiving mail, simply check the - Bugmail Disabled checkbox above. - - - - Even users whose accounts have been disabled can still - submit bugs via the e-mail gateway, if one exists. - The e-mail gateway should not be - enabled for secure installations of Bugzilla. - - - - - Don't disable all the administrator accounts! - - - - - - - <groupname>: - 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. The first checkbox gives the - user the ability to add and remove other users as members of - this group. The second checkbox adds the user himself as a member - of the group. - - - - - - canconfirm: - 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). - - - - - creategroups: - This option will allow a user to create and destroy groups in - Bugzilla. - - - - - editbugs: - 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. - - - - - - editcomponents: - 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. - - - - - - editkeywords: - 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. - - - - - editusers: - 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. - - - - - - tweakparams: - This flag allows a user to change Bugzilla's Params - (using editparams.cgi.) - - - - - <productname>: - This allows an administrator to specify the products - in which a user can see bugs. If you turn on the - makeproductgroups parameter in - the Group Security Panel in the Parameters page, - then Bugzilla creates one group per product (at the time you create - the product), and this group has exactly the same name as the - product itself. Note that for products that already exist when - the parameter is turned on, the corresponding group will not be - created. The user must still have the editbugs - privilege to edit bugs in these products. - - -
- -
- Deleting Users - - If the allowuserdeletion parameter is turned on, see - , then you can also delete user accounts. - Note that this is most of the time not the best thing to do. If only - a warning in a yellow box is displayed, then the deletion is safe. - If a warning is also displayed in a red box, then you should NOT try - to delete the user account, else you will get referential integrity - problems in your database, which can lead to unexpected behavior, - such as bugs not appearing in bug lists anymore, or data displaying - incorrectly. You have been warned! - -
- -
- Impersonating Users - - - There may be times when an administrator would like to do something as - another user. The sudo feature may be used to do - this. - - - - - To use the sudo feature, you must be in the - bz_sudoers group. By default, all - administrators are in this group. - - - - If you have access to this feature, you may start a session by - going to the Edit Users page, Searching for a user and clicking on - their login. You should see a link below their login name titled - "Impersonate this user". Click on the link. This will take you - to a page where you will see a description of the feature and - instructions for using it. After reading the text, simply - enter the login of the user you would like to impersonate, provide - a short message explaining why you are doing this, and press the - button. - - - As long as you are using this feature, everything you do will be done - as if you were logged in as the user you are impersonating. - - - - The user you are impersonating will not be told about what you are - doing. If you do anything that results in mail being sent, that - mail will appear to be from the user you are impersonating. You - should be extremely careful while using this feature. - -
-
-
- -
- Classifications - - Classifications tend to be used in order to group several related - products into one distinct entity. - - The classifications layer is disabled by default; it can be turned - on or off using the useclassification parameter, - in the Bug Fields section of the edit parameters screen. - - Access to the administration of classifications is controlled using - the editclassifications system group, which defines - a privilege for creating, destroying, and editing classifications. - - When activated, classifications will introduce an additional - step when filling bugs (dedicated to classification selection), and they - will also appear in the advanced search form. -
- -
- Products - - - - Products typically represent real-world - shipping products. Products can be given - . - For example, if a company makes computer games, - they could have a classification of "Games", and a separate - product for each game. This company might also have a - Common product for units of technology used - in multiple games, and perhaps a few special products that - represent items that are not actually shipping products - (for example, "Website", or "Administration"). - - - - 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 CONFIRMED status. - - - - When creating or editing products the following options are - available: - - - - - - - Product - - - - The name of the product - - - - - - - Description - - - - A brief description of the product - - - - - - - Default milestone - - - - Select the default milestone for this product. - - - - - - - Closed for bug entry - - - - Select this box to prevent new bugs from being - entered against this product. - - - - - - - Maximum votes per person - - - - Maximum votes a user is allowed to give for this - product - - - - - - - Maximum votes a person can put on a single bug - - - - Maximum votes a user is allowed to give for this - product in a single bug - - - - - - - Confirmation threshold - - - - Number of votes needed to automatically remove any - bug against this product from the UNCONFIRMED state - - - - - - - Version - - - - Specify which version of the product bugs will be - entered against. - - - - - - - Create chart datasets for this product - - - - Select to make chart datasets available for this product. - - - - - - - - When editing a product there is also a link to edit Group Access Controls, - see . - - -
- Creating New Products - - - To create a new product: - - - - - - Select Administration from the footer and then - choose Products from the main administration page. - - - - - - Select the Add link in the bottom right. - - - - - - Enter the name of the product and a description. The - Description field may contain HTML. - - - - - - When the product is created, Bugzilla will give a message - stating that a component must be created before any bugs can - be entered against the new product. Follow the link to create - a new component. See for more - information. - - - - -
- -
- Editing Products - - - To edit an existing product, click the "Products" link from the - "Administration" page. If the 'useclassification' parameter is - turned on, a table of existing classifications is displayed, - including an "Unclassified" category. The table indicates how many products - are in each classification. Click on the classification name to see its - products. If the 'useclassification' parameter is not in use, the table - lists all products directly. The product table summarizes the information - about the product defined - when the product was created. Click on the product name to edit these - properties, and to access links to other product attributes such as the - product's components, versions, milestones, and group access controls. - - -
- -
- Adding or Editing Components, Versions and Target Milestones - - To edit existing, or add new, Components, Versions or Target Milestones - to a Product, select the "Edit Components", "Edit Versions" or "Edit - Milestones" links from the "Edit Product" page. A table of existing - Components, Versions or Milestones is displayed. Click on a item name - to edit the properties of that item. Below the table is a link to add - a new Component, Version or Milestone. - - - For more information on components, see . - - - For more information on versions, see . - - - For more information on milestones, see . - -
- -
- Assigning Group Controls to Products - - - On the Edit Product page, there is a link called - Edit Group Access Controls. The settings on this page - control the relationship of the groups to the product being edited. - - - - Group Access Controls are an important aspect of using groups for - isolating products and restricting access to bugs filed against those - products. For more information on groups, including how to create, edit - add users to, and alter permission of, see . - - - - After selecting the "Edit Group Access Controls" link from the "Edit - Product" page, a table containing all user-defined groups for this - Bugzilla installation is displayed. The system groups that are created - when Bugzilla is installed are not applicable to Group Access Controls. - Below is description of what each of these fields means. - - - - Groups may be applicable (e.g bugs in this product can be associated - with this group) , default (e.g. bugs in this product are in this group - by default), and mandatory (e.g. bugs in this product must be associated - with this group) for each product. Groups can also control access - to bugs for a given product, or be used to make bugs for a product - totally read-only unless the group restrictions are met. The best way to - understand these relationships is by example. See - for examples of - product and group relationships. - - - - - Products and Groups are not limited to a one-to-one relationship. - Multiple groups can be associated with the same product, and groups - can be associated with more than one product. - - - - - If any group has Entry selected, then the - product will restrict bug entry to only those users - who are members of all the groups with - Entry selected. - - - - If any group has Canedit selected, - then the product will be read-only for any users - who are not members of all of the groups with - Canedit selected. Only users who - are members of all the Canedit groups - will be able to edit bugs for this product. This is an additional - restriction that enables finer-grained control over products rather - than just all-or-nothing access levels. - - - - The following settings let you - choose privileges on a per-product basis. - This is a convenient way to give privileges to - some users for some products only, without having - to give them global privileges which would affect - all products. - - - - Any group having editcomponents - selected allows users who are in this group to edit all - aspects of this product, including components, milestones - and versions. - - - - Any group having canconfirm selected - allows users who are in this group to confirm bugs - in this product. - - - - Any group having editbugs selected allows - users who are in this group to edit all fields of - bugs in this product. - - - - The MemberControl and - OtherControl are used in tandem to determine which - bugs will be placed in this group. The only allowable combinations of - these two parameters are listed in a table on the "Edit Group Access Controls" - page. Consult this table for details on how these fields can be used. - Examples of different uses are described below. - - -
- Common Applications of Group Controls - - - The use of groups is best explained by providing examples that illustrate - configurations for common use cases. The examples follow a common syntax: - Group: Entry, MemberControl, OtherControl, CanEdit, - EditComponents, CanConfirm, EditBugs. Where "Group" is the name - of the group being edited for this product. The other fields all - correspond to the table on the "Edit Group Access Controls" page. If any - of these options are not listed, it means they are not checked. - - - - Basic Product/Group Restriction - - - - Suppose there is a product called "Bar". The - "Bar" product can only have bugs entered against it by users in the - group "Foo". Additionally, bugs filed against product "Bar" must stay - restricted to users to "Foo" at all times. Furthermore, only members - of group "Foo" can edit bugs filed against product "Bar", even if other - users could see the bug. This arrangement would achieved by the - following: - - - -Product Bar: -foo: ENTRY, MANDATORY/MANDATORY, CANEDIT - - - - Perhaps such strict restrictions are not needed for product "Bar". A - more lenient way to configure product "Bar" and group "Foo" would be: - - - -Product Bar: -foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS - - - - The above indicates that for product "Bar", members of group "Foo" can - enter bugs. Any one with permission to edit a bug against product "Bar" - can put the bug - in group "Foo", even if they themselves are not in "Foo". Anyone in group - "Foo" can edit all aspects of the components of product "Bar", can confirm - bugs against product "Bar", and can edit all fields of any bug against - product "Bar". - - - - General User Access With Security Group - - - - To permit any user to file bugs against "Product A", - and to permit any user to submit those bugs into a - group called "Security": - - - -Product A: -security: SHOWN/SHOWN - - - - General User Access With A Security Product - - - - To permit any user to file bugs against product called "Security" - while keeping those bugs from becoming visible to anyone - outside the group "SecurityWorkers" (unless a member of the - "SecurityWorkers" group removes that restriction): - - - -Product Security: -securityworkers: DEFAULT/MANDATORY - - - - Product Isolation With a Common Group - - - - To permit users of "Product A" to access the bugs for - "Product A", users of "Product B" to access the bugs for - "Product B", and support staff, who are members of the "Support - Group" to access both, three groups are needed: - - - - - - Support Group: Contains members of the support staff. - - - - AccessA Group: Contains users of product A and the Support group. - - - - AccessB Group: Contains users of product B and the Support group. - - - - - - Once these three groups are defined, the product group controls - can be set to: - - - -Product A: -AccessA: ENTRY, MANDATORY/MANDATORY -Product B: -AccessB: ENTRY, MANDATORY/MANDATORY - - - - Perhaps the "Support Group" wants more control. For example, - the "Support Group" could be permitted to make bugs inaccessible to - users of both groups "AccessA" and "AccessB". - Then, the "Support Group" could be permitted to publish - bugs relevant to all users in a third product (let's call it - "Product Common") that is read-only - to anyone outside the "Support Group". In this way the "Support Group" - could control bugs that should be seen by both groups. - That configuration would be: - - - -Product A: -AccessA: ENTRY, MANDATORY/MANDATORY -Support: SHOWN/NA -Product B: -AccessB: ENTRY, MANDATORY/MANDATORY -Support: SHOWN/NA -Product Common: -Support: ENTRY, DEFAULT/MANDATORY, CANEDIT - - - - Make a Product Read Only - - - - Sometimes a product is retired and should no longer have - new bugs filed against it (for example, an older version of a software - product that is no longer supported). A product can be made read-only - by creating a group called "readonly" and adding products to the - group as needed: - - - -Product A: -ReadOnly: ENTRY, NA/NA, CANEDIT - - - - - For more information on Groups outside of how they relate to products - see . - - - -
- -
- -
- -
- Components - - 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. - - - Each component has a default assignee and (if you turned it on in the parameters), - a QA Contact. The default assignee should be the primary person who fixes bugs in - that component. The QA Contact should be the person who will ensure - these bugs are completely fixed. The Assignee, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Assignee and Default QA Contact fields only - dictate the - default assignments; - these can be changed on bug submission, or at any later point in - a bug's life. - - To create a new Component: - - - - Select the Edit components link - from the Edit product page - - - - Select the Add link in the bottom right. - - - - Fill out the Component field, a - short Description, the - Default Assignee, Default CC List - and Default QA Contact (if enabled). - The Component Description field may contain a - limited subset of HTML tags. The Default Assignee - field must be a login name already existing in the Bugzilla database. - - - -
- -
- Versions - - Versions are the revisions of the product, such as "Flinders - 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select - field; the usual practice is to select the earliest version known to have - the bug. - - - To create and edit Versions: - - - - From the "Edit product" screen, select "Edit Versions" - - - - You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right. - - - - Enter the name of the Version. This field takes text only. - Then click the "Add" button. - - - -
- -
- Milestones - - 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. - - - Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" parameter in the "Bug Fields" tab of the - "Parameters" page. - - - - To create new Milestones, and set Default Milestones: - - - - Select "Edit milestones" from the "Edit product" page. - - - - Select "Add" in the bottom right corner. - - - - Enter the name of the Milestone in the "Milestone" field. You - can optionally set the "sortkey", which is a positive or negative - number (-32768 to 32767) that defines where in the list this particular - milestone appears. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add". - - -
- -
- Flags - - - Flags are a way to attach a specific status to a bug or attachment, - either + or -. The meaning of these symbols depends on the text - the flag itself, but contextually they could mean pass/fail, - accept/reject, approved/denied, or even a simple yes/no. If your site - allows requestable flags, then users may set a flag to ? as a - request to another user that they look at the bug/attachment, and set - the flag to its correct status. - - -
- A Simple Example - - - A developer might want to ask their manager, - Should we fix this bug before we release version 2.0? - They might want to do this for a lot of bugs, - so it would be nice to streamline the process... - - - In Bugzilla, it would work this way: - - - - The Bugzilla administrator creates a flag type called - blocking2.0 that shows up on all bugs in - your product. - - - - It shows up on the Show Bug screen - as the text blocking2.0 with a drop-down box next - to it. The drop-down box contains four values: an empty space, - ?, -, and +. - - - - The developer sets the flag to ?. - - - - The manager sees the blocking2.0 - flag with a ? value. - - - - - If the manager thinks the feature should go into the product - before version 2.0 can be released, he sets the flag to - +. Otherwise, he sets it to -. - - - - - Now, every Bugzilla user who looks at the bug knows whether or - not the bug needs to be fixed before release of version 2.0. - - - - - -
- -
- About Flags - -
- Values - - Flags can have three values: - - - ? - - A user is requesting that a status be set. (Think of it as 'A question is being asked'.) - - - - - - - The status has been set negatively. (The question has been answered no.) - - - - + - - The status has been set positively. - (The question has been answered yes.) - - - - - - Actually, there's a fourth value a flag can have -- - unset -- which shows up as a blank space. This - just means that nobody has expressed an opinion (or asked - someone else to express an opinion) about this bug or attachment. - -
-
- -
- Using flag requests - - If a flag has been defined as 'requestable', and a user has enough privileges - to request it (see below), the user can set the flag's status to ?. - This status indicates that someone (a.k.a. the requester) is asking - someone else to set the flag to either + or -. - - - If a flag has been defined as 'specifically requestable', - a text box will appear next to the flag into which the requester may - enter a Bugzilla username. That named person (a.k.a. the requestee) - will receive an email notifying them of the request, and pointing them - to the bug/attachment in question. - - - If a flag has not been defined as 'specifically requestable', - then no such text-box will appear. A request to set this flag cannot be made of - any specific individual, but must be asked to the wind. - A requester may ask the wind on any flag simply by leaving the text-box blank. - -
- -
- Two Types of Flags - - - Flags can go in two places: on an attachment, or on a bug. - - -
- Attachment Flags - - - Attachment flags are used to ask a question about a specific - attachment on a bug. - - - Many Bugzilla installations use this to - request that one developer review another - developer's code before they check it in. They attach the code to - a bug report, and then set a flag on that attachment called - review to - review?boss@domain.com. - boss@domain.com is then notified by email that - he has to check out that attachment and approve it or deny it. - - - - For a Bugzilla user, attachment flags show up in three places: - - - - On the list of attachments in the Show Bug - screen, you can see the current state of any flags that - have been set to ?, +, or -. You can see who asked about - the flag (the requester), and who is being asked (the - requestee). - - - - - When you Edit an attachment, you can - see any settable flag, along with any flags that have - already been set. This Edit Attachment - screen is where you set flags to ?, -, +, or unset them. - - - - - Requests are listed in the Request Queue, which - is accessible from the My Requests link (if you are - logged in) or Requests link (if you are logged out) - visible in the footer of all pages. - - - - - -
- -
- Bug Flags - - - Bug flags are used to set a status on the bug itself. You can - see Bug Flags in the Show Bug and Requests - screens, as described above. - - - Only users with enough privileges (see below) may set flags on bugs. - This doesn't necessarily include the assignee, reporter, or users with the - editbugs permission. - -
- -
- -
- Administering Flags - - - If you have the editcomponents permission, you can - edit Flag Types from the main administration page. Clicking the - Flags link will bring you to the Administer - Flag Types page. Here, you can select whether you want - to create (or edit) a Bug flag, or an Attachment flag. - - - No matter which you choose, the interface is the same, so we'll - just go over it once. - - -
- Editing a Flag - - To edit a flag's properties, just click the flag's name. - That will take you to the same - form as described below (). - -
- -
- Creating a Flag - - - When you click on the Create a Flag Type for... - link, you will be presented with a form. Here is what the fields in - the form mean: - - -
- Name - - This is the name of the flag. This will be displayed - to Bugzilla users who are looking at or setting the flag. - The name may contain any valid Unicode characters except commas - and spaces. - -
- -
- Description - - The description describes the flag in more detail. It is visible - in a tooltip when hovering over a flag either in the Show Bug - or Edit Attachment pages. This field can be as - long as you like, and can contain any character you want. - -
- -
- Category - - - Default behaviour for a newly-created flag is to appear on - products and all components, which is why __Any__:__Any__ - is already entered in the Inclusions box. - If this is not your desired behaviour, you must either set some - exclusions (for products on which you don't want the flag to appear), - or you must remove __Any__:__Any__ from the Inclusions box - and define products/components specifically for this flag. - - - - To create an Inclusion, select a Product from the top drop-down box. - You may also select a specific component from the bottom drop-down box. - (Setting __Any__ for Product translates to, - all the products in this Bugzilla. - Selecting __Any__ in the Component field means - all components in the selected product.) - Selections made, press Include, and your - Product/Component pairing will show up in the Inclusions box on the right. - - - - To create an Exclusion, the process is the same; select a Product from the - top drop-down box, select a specific component if you want one, and press - Exclude. The Product/Component pairing will show up in the - Exclusions box on the right. - - - - This flag will and can be set for any - products/components that appearing in the Inclusions box - (or which fall under the appropriate __Any__). - This flag will not appear (and therefore cannot be set) on - any products appearing in the Exclusions box. - IMPORTANT: Exclusions override inclusions. - - - - You may select a Product without selecting a specific Component, - but you can't select a Component without a Product, or to select a - Component that does not belong to the named Product. If you do so, - Bugzilla will display an error message, even if all your products - have a component by that name. - - - Example: Let's say you have a product called - Jet Plane that has thousands of components. You want - to be able to ask if a problem should be fixed in the next model of - plane you release. We'll call the flag fixInNext. - But, there's one component in Jet Plane, - called Pilot. It doesn't make sense to release a - new pilot, so you don't want to have the flag show up in that component. - So, you include Jet Plane:__Any__ and you exclude - Jet Plane:Pilot. - -
- -
- Sort Key - - Flags normally show up in alphabetical order. If you want them to - show up in a different order, you can use this key set the order on each flag. - Flags with a lower sort key will appear before flags with a higher - sort key. Flags that have the same sort key will be sorted alphabetically, - but they will still be after flags with a lower sort key, and before flags - with a higher sort key. - - - Example: I have AFlag (Sort Key 100), BFlag (Sort Key 10), - CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in - the order: DFlag, BFlag, CFlag, AFlag. - -
- -
- Active - - Sometimes, you might want to keep old flag information in the - Bugzilla database, but stop users from setting any new flags of this type. - To do this, uncheck active. Deactivated - flags will still show up in the UI if they are ?, +, or -, but they - may only be cleared (unset), and cannot be changed to a new value. - Once a deactivated flag is cleared, it will completely disappear from a - bug/attachment, and cannot be set again. - -
- -
- Requestable - - New flags are, by default, requestable, meaning that they - offer users the ? option, as well as + - and -. - To remove the ? option, uncheck requestable. - -
- -
- Specifically Requestable - - By default this box is checked for new flags, meaning that users may make - flag requests of specific individuals. Unchecking this box will remove the - text box next to a flag; if it is still requestable, then requests may - only be made to the wind. Removing this after specific - requests have been made will not remove those requests; that data will - stay in the database (though it will no longer appear to the user). - -
- -
- Multiplicable - - Any flag with Multiplicable set (default for new flags is 'on') - may be set more than once. After being set once, an unset flag - of the same type will appear below it with addl. (short for - additional) before the name. There is no limit to the number of - times a Multiplicable flags may be set on the same bug/attachment. - -
- -
- CC List - - - If you want certain users to be notified every time this flag is - set to ?, -, +, or unset, add them here. This is a comma-separated - list of email addresses that need not be restricted to Bugzilla usernames. - -
- -
- Grant Group - - When this field is set to some given group, only users in the group - can set the flag to + and -. This - field does not affect who can request or cancel the flag. For that, - see the Request Group field below. If this field - is left blank, all users can set or delete this flag. This field is - useful for restricting which users can approve or reject requests. - -
- -
- Request Group - - When this field is set to some given group, only users in the group - can request or cancel this flag. Note that this field has no effect - if the grant group field is empty. You can set the - value of this field to a different group, but both fields have to be - set to a group for this field to have an effect. - -
-
- -
- Deleting a Flag - - - When you are at the Administer Flag Types screen, - you will be presented with a list of Bug flags and a list of Attachment - Flags. - - - To delete a flag, click on the Delete link next to - the flag description. - - - - Once you delete a flag, it is gone from - your Bugzilla. All the data for that flag will be deleted. - Everywhere that flag was set, it will disappear, - and you cannot get that data back. If you want to keep flag data, - but don't want anybody to set any new flags or change current flags, - unset active in the flag Edit form. - - -
- -
- - - -
- -
- Keywords - - - The administrator can define keywords which can be used to tag and - categorise bugs. For example, the keyword "regression" is commonly used. - A company might have a policy stating all regressions - must be fixed by the next release - this keyword can make tracking those - bugs much easier. - - - Keywords are global, rather than per-product. If the administrator changes - a keyword currently applied to any bugs, the keyword cache must be rebuilt - using the script. Currently keywords cannot - be marked obsolete to prevent future usage. - - - Keywords can be created, edited or deleted by clicking the "Keywords" - link in the admin page. There are two fields for each keyword - the keyword - itself and a brief description. Once created, keywords can be selected - and applied to individual bugs in that bug's "Details" section. - -
- -
- Custom Fields - - - The release of Bugzilla 3.0 added the ability to create Custom Fields. - Custom Fields are treated like any other field - they can be set in bugs - and used for search queries. Administrators should keep in mind that - adding too many fields can make the user interface more complicated and - harder to use. Custom Fields should be added only when necessary and with - careful consideration. - - - - Before adding a Custom Field, make sure that Bugzilla cannot already - do the desired behavior. Many Bugzilla options are not enabled by - default, and many times Administrators find that simply enabling - certain options that already exist is sufficient. - - - - Administrators can manage Custom Fields using the - Custom Fields link on the Administration page. The Custom - Fields administration page displays a list of Custom Fields, if any exist, - and a link to "Add a new custom field". - - -
- Adding Custom Fields - - - To add a new Custom Field, click the "Add a new custom field" link. This - page displays several options for the new field, described below. - - - - The following attributes must be set for each new custom field: - - - - Name: - The name of the field in the database, used internally. This name - MUST begin with cf_ to prevent confusion with - standard fields. If this string is omitted, it will - be automatically added to the name entered. - - - - - - Description: - A brief string which is used as the label for this Custom Field. - That is the string that users will see, and should be - short and explicit. - - - - - - Type: - The type of field to create. There are - several types available: - - - Bug ID: - - - A field where you can enter the ID of another bug from - the same Bugzilla installation. To point to a bug in a remote - installation, use the See Also field instead. - - - - - - Large Text Box: - - - A multiple line box for entering free text. - - - - - - Free Text: - - - A single line box for entering free text. - - - - - - Multiple-Selection Box: - - - A list box where multiple options - can be selected. After creating this field, it must be edited - to add the selection options. See - for information about - editing legal values. - - - - - - Drop Down: - - - A list box where only one option can be selected. - After creating this field, it must be edited to add the - selection options. See - for information about - editing legal values. - - - - - - Date/Time: - - - A date field. This field appears with a - calendar widget for choosing the date. - - - - - - - - - - Sortkey: - Integer that determines in which order Custom Fields are - displayed in the User Interface, especially when viewing a bug. - Fields with lower values are displayed first. - - - - - - Reverse Relationship Description: - When the custom field is of type Bug ID, you can - enter text here which will be used as label in the referenced - bug to list bugs which point to it. This gives you the ability - to have a mutual relationship between two bugs. - - - - - - Can be set on bug creation: - Boolean that determines whether this field can be set on - bug creation. If not selected, then a bug must be created - before this field can be set. See - for information about filing bugs. - - - - - - Displayed in bugmail for new bugs: - Boolean that determines whether the value set on this field - should appear in bugmail when the bug is filed. This attribute - has no effect if the field cannot be set on bug creation. - - - - - - Is obsolete: - Boolean that determines whether this field should - be displayed at all. Obsolete Custom Fields are hidden. - - - - - - Is mandatory: - Boolean that determines whether this field must be set. - For single and multi-select fields, this means that a (non-default) - value must be selected, and for text and date fields, some text - must be entered. - - - - - - Field only appears when: - A custom field can be made visible when some criteria is met. - For instance, when the bug belongs to one or more products, - or when the bug is of some given severity. If left empty, then - the custom field will always be visible, in all bugs. - - - - - - Field that controls the values that appear in this field: - When the custom field is of type Drop Down or - Multiple-Selection Box, you can restrict the - availability of the values of the custom field based on the - value of another field. This criteria is independent of the - criteria used in the Field only appears when - setting. For instance, you may decide that some given value - valueY is only available when the bug status - is RESOLVED while the value valueX should - always be listed. - Once you have selected the field which should control the - availability of the values of this custom field, you can - edit values of this custom field to set the criteria, see - . - - - - -
- -
- Editing Custom Fields - - - As soon as a Custom Field is created, its name and type cannot be - changed. If this field is a drop down menu, its legal values can - be set as described in . All - other attributes can be edited as described above. - -
- -
- Deleting Custom Fields - - - Only custom fields which are marked as obsolete, and which never - have been used, can be deleted completely (else the integrity - of the bug history would be compromised). For custom fields marked - as obsolete, a "Delete" link will appear in the Action - column. If the custom field has been used in the past, the deletion - will be rejected. But marking the field as obsolete is sufficient - to hide it from the user interface entirely. - -
-
- -
- Legal Values - - - Legal values for the operating system, platform, bug priority and - severity, custom fields of type Drop Down and - Multiple-Selection Box (see ), - as well as the list of valid bug statuses and resolutions can be - customized from the same interface. You can add, edit, disable and - remove values which can be used with these fields. - - -
- Viewing/Editing legal values - - Editing legal values requires admin privileges. - Select "Field Values" from the Administration page. A list of all - fields, both system fields and Custom Fields, for which legal values - can be edited appears. Click a field name to edit its legal values. - - - There is no limit to how many values a field can have, but each value - must be unique to that field. The sortkey is important to display these - values in the desired order. - - - When the availability of the values of a custom field is controlled - by another field, you can select from here which value of the other field - must be set for the value of the custom field to appear. - -
- -
- Deleting legal values - - Legal values from Custom Fields can be deleted, but only if the - following two conditions are respected: - - - - - The value is not used by default for the field. - - - - No bug is currently using this value. - - - - - If any of these conditions is not respected, the value cannot be deleted. - The only way to delete these values is to reassign bugs to another value - and to set another value as default for the field. - -
-
- -
- Bug Status Workflow - - - The bug status workflow is no longer hardcoded but can be freely customized - from the web interface. Only one bug status cannot be renamed nor deleted, - UNCONFIRMED, but the workflow involving it is free. The configuration - page displays all existing bug statuses twice, first on the left for bug - statuses we come from and on the top for bug statuses we move to. - If the checkbox is checked, then the transition between the two bug statuses - is legal, else it's forbidden independently of your privileges. The bug status - used for the "duplicate_or_move_bug_status" parameter must be part of the - workflow as that is the bug status which will be used when duplicating or - moving a bug, so it must be available from each bug status. - - - When the workflow is set, the "View Current Triggers" link below the table - lets you set which transitions require a comment from the user. - -
- -
- Voting - - All of the code for voting in Bugzilla has been moved into an - extension, called "Voting", in the extensions/Voting/ - directory. To enable it, you must remove the disabled - file from that directory, and run checksetup.pl. - - 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 - "CONFIRMED", users of the bug system can help high-priority bugs garner - attention so they don't sit for a long time awaiting triage. - - To modify Voting settings: - - - - Navigate to the "Edit product" screen for the Product you - wish to modify - - - - Maximum Votes per person: - Setting this field to "0" disables voting. - - - - Maximum Votes a person can put on a single - bug: - 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. - - - - Number of votes a bug in this product needs to - automatically get out of the UNCONFIRMED state: - Setting this field to "0" disables the automatic move of - bugs from UNCONFIRMED to CONFIRMED. - - - - - Once you have adjusted the values to your preference, click - "Update". - - -
- -
- Quips - - - Quips are small text messages that can be configured to appear - next to search results. A Bugzilla installation can have its own specific - quips. Whenever a quip needs to be displayed, a random selection - is made from the pool of already existing quips. - - - - Quip submission is controlled by the quip_list_entry_control - parameter. It has several possible values: open, moderated, or closed. - In order to enable quips approval you need to set this parameter to - "moderated". In this way, users are free to submit quips for addition - but an administrator must explicitly approve them before they are - actually used. - - - - In order to see the user interface for the quips, it is enough to click - on a quip when it is displayed together with the search results. Or - it can be seen directly in the browser by visiting the quips.cgi URL - (prefixed with the usual web location of the Bugzilla installation). - Once the quip interface is displayed, it is enough to click the - "view and edit the whole quip list" in order to see the administration - page. A page with all the quips available in the database will - be displayed. - - - - Next to each quip there is a checkbox, under the - "Approved" column. Quips who have this checkbox checked are - already approved and will appear next to the search results. - The ones that have it unchecked are still preserved in the - database but they will not appear on search results pages. - User submitted quips have initially the checkbox unchecked. - - - - Also, there is a delete link next to each quip, - which can be used in order to permanently delete a quip. - - - - Display of quips is controlled by the display_quips - user preference. Possible values are "on" and "off". - -
- -
- Groups and Group Security - - - Groups allow for separating bugs into logical divisions. - Groups are typically used - to isolate bugs that should only be seen by certain people. For - example, a company might create a different group for each one of its customers - or partners. Group permissions could be set so that each partner or customer would - only have access to their own bugs. Or, groups might be used to create - variable access controls for different departments within an organization. - Another common use of groups is to associate groups with products, - creating isolation and access control on a per-product basis. - - - - Groups and group behaviors are controlled in several places: - - - - - - - The group configuration page. To view or edit existing groups, or to - create new groups, access the "Groups" link from the "Administration" - page. This section of the manual deals primarily with the aspect of - group controls accessed on this page. - - - - - - Global configuration parameters. Bugzilla has several parameters - that control the overall default group behavior and restriction - levels. For more information on the parameters that control - group behavior globally, see . - - - - - - - Product association with groups. Most of the functionality of groups - and group security is controlled at the product level. Some aspects - of group access controls for products are discussed in this section, - but for more detail see . - - - - - - Group access for users. See for - details on how users are assigned group access. - - - - - - - Group permissions are such that if a bug belongs to a group, only members - of that group can see the bug. If a bug is in more than one group, only - members of all the groups that the bug is in can see - the bug. For information on granting read-only access to certain people and - full edit access to others, see . - - - - - By default, bugs can also be seen by the Assignee, the Reporter, and - by everyone on the CC List, regardless of whether or not the bug would - typically be viewable by them. Visibility to the Reporter and CC List can - be overridden (on a per-bug basis) by bringing up the bug, finding the - section that starts with Users in the roles selected below... - and un-checking the box next to either 'Reporter' or 'CC List' (or both). - - - -
- Creating Groups - - - To create a new group, follow the steps below: - - - - - - - Select the Administration link in the page footer, - and then select the Groups link from the - Administration page. - - - - - - A table of all the existing groups is displayed. Below the table is a - description of all the fields. To create a new group, select the - Add Group link under the table of existing groups. - - - - - - There are five fields to fill out. These fields are documented below - the form. Choose a name and description for the group. Decide whether - this group should be used for bugs (in all likelihood this should be - selected). Optionally, choose a regular expression that will - automatically add any matching users to the group, and choose an - icon that will help identify user comments for the group. The regular - expression can be useful, for example, to automatically put all users - from the same company into one group (if the group is for a specific - customer or partner). - - - - If User RegExp is filled out, users whose email - addresses match the regular expression will automatically be - members of the group as long as their email addresses continue - to match the regular expression. If their email address changes - and no longer matches the regular expression, they will be removed - from the group. Versions 2.16 and older of Bugzilla did not automatically - remove users who's email addresses no longer matched the RegExp. - - - - - If specifying a domain in the regular expression, end - the regexp with a "$". Otherwise, when granting access to - "@mycompany\.com", access will also be granted to - 'badperson@mycompany.com.cracker.net'. Use the syntax, - '@mycompany\.com$' for the regular expression. - - - - - - - After the new group is created, it can be edited for additional options. - The "Edit Group" page allows for specifying other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group. For more details, see . - - - - -
- -
- Editing Groups and Assigning Group Permissions - - - To access the "Edit Groups" page, select the - Administration link in the page footer, - and then select the Groups link from the Administration page. - A table of all the existing groups is displayed. Click on a group name - you wish to edit or control permissions for. - - - - The "Edit Groups" page contains the same five fields present when - creating a new group. Below that are two additional sections, "Group - Permissions," and "Mass Remove". The "Mass Remove" option simply removes - all users from the group who match the regular expression entered. The - "Group Permissions" section requires further explanation. - - - - The "Group Permissions" section on the "Edit Groups" page contains four sets - of permissions that control the relationship of this group to other - groups. If the 'usevisibilitygroups' parameter is in use (see - ) two additional sets of permissions are displayed. - Each set consists of two select boxes. On the left, a select box - with a list of all existing groups. On the right, a select box listing - all groups currently selected for this permission setting (this box will - be empty for new groups). The way these controls allow groups to relate - to one another is called inheritance. - Each of the six permissions is described below. - - - - - - - - Groups That Are a Member of This Group - - - - - Members of any groups selected here will automatically have - membership in this group. In other words, members of any selected - group will inherit membership in this group. - - - - - - - - - Groups That This Group Is a Member Of - - - - - Members of this group will inherit membership to any group - selected here. For example, suppose the group being edited is - an Admin group. If there are two products (Product1 and Product2) - and each product has its - own group (Group1 and Group2), and the Admin group - should have access to both products, - simply select both Group1 and Group2 here. - - - - - - - - - Groups That Can Grant Membership in This Group - - - - - The members of any group selected here will be able add users - to this group, even if they themselves are not in this group. - - - - - - - - - Groups That This Group Can Grant Membership In - - - - - Members of this group can add users to any group selected here, - even if they themselves are not in the selected groups. - - - - - - - - - Groups That Can See This Group - - - - - Members of any selected group can see the users in this group. - This setting is only visible if the 'usevisibilitygroups' parameter - is enabled on the Bugzilla Configuration page. See - for information on configuring Bugzilla. - - - - - - - - - Groups That This Group Can See - - - - - Members of this group can see members in any of the selected groups. - This setting is only visible if the 'usevisibilitygroups' parameter - is enabled on the the Bugzilla Configuration page. See - for information on configuring Bugzilla. - - - - - - - -
- -
- Assigning Users to Groups - - - A User can become a member of a group in several ways: - - - - - - - The user can be explicitly placed in the group by editing - the user's profile. This can be done by accessing the "Users" page - from the "Administration" page. Use the search form to find the user - you want to edit group membership for, and click on their email - address in the search results to edit their profile. The profile - page lists all the groups, and indicates if the user is a member of - the group either directly or indirectly. More information on indirect - group membership is below. For more details on User administration, - see . - - - - - - The group can include another group of which the user is - a member. This is indicated by square brackets around the checkbox - next to the group name in the user's profile. - See for details on group inheritance. - - - - - - The user's email address can match the regular expression - that has been specified to automatically grant membership to - the group. This is indicated by "*" around the check box by the - group name in the user's profile. - See for details on - the regular expression option when creating groups. - - - - - -
- -
- Assigning Group Controls to Products - - - The primary functionality of groups is derived from the relationship of - groups to products. The concepts around segregating access to bugs with - product group controls can be confusing. For details and examples on this - topic, see . - - -
-
- -
- Checking and Maintaining Database Integrity - - - Over time it is possible for the Bugzilla database to become corrupt - or to have anomalies. - This could happen through normal usage of Bugzilla, manual database - administration outside of the Bugzilla user interface, or from some - other unexpected event. Bugzilla includes a "Sanity Check" script that - can perform several basic database checks, and repair certain problems or - inconsistencies. - - - To run the "Sanity Check" script, log in as an Administrator and click the - "Sanity Check" link in the admin page. Any problems that are found will be - displayed in red letters. If the script is capable of fixing a problem, - it will present a link to initiate the fix. If the script cannot - fix the problem it will require manual database administration or recovery. - - - The "Sanity Check" script can also be run from the command line via the perl - script sanitycheck.pl. The script can also be run as - a cron job. Results will be delivered by email. - - - The "Sanity Check" script should be run on a regular basis as a matter of - best practice. - - - - The "Sanity Check" script is no substitute for a competent database - administrator. It is only designed to check and repair basic database - problems. - - - -
- - - - - diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml deleted file mode 100644 index 707146551..000000000 --- a/docs/en/xml/conventions.xml +++ /dev/null @@ -1,91 +0,0 @@ - - - - %myents; -]> - -
- Document Conventions - - This document uses the following conventions: - - - This is a caution. Make sure to read this to not be in trouble! - - - - This is a hint or tip, especially about some configuration tweaks. - - - - This is just a note, for your information. - - - - This is a warning, something you should take care of. - - - - A filename or a path to a filename is displayed like this: - /path/to/filename.ext - - - - A command to type in the shell is displayed like this: - command --arguments - - - bash$ represents a normal user's prompt under bash shell - - bash# represents a root user's prompt under bash shell - - - A word which is in the glossary will appear like this: - Bugzilla - - - - A sample of code is illustrated like this: - -First Line of Code -Second Line of Code -... - - - - - This documentation is maintained in DocBook 4.2 XML format. - Changes are best submitted as plain text or XML diffs, attached - to a bug filed in the Bugzilla Documentation - component. - -
- - diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml deleted file mode 100644 index c140acf77..000000000 --- a/docs/en/xml/customization.xml +++ /dev/null @@ -1,612 +0,0 @@ - - - - %myents; -]> - - - Customizing Bugzilla - -
- Bugzilla Extensions - - - One of the best ways to customize Bugzilla is by writing a Bugzilla - Extension. Bugzilla Extensions let you modify both the code and - UI of Bugzilla in a way that can be distributed to other Bugzilla - users and ported forward to future versions of Bugzilla with minimal - effort. - - - - See the Bugzilla Extension - documentation for information on how to write an Extension. - -
- -
- Custom Skins - - - Bugzilla allows you to have multiple skins. These are custom CSS and possibly - also custom images for Bugzilla. To create a new custom skin, you have two - choices: - - - - Make a single CSS file, and put it in the - skins/contrib directory. - - - - - Make a directory that contains all the same CSS file - names as skins/standard/, and put - your directory in skins/contrib/. - - - - - - - After you put the file or the directory there, make sure to run checksetup.pl - so that it can reset the file permissions correctly. - - - After you have installed the new skin, it will show up as an option in the - user's General Preferences. If you would like to force a particular skin on all - users, just select it in the Default Preferences and then uncheck "Enabled" on - the preference. - -
- -
- Template Customization - - - Administrators can configure the look and feel of Bugzilla without - having to edit Perl files or face the nightmare of massive merge - conflicts when they upgrade to a newer version in the future. - - - - Templatization also makes localized versions of Bugzilla possible, - for the first time. It's possible to have Bugzilla's UI language - determined by the user's browser. More information is available in - . - - -
- Template Directory Structure - - The template directory structure starts with top level directory - named template, which contains a directory - for each installed localization. The next level defines the - language used in the templates. Bugzilla comes with English - templates, so the directory name is en, - and we will discuss template/en throughout - the documentation. Below template/en is the - default directory, which contains all the - standard templates shipped with Bugzilla. - - - - - A directory data/templates also exists; - this is where Template Toolkit puts the compiled versions of - the templates from either the default or custom directories. - Do not directly edit the files in this - directory, or all your changes will be lost the next time - Template Toolkit recompiles the templates. - - -
- -
- Choosing a Customization Method - - If you want to edit Bugzilla's templates, the first decision - you must make is how you want to go about doing so. There are two - choices, and which you use depends mainly on the scope of your - modifications, and the method you plan to use to upgrade Bugzilla. - - - - The first method of making customizations is to directly edit the - templates found in template/en/default. - This is probably the best way to go about it if you are going to - be upgrading Bugzilla through Bzr, because if you then execute - a bzr update, any changes you have made will - be merged automagically with the updated versions. - - - - - If you use this method, and Bzr conflicts occur during an - update, the conflicted templates (and possibly other parts - of your installation) will not work until they are resolved. - - - - - The second method is to copy the templates to be modified - into a mirrored directory structure under - template/en/custom. Templates in this - directory structure automatically override any identically-named - and identically-located templates in the - default directory. - - - - - The custom directory does not exist - at first and must be created if you want to use it. - - - - - The second method of customization should be used if you - use the overwriting method of upgrade, because otherwise - your changes will be lost. This method may also be better if - you are using the Bzr 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. - - - - Using this method, your installation may break if incompatible - changes are made to the template interface. Such changes should - be documented in the release notes, provided you are using a - stable release of Bugzilla. If you use using unstable code, you will - need to deal with this one yourself, although if possible the changes - will be mentioned before they occur in the deprecations section of the - previous stable release's release notes. - - - - - Regardless of which method you choose, it is recommended that - you run ./checksetup.pl after - editing any templates in the template/en/default - directory, and after creating or editing any templates in the - custom directory. - - - - - - It is required that you run - ./checksetup.pl after creating a new - template in the custom directory. Failure - to do so will raise an incomprehensible error message. - - -
- -
- How To Edit Templates - - - - 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 - Developers' - Guide. - - - - - 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 - Template Toolkit home - page. - - - - One thing you should take particular care about is the need - to properly HTML filter data that has been passed into the template. - This means that if the data can possibly contain special HTML characters - such as <, and the data was not intended to be HTML, they need to be - converted to entity form, i.e. &lt;. You use the 'html' filter in the - Template Toolkit to do this (or the 'uri' filter to encode special - characters in URLs). If you forget, you may open up your installation - to cross-site scripting attacks. - - - - 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. - - -
- - -
- Template Formats and Types - - - Some CGI's have the ability to use more than one template. For example, - buglist.cgi can output itself as RDF, or as two - formats of HTML (complex and simple). The mechanism that provides this - feature is extensible. - - - - Bugzilla can support different types of output, which again can have - multiple formats. In order to request a certain type, you can append - the &ctype=<contenttype> (such as rdf or html) to the - <cginame>.cgi URL. If you would like to - retrieve a certain format, you can use the &format=<format> - (such as simple or complex) in the URL. - - - - To see if a CGI supports multiple output formats and types, grep the - CGI for get_format. If it's not present, adding - multiple format/type support isn't too hard - see how it's done in - other CGIs, e.g. config.cgi. - - - - 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. - - - - Write your template in whatever markup or text style is appropriate. - - - - You now need to decide what content type you want your template - served as. The content types are defined in the - Bugzilla/Constants.pm file in the - contenttypes - constant. If your content type is not there, add it. Remember - the three- or four-letter tag assigned to your content type. - This tag will be part of the template filename. - - - - - After adding or changing a content type, it's suitable to edit - Bugzilla/Constants.pm in order to reflect - the changes. Also, the file should be kept up to date after an - upgrade if content types have been customized in the past. - - - - - Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl. - Try out the template by calling the CGI as - <cginame>.cgi?format=<formatname>&ctype=<type> . - -
- - -
- Particular Templates - - - There are a few templates you may be particularly interested in - customizing for your installation. - - - - index.html.tmpl: - This is the Bugzilla front page. - - - - global/header.html.tmpl: - 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. - - - - global/banner.html.tmpl: - 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. - - - - global/footer.html.tmpl: - 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. - - - - global/variables.none.tmpl: - This defines a list of terms that may be changed in order to - brand the Bugzilla instance In this way, terms - like bugs can be replaced with issues - across the whole Bugzilla installation. The name - Bugzilla and other words can be customized as well. - - - - list/table.html.tmpl: - This template controls the appearance of the bug lists created - by Bugzilla. Editing this template allows per-column control of - the width and title of a column, the maximum display length of - each entry, and the wrap behaviour of long entries. - For long bug lists, Bugzilla inserts a 'break' every 100 bugs by - default; this behaviour is also controlled by this template, and - that value can be modified here. - - - - bug/create/user-message.html.tmpl: - 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. - - - - bug/process/midair.html.tmpl: - 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. - - - - bug/create/create.html.tmpl and - bug/create/comment.txt.tmpl: - You may not wish to go to the effort of creating custom fields in - Bugzilla, yet you want to make sure that each bug report contains - a number of pieces of important information for which there is not - a special field. The bug entry system has been designed in an - extensible fashion to enable you to add arbitrary HTML widgets, - such as drop-down lists or textboxes, to the bug entry page - and have their values appear formatted in the initial comment. - A hidden field that indicates the format should be added inside - the form in order to make the template functional. Its value should - be the suffix of the template filename. For example, if the file - is called create-cust.html.tmpl, then - <input type="hidden" name="format" value="cust"> - should be used inside the form. - - - - An example of this is the mozilla.org - guided - bug submission form. The code for this comes with the Bugzilla - distribution as an example for you to copy. It can be found in the - files - create-guided.html.tmpl and - comment-guided.html.tmpl. - - - - So to use this feature, create a custom template for - enter_bug.cgi. The default template, on which you - could base it, is - custom/bug/create/create.html.tmpl. - Call it create-<formatname>.html.tmpl, and - in it, add widgets for each piece of information you'd like - collected - such as a build number, or set of steps to reproduce. - - - - Then, create a template like - custom/bug/create/comment.txt.tmpl, and call it - comment-<formatname>.txt.tmpl. This - template should reference the form fields you have created using - the syntax [% form.<fieldname> %]. When a - bug report is - submitted, the initial comment attached to the bug report will be - formatted according to the layout of this template. - - - - For example, if your custom enter_bug template had a field - <input type="text" name="buildid" size="30"> - and then your comment.txt.tmpl had - BuildID: [% form.buildid %] - then something like - BuildID: 20020303 - would appear in the initial comment. - -
- - -
- Configuring Bugzilla to Detect the User's Language - - Bugzilla honours the user's Accept: HTTP header. You can install - templates in other languages, and Bugzilla will pick the most appropriate - according to a priority order defined by you. Many - language templates can be obtained from . Instructions - for submitting new languages are also available from that location. - -
- -
- -
- Customizing Who Can Change What - - - - This feature should be considered experimental; the Bugzilla code you - will be changing is not stable, and could change or move between - versions. Be aware that if you make modifications as outlined here, - you may have - to re-make them or port them if Bugzilla changes internally between - versions, and you upgrade. - - - - - 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. - - - - By default, assignees, QA owners and users - with editbugs privileges can edit all fields of bugs, - except group restrictions (unless they are members of the groups they - are trying to change). Bug reporters also have the ability to edit some - fields, but in a more restrictive manner. Other users, without - editbugs privileges, cannot edit - bugs, except to comment and add themselves to the CC list. - - - - For maximum flexibility, customizing this means editing Bugzilla's Perl - code. This gives the administrator complete control over exactly who is - allowed to do what. The relevant method is called - check_can_change_field(), - and is found in Bug.pm in your - Bugzilla/ directory. If you open that file and search for - sub check_can_change_field, you'll find it. - - - - 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: - # Allow the assignee to change anything. - if ($ownerid eq $whoid) { - return 1; - } - It's fairly obvious what this piece of code does. - - - - So, how does one go about changing this function? Well, simple changes - can be made just by removing pieces - for example, if you wanted to - prevent any user adding a comment to a bug, just remove the lines marked - Allow anyone to change comments. If you don't want the - Reporter to have any special rights on bugs they have filed, just - remove the entire section that deals with the Reporter. - - - - 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.: - if ($field eq "qacontact") { - if (Bugzilla->user->in_group("quality_assurance")) { - return 1; - } - else { - return 0; - } - } - This says that only users in the group "quality_assurance" can change - the QA Contact field of a bug. - - - - Getting more weird: - user->email =~ /.*\@example\.com$/)) - { - if ($oldvalue eq "P1") { - return 1; - } - else { - return 0; - } - }]]> - 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. - - - - - If you are modifying process_bug.cgi in any - way, do not change the code that is bounded by DO_NOT_CHANGE blocks. - Doing so could compromise security, or cause your installation to - stop working entirely. - - - - - For a list of possible field names, look at the bugs table in the - database. If you need help writing custom rules for your organization, - ask in the newsgroup. - -
- -
- Integrating Bugzilla with Third-Party Tools - - - Many utilities and applications can integrate with Bugzilla, - either on the client- or server-side. None of them are maintained - by the Bugzilla community, nor are they tested during our - QA tests, so use them at your own risk. They are listed at - . - -
- - - - diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml deleted file mode 100644 index 4d10f28f0..000000000 --- a/docs/en/xml/gfdl.xml +++ /dev/null @@ -1,457 +0,0 @@ - - - - %myents; -]> - - - GNU Free Documentation License - - - - - Version 1.1, March 2000 - -
- Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, - Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and - distribute verbatim copies of this license document, but changing it is - not allowed. -
- -
- Preamble - - 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. - - 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. - - 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. -
- -
- Applicability and Definition - - 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". - - 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. - - 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. - - 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. - - 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. - - 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". - - 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. - - 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. -
- -
- Verbatim Copying - - 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. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. -
- -
- Copying in Quantity - - 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. - - 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. - - 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. - - 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. -
- -
- Modifications - - 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: - - - - 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. - - - - 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). - - - - State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - - - Preserve all the copyright notices of the Document. - - - - Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - - - 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. - - - - Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - - - - Include an unaltered copy of this License. - - - - 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. - - - - 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. - - - - 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. - - - - 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. - - - - Delete any section entitled "Endorsements". Such a section may - not be included in the Modified Version. - - - - Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - - - 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. - - 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. - - 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. - - 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. -
- -
- Combining Documents - - 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. - - 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. - - 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." -
- -
- Collections of Documents - - 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. - - 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. -
- -
- Aggregation with Independent Works - - 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. - - 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. -
- -
- Translation - - 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. -
- -
- Termination - - 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. -
- -
- Future Revisions of this License - - 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 - . - - 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. -
- -
- How to use this License for your documents - - 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: - -
- 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". -
- - 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. - - 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. -
- - - diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml deleted file mode 100644 index 5458fa32d..000000000 --- a/docs/en/xml/glossary.xml +++ /dev/null @@ -1,561 +0,0 @@ - - - - %myents; -]> - - - - 0-9, high ascii - - - .htaccess - - - Apache web server, and other NCSA-compliant web servers, - observe the convention of using files in directories called - .htaccess - - to restrict access to certain files. In Bugzilla, they are used - to keep secret files which would otherwise - compromise your installation - e.g. the - localconfig - file contains the password to your database. - curious. - - - - - - A - - - Apache - - - 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 - a patchy - version of the original - NCSA - world-wide-web server. - - - Useful Directives when configuring Bugzilla - - - AddHandler - - Tell Apache that it's OK to run CGI scripts. - - - - AllowOverride - Options - - 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 .htaccess - overrides. - - - - - DirectoryIndex - - Used to tell Apache what files are indexes. If you can - not add index.cgi to the list of valid files, - you'll need to set $index_html to - 1 in localconfig so - ./checksetup.pl will create an - index.html that redirects to - index.cgi. - - - - - ScriptInterpreterSource - - Used when running Apache on windows so the shebang line - doesn't have to be changed in every Bugzilla script. - - - - - - For more information about how to configure Apache for Bugzilla, - see . - - - - - - - B - - - Bug - - - A - bug - - in Bugzilla refers to an issue entered into the database which has an - associated number, assignments, comments, etc. Some also refer to a - tickets - or - issues; - in the context of Bugzilla, they are synonymous. - - - - - Bug Number - - - 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. - - - - - Bugzilla - - - Bugzilla is the world-leading free software bug tracking system. - - - - - - - C - - - Common Gateway Interface - CGI - - CGI 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 CGI application. - - - - - - Component - - - 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). - - - - - Comprehensive Perl Archive Network - CPAN - - - - - CPAN - - stands for the - Comprehensive Perl Archive Network. - CPAN maintains a large number of extremely useful - Perl - modules - encapsulated chunks of code for performing a - particular task. - - - - - contrib - - - The contrib directory is - a location to put scripts that have been contributed to Bugzilla but - are not a part of the official distribution. These scripts are written - by third parties and may be in languages other than perl. For those - that are in perl, there may be additional modules or other requirements - than those of the official distribution. - - Scripts in the contrib - directory are not officially supported by the Bugzilla team and may - break in between versions. - - - - - - - - - D - - - daemon - - - 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. - mysqld, - the MySQL server, and - apache, - a web server, are generally run as daemons. - - - - - DOS Attack - - - A DOS, or Denial of Service attack, is when a user attempts to - deny access to a web server by repeatedly accessing a page or sending - malformed requests to a webserver. A D-DOS, or - Distributed Denial of Service attack, is when these requests come - from multiple sources at the same time. Unfortunately, these are much - more difficult to defend against. - - - - - - - - G - - - Groups - - - The word - Groups - - 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 - Products - in the - Bugzilla - database. - - - - - - J - - - JavaScript - - JavaScript is cool, we should talk about it. - - - - - - - M - - - Message Transport Agent - MTA - - - A Message Transport Agent is used to control the flow of email on a system. - The Email::Send - Perl module, which Bugzilla uses to send email, can be configured to - use many different underlying implementations for actually sending the - mail using the parameter. - - - - - - MySQL - - - MySQL is one of the supported - RDBMS for Bugzilla. MySQL - can be downloaded from . While you - should familiarize yourself with all of the documentation, some high - points are: - - - - Backup - - Methods for backing up your Bugzilla database. - - - - - Option Files - - Information about how to configure MySQL using - my.cnf. - - - - - Privilege System - - Information about how to protect your MySQL server. - - - - - - - - - - P - - - Perl Package Manager - PPM - - - - - - - - - Product - - - 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. - - - - - Perl - - - 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. - Bugzilla - - is maintained in Perl. - - - - - - Q - - - QA - - - - QA, - Q/A, and - Q.A. - are short for - Quality Assurance. - 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 - QA Contact - - field in a bug. - - - - - - R - - - Relational DataBase Management System - RDBMS - - - A relational database management system is a database system - that stores information in tables that are related to each other. - - - - - - Regular Expression - regexp - - - A regular expression is an expression used for pattern matching. - Documentation - - - - - - - S - - - Service - - - In Windows NT environment, a boot-time background application - is referred to as a service. These are generally managed through the - control panel while logged in as an account with - Administrator level capabilities. For more - information, consult your Windows manual or the MSKB. - - - - - - - SGML - - - - - SGML - - stands for - Standard Generalized Markup Language. - Created in the 1980's to provide an extensible means to maintain - documentation based upon content instead of presentation, - SGML - - has withstood the test of time as a robust, powerful language. - - XML - - - is the - baby brother - - of SGML; any valid - XML - - document it, by definition, a valid - SGML - - document. The document you are reading is written and maintained in - SGML, - and is also valid - XML - - if you modify the Document Type Definition. - - - - - - T - - - Target Milestone - - - Target Milestones are Product goals. They are configurable on a - per-Product basis. Most software development houses have a concept of - - milestones - - 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. - - - - - Tool Command Language - TCL - - 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. - - - - - - - Z - - - Zarro Boogs Found - - - 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: - - -
- Terry Weissman - 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. - - - 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... - -
- - - - - - - diff --git a/docs/en/xml/index.xml b/docs/en/xml/index.xml deleted file mode 100644 index e71a504a8..000000000 --- a/docs/en/xml/index.xml +++ /dev/null @@ -1,27 +0,0 @@ - - diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml deleted file mode 100644 index d68133fb7..000000000 --- a/docs/en/xml/installation.xml +++ /dev/null @@ -1,2453 +0,0 @@ - - - - %myents; -]> - - - Installing Bugzilla - -
- Installation - - - If you just want to use Bugzilla, - you do not need to install it. None of this chapter is relevant to - you. Ask your Bugzilla administrator for the URL to access it from - your web browser. - - - - The Bugzilla server software is usually installed on Linux or - Solaris. - If you are installing on another OS, check - before you start your installation to see if there are any special - instructions. - - - This guide assumes that you have administrative access to the - Bugzilla machine. It not possible to - install and run Bugzilla itself without administrative access except - in the very unlikely event that every single prerequisite is - already installed. - - - - The installation process may make your machine insecure for - short periods of time. Make sure there is a firewall between you - and the Internet. - - - - - You are strongly recommended to make a backup of your system - before installing Bugzilla (and at regular intervals thereafter :-). - - - In outline, the installation proceeds as follows: - - - - - Install Perl - (&min-perl-ver; or above) - - - - Install a Database Engine - - - - Install a Webserver - - - - Install Bugzilla - - - - Install Perl modules - - - - - Install a Mail Transfer Agent - (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) - - - - Configure all of the above. - - - - -
- Perl - - Installed Version Test: perl -v - - Any machine that doesn't have Perl on it is a sad machine indeed. - If you don't have it and your OS doesn't provide official packages, - visit . - Although Bugzilla runs with Perl &min-perl-ver;, - it's a good idea to be using the latest stable version. - -
- -
- Database Engine - - - Bugzilla supports MySQL, PostgreSQL and Oracle as database servers. - You only require one of these systems to make use of Bugzilla. - - -
- MySQL - Installed Version Test: mysql -V - - - If you don't have it and your OS doesn't provide official packages, - visit . You need MySQL version - &min-mysql-ver; or higher. - - - - Many of the binary - versions of MySQL store their data files in - /var. - On some Unix systems, this is part of a smaller root partition, - and may not have room for your bug database. To change the data - directory, you have to build MySQL from source yourself, and - set it as an option to configure. - - - If you install from something other than a packaging/installation - system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe - (Windows Executable), or .msi (Windows Installer), make sure the MySQL - server is started when the machine boots. - -
- -
- PostgreSQL - Installed Version Test: psql -V - - - If you don't have it and your OS doesn't provide official packages, - visit . You need PostgreSQL - version &min-pg-ver; or higher. - - - If you install from something other than a packaging/installation - system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe - (Windows Executable), or .msi (Windows Installer), make sure the - PostgreSQL server is started when the machine boots. - -
- -
- Oracle - - Installed Version Test: select * from v$version - (you first have to log in into your DB) - - - - If you don't have it and your OS doesn't provide official packages, - visit . You need Oracle - version &min-oracle-ver; or higher. - - - - If you install from something other than a packaging/installation - system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe - (Windows Executable), or .msi (Windows Installer), make sure the - Oracle server is started when the machine boots. - -
-
- -
- Web Server - - Installed Version Test: view the default welcome page at - http://<your-machine>/ - - - You have freedom of choice here, pretty much any web server that - is capable of running CGI - scripts will work. - However, we strongly recommend using the Apache web server - (either 1.3.x or 2.x), and the installation instructions usually assume - you are using it. If you have got Bugzilla working using another web server, - please share your experiences with us by filing a bug in - Bugzilla Documentation. - - - - If you don't have Apache and your OS doesn't provide official packages, - visit . - - -
- -
- Bugzilla - - - Download a Bugzilla tarball - (or check it out from Bzr) - and place it in a suitable directory, accessible by the default web server user - (probably apache or www). - Good locations are either directly in the web server's document directories or - in /usr/local with a symbolic link to the web server's - document directories or an alias in the web server's configuration. - - - - The default Bugzilla distribution is NOT designed to be placed - in a cgi-bin directory. This - includes any directory which is configured using the - directive of Apache. - - - - Once all the files are in a web accessible directory, make that - directory writable by your web server's user. This is a temporary step - until you run the - checksetup.pl - script, which locks down your installation. -
- -
- Perl Modules - - Bugzilla's installation process is based - on a script called checksetup.pl. - The first thing it checks is whether you have appropriate - versions of all the required - Perl modules. The aim of this section is to pass this check. - When it passes, proceed to . - - - - At this point, you need to su to root. You should - remain as root until the end of the install. To check you have the - required modules, run: - - - bash# ./checksetup.pl --check-modules - - - checksetup.pl will print out a list of the - required and optional Perl modules, together with the versions - (if any) installed on your machine. - The list of required modules is reasonably long; however, you - may already have several of them installed. - - - - The preferred way to install missing Perl modules is to use the package - manager provided by your operating system (e.g rpm or - yum on Linux distros, or ppm on Windows - if using ActivePerl, see ). - If some Perl modules are still missing or are too old, then we recommend - using the install-module.pl script (doesn't work - with ActivePerl on Windows). If for some reason you really need to - install the Perl modules manually, see - . For instance, on Unix, - you invoke install-module.pl as follows: - - - bash# perl install-module.pl <modulename> - - - Many people complain that Perl modules will not install for - them. Most times, the error messages complain that they are missing a - file in - @INC. - 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 - are - the local UNIX sysadmin, please consult the newsgroup/mailing list - for further assistance or hire someone to help you out. - - - - If you are using a package-based system, and attempting to install the - Perl modules from CPAN, you may need to install the "development" packages for - MySQL and GD before attempting to install the related Perl modules. The names of - these packages will vary depending on the specific distribution you are using, - but are often called <packagename>-devel. - - - - Here is a complete list of modules and their minimum versions. - Some modules have special installation notes, which follow. - - - Required Perl modules: - - - - - CGI (&min-cgi-ver;) - - - - - - Date::Format (&min-date-format-ver;) - - - - - - DateTime (&min-datetime-ver;) - - - - - - DateTime::TimeZone (&min-datetime-timezone-ver;) - - - - - - DBI (&min-dbi-ver;) - - - - - - DBD::mysql (&min-dbd-mysql-ver;) if using MySQL - - - - - - DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL - - - - - - DBD::Oracle (&min-dbd-oracle-ver;) if using Oracle - - - - - - Digest::SHA (&min-digest-sha-ver;) - - - - - - Email::Send (&min-email-send-ver;) - - - - - - Email::MIME (&min-email-mime-ver;) - - - - - - Template (&min-template-ver;) - - - - - - URI (&min-uri-ver;) - - - - - Optional Perl modules: - - - - GD (&min-gd-ver;) for bug charting - - - - - - Template::Plugin::GD::Image - (&min-template-plugin-gd-image-ver;) for Graphical Reports - - - - - - Chart::Lines (&min-chart-lines-ver;) for bug charting - - - - - - GD::Graph (&min-gd-graph-ver;) for bug charting - - - - - - GD::Text (&min-gd-text-ver;) for bug charting - - - - - - XML::Twig (&min-xml-twig-ver;) for bug import/export - - - - - - MIME::Parser (&min-mime-parser-ver;) for bug import/export - - - - - - LWP::UserAgent - (&min-lwp-useragent-ver;) for Automatic Update Notifications - - - - - - PatchReader (&min-patchreader-ver;) for pretty HTML view of patches - - - - - - Net::LDAP - (&min-net-ldap-ver;) for LDAP Authentication - - - - - - Authen::SASL - (&min-authen-sasl-ver;) for SASL Authentication - - - - - - Authen::Radius - (&min-authen-radius-ver;) for RADIUS Authentication - - - - - - SOAP::Lite (&min-soap-lite-ver;) for the web service interface - - - - - - JSON::RPC - (&min-json-rpc-ver;) for the JSON-RPC interface - - - - - - Test::Taint - (&min-test-taint-ver;) for the web service interface - - - - - - HTML::Parser - (&min-html-parser-ver;) for More HTML in Product/Group Descriptions - - - - - - HTML::Scrubber - (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions - - - - - - Email::Reply - (&min-email-reply-ver;) for Inbound Email - - - - - - TheSchwartz - (&min-theschwartz-ver;) for Mail Queueing - - - - - - Daemon::Generic - (&min-daemon-generic-ver;) for Mail Queueing - - - - - - mod_perl2 - (&min-mod_perl2-ver;) for mod_perl - - - - -
- -
- Mail Transfer Agent (MTA) - - - Bugzilla is dependent on the availability of an e-mail system for its - user authentication and for other tasks. - - - - - This is not entirely true. It is possible to completely disable - email sending, or to have Bugzilla store email messages in a - file instead of sending them. However, this is mainly intended - for testing, as disabling or diverting email on a production - machine would mean that users could miss important events (such - as bug changes or the creation of new accounts). - - - - For more information, see the mail_delivery_method parameter - in . - - - - - On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will - suffice. Sendmail, Postfix, qmail and Exim are examples of common - MTAs. Sendmail is the original Unix MTA, but the others are easier to - configure, and therefore many people replace Sendmail with Postfix or - Exim. They are drop-in replacements, so Bugzilla will not - distinguish between them. - - - - If you are using Sendmail, version 8.7 or higher is required. - If you are using a Sendmail-compatible MTA, it must be congruent with - at least version 8.7 of Sendmail. - - - - Consult the manual for the specific MTA you choose for detailed - installation instructions. Each of these programs will have their own - configuration files where you must configure certain parameters to - ensure that the mail is delivered properly. They are implemented - as services, and you should ensure that the MTA is in the auto-start - list of services for the machine. - - - - If a simple mail sent with the command-line 'mail' program - succeeds, then Bugzilla should also be fine. - - -
-
- Installing Bugzilla on mod_perl - It is now possible to run the Bugzilla software under mod_perl on - Apache. mod_perl has some additional requirements to that of running - Bugzilla under mod_cgi (the standard and previous way). - - Bugzilla requires mod_perl to be installed, which can be - obtained from - Bugzilla requires - version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed. -
-
- -
- Configuration - - - - Poorly-configured MySQL and Bugzilla installations have - given attackers full access to systems in the past. Please take the - security parts of these guidelines seriously, even for Bugzilla - machines hidden away behind your firewall. Be certain to read - for some important security tips. - - - -
- localconfig - - - You should now run checksetup.pl again, this time - without the --check-modules switch. - - bash# ./checksetup.pl - - This time, checksetup.pl should tell you that all - the correct modules are installed and will display a message about, and - write out a file called, localconfig. This file - contains the default settings for a number of Bugzilla parameters. - - - - Load this file in your editor. The only two values you - need to change are $db_driver and $db_pass, - respectively the type of the database and the password for - the user you will create for your database. Pick a strong - password (for simplicity, it should not contain single quote - characters) and put it here. $db_driver can be either 'mysql', - 'Pg', 'Oracle' or 'Sqlite'. - - - - - In Oracle, $db_name should actually be - the SID name of your database (e.g. "XE" if you are using Oracle XE). - - - - - You may need to change the value of - webservergroup if your web server does not - run in the "apache" group. On Debian, for example, Apache runs in - the "www-data" group. If you are going to run Bugzilla on a - machine where you do not have root access (such as on a shared web - hosting account), you will need to leave - webservergroup empty, ignoring the warnings - that checksetup.pl will subsequently display - every time it is run. - - - - - If you are using suexec, you should use your own primary group - for webservergroup rather than leaving it - empty, and see the additional directions in the suexec section - . - - - - - The other options in the localconfig file - are documented by their accompanying comments. If you have a slightly - non-standard database setup, you may wish to change one or more of - the other "$db_*" parameters. - -
- -
- Database Server - - This section deals with configuring your database server for use - with Bugzilla. Currently, MySQL (), - PostgreSQL (), Oracle () - and SQLite () are available. - - -
- Bugzilla Database Schema - - - The Bugzilla database schema is available at - Ravenbrook. - This very valuable tool can generate a written description of - the Bugzilla database schema for any version of Bugzilla. It - can also generate a diff between two versions to help someone - see what has changed. - -
- -
- MySQL - - - - MySQL's default configuration is insecure. - We highly recommend to run mysql_secure_installation - on Linux or the MySQL installer on Windows, and follow the instructions. - Important points to note are: - - - Be sure that the root account has a secure password set. - - - Do not create an anonymous account, and if it exists, say "yes" - to remove it. - - - If your web server and MySQL server are on the same machine, - you should disable the network access. - - - - - -
- Allow large attachments and many comments - - By default, MySQL will only allow you to insert things - into the database that are smaller than 1MB. Attachments - may be larger than this. Also, Bugzilla combines all comments - on a single bug into one field for full-text searching, and the - combination of all comments on a single bug could in some cases - be larger than 1MB. - - To change MySQL's default, you need to edit your MySQL - configuration file, which is usually /etc/my.cnf - on Linux. We recommend that you allow at least 4MB packets by - adding the "max_allowed_packet" parameter to your MySQL - configuration in the "[mysqld]" section, like this: - - [mysqld] -# Allow packets up to 4MB -max_allowed_packet=4M - -
- -
- Allow small words in full-text indexes - - By default, words must be at least four characters in length - in order to be indexed by MySQL's full-text indexes. This causes - a lot of Bugzilla specific words to be missed, including "cc", - "ftp" and "uri". - - MySQL can be configured to index those words by setting the - ft_min_word_len param to the minimum size of the words to index. - This can be done by modifying the /etc/my.cnf - according to the example below: - - [mysqld] -# Allow small words in full-text indexes -ft_min_word_len=2 - - Rebuilding the indexes can be done based on documentation found at - . - -
- -
- Add a user to MySQL - - - You need to add a new MySQL user for Bugzilla to use. - (It's not safe to have Bugzilla use the MySQL root account.) - The following instructions assume the defaults in - localconfig; if you changed those, - you need to modify the SQL command appropriately. You will - need the $db_pass password you - set in localconfig in - . - - - - We use an SQL GRANT command to create - a bugs user. This also restricts the - bugsuser to operations within a database - called bugs, and only allows the account - to connect from localhost. Modify it to - reflect your setup if you will be connecting from another - machine or as a different user. - - - - Run the mysql command-line client and enter: - - - -mysql> GRANT SELECT, INSERT, - UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, - CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* - TO bugs@localhost IDENTIFIED BY '$db_pass'; -mysql> FLUSH PRIVILEGES; - -
- -
- Permit attachments table to grow beyond 4GB - - - By default, MySQL will limit the size of a table to 4GB. - This limit is present even if the underlying filesystem - has no such limit. To set a higher limit, follow these - instructions. - - - - After you have completed the rest of the installation (or at least the - database setup parts), you should run the MySQL - command-line client and enter the following, replacing $bugs_db - with your Bugzilla database name (bugs by default): - - - -mysql> use $bugs_db -mysql> ALTER TABLE attachments - AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; - - - - The above command will change the limit to 20GB. Mysql will have - to make a temporary copy of your entire table to do this. Ideally, - you should do this when your attachments table is still small. - - - - - This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. - - -
-
- -
- PostgreSQL -
- Add a User to PostgreSQL - - You need to add a new user to PostgreSQL for the Bugzilla - application to use when accessing the database. The following instructions - assume the defaults in localconfig; if you - changed those, you need to modify the commands appropriately. You will - need the $db_pass password you - set in localconfig in - . - - On most systems, to create the user in PostgreSQL, you will need to - login as the root user, and then - - bash# su - postgres - - As the postgres user, you then need to create a new user: - - bash$ createuser -U postgres -dRSP bugs - - When asked for a password, provide the password which will be set as - $db_pass in localconfig. - The created user will not be a superuser (-S) and will not be able to create - new users (-R). He will only have the ability to create databases (-d). -
- -
- Configure PostgreSQL - - Now, you will need to edit pg_hba.conf which is - usually located in /var/lib/pgsql/data/. In this file, - you will need to add a new line to it as follows: - - - host all bugs 127.0.0.1 255.255.255.255 md5 - - - This means that for TCP/IP (host) connections, allow connections from - '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use - password authentication (md5) for that user. - - Now, you will need to restart PostgreSQL, but you will need to fully - stop and start the server rather than just restarting due to the possibility - of a change to postgresql.conf. After the server has - restarted, you will need to edit localconfig, finding - the $db_driver variable and setting it to - Pg and changing the password in $db_pass - to the one you picked previously, while setting up the account. -
-
- -
- Oracle -
- Create a New Tablespace - - - You can use the existing tablespace or create a new one for Bugzilla. - To create a new tablespace, run the following command: - - - -CREATE TABLESPACE bugs -DATAFILE '$path_to_datafile' SIZE 500M -AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED - - - - Here, the name of the tablespace is 'bugs', but you can - choose another name. $path_to_datafile is - the path to the file containing your database, for instance - /u01/oradata/bugzilla.dbf. - The initial size of the database file is set in this example to 500 Mb, - with an increment of 30 Mb everytime we reach the size limit of the file. - -
- -
- Add a User to Oracle - - - The user name and password must match what you set in - localconfig ($db_user - and $db_pass, respectively). Here, we assume that - the user name is 'bugs' and the tablespace name is the same - as above. - - - -CREATE USER bugs -IDENTIFIED BY "$db_pass" -DEFAULT TABLESPACE bugs -TEMPORARY TABLESPACE TEMP -PROFILE DEFAULT; --- GRANT/REVOKE ROLE PRIVILEGES -GRANT CONNECT TO bugs; -GRANT RESOURCE TO bugs; --- GRANT/REVOKE SYSTEM PRIVILEGES -GRANT UNLIMITED TABLESPACE TO bugs; -GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs; - -
- -
- Configure the Web Server - - - If you use Apache, append these lines to httpd.conf - to set ORACLE_HOME and LD_LIBRARY_PATH. For instance: - - - -SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/ -SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/ - - - - When this is done, restart your web server. - -
-
- -
- SQLite - - - - Due to SQLite's concurrency - limitations we recommend SQLite only for small and development - Bugzilla installations. - - - - - No special configuration is required to run Bugzilla on SQLite. - The database will be stored in data/db/$db_name, - where $db_name is the database name defined - in localconfig. - -
-
- -
- checksetup.pl - - - Next, rerun checksetup.pl. It reconfirms - that all the modules are present, and notices the altered - localconfig file, which it assumes you have edited to your - satisfaction. It compiles the UI templates, - connects to the database using the 'bugs' - user you created and the password you defined, and creates the - 'bugs' database and the tables therein. - - - - After that, it asks for details of an administrator account. Bugzilla - can have multiple administrators - you can create more later - but - it needs one to start off with. - Enter the email address of an administrator, his or her full name, - and a suitable Bugzilla password. - - - - checksetup.pl will then finish. You may rerun - checksetup.pl at any time if you wish. - -
- - -
- Web server - - Configure your web server according to the instructions in the - appropriate section. (If it makes a difference in your choice, - the Bugzilla Team recommends Apache.) To check whether your web server - is correctly configured, try to access testagent.cgi - from your web server. If "OK" is displayed, then your configuration - is successful. Regardless of which web server - you are using, however, ensure that sensitive information is - not remotely available by properly applying the access controls in - . You can run - testserver.pl to check if your web server serves - Bugzilla files as expected. - - -
- Bugzilla using Apache - You have two options for running Bugzilla under Apache - - mod_cgi (the default) and - mod_perl (new in Bugzilla - 2.23) - -
- Apache <productname>httpd</productname> with mod_cgi - - - To configure your Apache web server to work with Bugzilla while using - mod_cgi, do the following: - - - - - - Load httpd.conf in your editor. - In Fedora and Red Hat Linux, this file is found in - /etc/httpd/conf. - - - - - - Apache uses <Directory> - directives to permit fine-grained permission setting. Add the - following lines to a directive that applies to the location - of your Bugzilla installation. (If such a section does not - exist, you'll want to add one.) In this example, Bugzilla has - been installed at - /var/www/html/bugzilla. - - - -<Directory /var/www/html/bugzilla> -AddHandler cgi-script .cgi -Options +ExecCGI -DirectoryIndex index.cgi index.html -AllowOverride Limit FileInfo Indexes Options -</Directory> - - - - These instructions: allow apache to run .cgi files found - within the bugzilla directory; instructs the server to look - for a file called index.cgi or, if not - found, index.html if someone - only types the directory name into the browser; and allows - Bugzilla's .htaccess files to override - some global permissions. - - - - - It is possible to make these changes globally, or to the - directive controlling Bugzilla's parent directory (e.g. - <Directory /var/www/html/>). - Such changes would also apply to the Bugzilla directory... - but they would also apply to many other places where they - may or may not be appropriate. In most cases, including - this one, it is better to be as restrictive as possible - when granting extra access. - - - - - - On Windows, you may have to also add the - ScriptInterpreterSource Registry-Strict - line, see Windows specific notes. - - - - - - - checksetup.pl can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the Group - line in httpd.conf, place the value found - there in the $webservergroup variable - in localconfig, then rerun - checksetup.pl. - - - - - - Optional: If Bugzilla does not actually reside in the webspace - directory, but instead has been symbolically linked there, you - will need to add the following to the - Options line of the Bugzilla - <Directory> directive - (the same one as in the step above): - - - +FollowSymLinks - - - Without this directive, Apache will not follow symbolic links - to places outside its own directory structure, and you will be - unable to run Bugzilla. - - - -
-
- Apache <productname>httpd</productname> with mod_perl - - Some configuration is required to make Bugzilla work with Apache - and mod_perl - - - - - Load httpd.conf in your editor. - In Fedora and Red Hat Linux, this file is found in - /etc/httpd/conf. - - - - - Add the following information to your httpd.conf file, substituting - where appropriate with your own local paths. - - - This should be used instead of the <Directory> block - shown above. This should also be above any other mod_perl - directives within the httpd.conf and must be specified - in the order as below. - - - You should also ensure that you have disabled KeepAlive - support in your Apache install when utilizing Bugzilla under mod_perl - - - -PerlSwitches -w -T -PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl - - - - - - checksetup.pl can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the Group - line in httpd.conf, place the value found - there in the $webservergroup variable - in localconfig, then rerun - checksetup.pl. - - - - - On restarting Apache, Bugzilla should now be running within the - mod_perl environment. Please ensure you have run checksetup.pl to set - permissions before you restart Apache. - - - Please bear the following points in mind when looking at using - Bugzilla under mod_perl: - - - - mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be - looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM. - The more RAM you can get, the better. mod_perl is basically trading RAM for - speed. At least 2GB total system RAM is recommended for running Bugzilla under - mod_perl. - - - - - Under mod_perl, you have to restart Apache if you make any manual change to - any Bugzilla file. You can't just reload--you have to actually - restart the server (as in make sure it stops and starts - again). You can change localconfig and the params file - manually, if you want, because those are re-read every time you load a page. - - - - - You must run in Apache's Prefork MPM (this is the default). The Worker MPM - may not work--we haven't tested Bugzilla's mod_perl support under threads. - (And, in fact, we're fairly sure it won't work.) - - - - - Bugzilla generally expects to be the only mod_perl application running on - your entire server. It may or may not work if there are other applications also - running under mod_perl. It does try its best to play nice with other mod_perl - applications, but it still may have conflicts. - - - - - It is recommended that you have one Bugzilla instance running under mod_perl - on your server. Bugzilla has not been tested with more than one instance running. - - - - - -
-
- -
- Microsoft <productname>Internet Information Services</productname> - - - If you are running Bugzilla on Windows and choose to use - Microsoft's Internet Information Services - or Personal Web Server you will need - to perform a number of other configuration steps as explained below. - You may also want to refer to the following Microsoft Knowledge - Base articles: - 245225 - HOW TO: Configure and Test a PERL Script with IIS 4.0, - 5.0, and 5.1 (for Internet Information - Services) and - 231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web - Server on Windows 95/98 (for Personal Web - Server). - - - - You will need to create a virtual directory for the Bugzilla - install. Put the Bugzilla files in a directory that is named - something other than what you want your - end-users accessing. That is, if you want your users to access - your Bugzilla installation through - http://<yourdomainname>/Bugzilla, then do - not put your Bugzilla files in a directory - named Bugzilla. Instead, place them in a different - location, and then use the IIS Administration tool to create a - Virtual Directory named "Bugzilla" that acts as an alias for the - actual location of the files. When creating that virtual directory, - make sure you add the Execute (such as ISAPI applications or - CGI) access permission. - - - - You will also need to tell IIS how to handle Bugzilla's - .cgi files. Using the IIS Administration tool again, open up - the properties for the new virtual directory and select the - Configuration option to access the Script Mappings. Create an - entry mapping .cgi to: - - - -<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s - - - - For example: - - - -c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s - - - - - The ActiveState install may have already created an entry for - .pl files that is limited to GET,HEAD,POST. If - so, this mapping should be removed as - Bugzilla's .pl files are not designed to be run via a web server. - - - - - IIS will also need to know that the index.cgi should be treated - as a default document. On the Documents tab page of the virtual - directory properties, you need to add index.cgi as a default - document type. If you wish, you may remove the other default - document types for this particular virtual directory, since Bugzilla - doesn't use any of them. - - - - Also, and this can't be stressed enough, make sure that files - such as localconfig and your - data directory are - secured as described in . - - -
- -
- -
- Bugzilla - - - Your Bugzilla should now be working. Access - http://<your-bugzilla-server>/ - - you should see the Bugzilla - front page. If not, consult the Troubleshooting section, - . - - - - - The URL above may be incorrect if you installed Bugzilla into a - subdirectory or used a symbolic link from your web site root to - the Bugzilla directory. - - - - - Log in with the administrator account you defined in the last - checksetup.pl run. You should go through - the Parameters page and see if there are any you wish to change. - They key parameters are documented in ; - you should certainly alter - maintainer and urlbase; - you may also want to alter - cookiepath or requirelogin. - - - - Bugzilla has several optional features which require extra - configuration. You can read about those in - . - -
-
- -
- Optional Additional Configuration - - - Bugzilla has a number of optional features. This section describes how - to configure or enable them. - - -
- Bug Graphs - - If you have installed the necessary Perl modules you - can start collecting statistics for the nifty Bugzilla - graphs. - - bash# crontab -e - - - This should bring up the crontab file in your editor. - Add a cron entry like this to run - collectstats.pl - daily at 5 after midnight: - - - 5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl - - - After two days have passed you'll be able to view bug graphs from - the Reports page. - - - - - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - nncron. - - -
- -
- The Whining Cron - - What good are - bugs if they're not annoying? To help make them more so you - can set up Bugzilla's automatic whining system to complain at engineers - which leave their bugs in the CONFIRMED state without triaging them. - - - This can be done by adding the following command as a daily - crontab entry, in the same manner as explained above for bug - graphs. This example runs it at 12.55am. - - - 55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl - - - - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - nncron. - - -
- -
- Whining - - - As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy - them at regular intervals, by having Bugzilla execute saved searches - at certain times and emailing the results to the user. This is known - as "Whining". The process of configuring Whining is described - in , but for it to work a Perl script must be - executed at regular intervals. - - - - This can be done by adding the following command as a daily - crontab entry, in the same manner as explained above for bug - graphs. This example runs it every 15 minutes. - - - */15 * * * * cd <your-bugzilla-directory> && ./whine.pl - - - - Whines can be executed as often as every 15 minutes, so if you specify - longer intervals between executions of whine.pl, some users may not - be whined at as often as they would expect. Depending on the person, - this can either be a very Good Thing or a very Bad Thing. - - - - - - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - nncron. - - -
- -
- Serving Alternate Formats with the right MIME type - - - Some Bugzilla pages have alternate formats, other than just plain - HTML. In particular, a few Bugzilla pages can - output their contents as either XUL (a special - Mozilla format, that looks like a program GUI) - or RDF (a type of structured XML - that can be read by various programs). - - - In order for your users to see these pages correctly, Apache must - send them with the right MIME type. To do this, - add the following lines to your Apache configuration, either in the - <VirtualHost> section for your - Bugzilla, or in the <Directory> - section for your Bugzilla: - - - AddType application/vnd.mozilla.xul+xml .xul -AddType application/rdf+xml .rdf - -
-
- -
- Multiple Bugzilla databases with a single installation - - The previous instructions referred to a standard installation, with - one unique Bugzilla database. However, you may want to host several - distinct installations, without having several copies of the code. This is - possible by using the PROJECT environment variable. When accessed, - Bugzilla checks for the existence of this variable, and if present, uses - its value to check for an alternative configuration file named - localconfig.<PROJECT> in the same location as - the default one (localconfig). It also checks for - customized templates in a directory named - <PROJECT> in the same location as the - default one (template/<langcode>). By default - this is template/en/default so PROJECT's templates - would be located at template/en/PROJECT. - - To set up an alternate installation, just export PROJECT=foo before - running checksetup.pl for the first time. It will - result in a file called localconfig.foo instead of - localconfig. Edit this file as described above, with - reference to a new database, and re-run checksetup.pl - to populate it. That's all. - - Now you have to configure the web server to pass this environment - variable when accessed via an alternate URL, such as virtual host for - instance. The following is an example of how you could do it in Apache, - other Webservers may differ. - -<VirtualHost 212.85.153.228:80> - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla -</VirtualHost> - - - - Don't forget to also export this variable before accessing Bugzilla - by other means, such as cron tasks for instance. -
- -
- OS-Specific Installation Notes - - Many aspects of the Bugzilla installation can be affected by the - operating system you choose to install it on. Sometimes it can be made - easier and others more difficult. This section will attempt to help you - understand both the difficulties of running on specific operating systems - and the utilities available to make it easier. - - - If you have anything to add or notes for an operating system not covered, - please file a bug in Bugzilla Documentation. - - -
- Microsoft Windows - - Making Bugzilla work on Windows is more difficult than making it - work on Unix. For that reason, we still recommend doing so on a Unix - based system such as GNU/Linux. That said, if you do want to get - Bugzilla running on Windows, you will need to make the following - adjustments. A detailed step-by-step - - installation guide for Windows is also available - if you need more help with your installation. - - -
- Win32 Perl - - Perl for Windows can be obtained from - ActiveState. - You should be able to find a compiled binary at . - The following instructions assume that you are using version - &min-perl-ver; of ActiveState. - - - - - These instructions are for 32-bit versions of Windows. If you are - using a 64-bit version of Windows, you will need to install 32-bit - Perl in order to install the 32-bit modules as described below. - - - -
- -
- Perl Modules on Win32 - - - Bugzilla on Windows requires the same perl modules found in - . The main difference is that - windows uses PPM instead - of CPAN. ActiveState provides a GUI to manage Perl modules. We highly - recommend that you use it. If you prefer to use ppm from the - command-line, type: - - - -C:\perl> ppm install <module name> - - - - - The PPM repository stores modules in 'packages' that may have - a slightly different name than the module. If retrieving these - modules from there, you will need to pay attention to the information - provided when you run checksetup.pl as it will - tell you what package you'll need to install. - - - - - - If you are behind a corporate firewall, you will need to let the - ActiveState PPM utility know how to get through it to access - the repositories by setting the HTTP_proxy system environmental - variable. For more information on setting that variable, see - the ActiveState documentation. - - -
- -
- Serving the web pages - - - 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 . More - information on configuring specific web servers can be found - in . - - - - - The web server looks at /usr/bin/perl to - call Perl. If you are using Apache on windows, you can set the - ScriptInterpreterSource - directive in your Apache config file to make it look at the - right place: insert the line - ScriptInterpreterSource Registry-Strict - into your httpd.conf file, and create the key - HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command - with as value (adapt to your - path if needed) in the registry. When this is done, restart Apache. - - - -
- -
- Sending Email - - - To enable Bugzilla to send email on Windows, the server running the - Bugzilla code must be able to connect to, or act as, an SMTP server. - - -
-
- -
- <productname>Mac OS X</productname> - - Making Bugzilla work on Mac OS X requires the following - adjustments. - -
- Sendmail - - In Mac OS X 10.3 and later, - Postfix - is used as the built-in email server. Postfix provides an executable - that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can - find it. Bugzilla is able to find the fake sendmail executable without - any assistance. - -
- -
- Libraries & Perl Modules on Mac OS X - - Apple does not include the GD library with Mac OS X. Bugzilla - needs this for bug graphs. - - You can use MacPorts () - or Fink (), both - of which are similar in nature to the CPAN installer, but install - common unix programs. - - Follow the instructions for setting up MacPorts or Fink. - Once you have one installed, you'll want to use it to install the - gd2 package. - - - Fink will prompt you for a number of dependencies, type 'y' and hit - enter to install all of the dependencies and then watch it work. You will - then be able to use CPAN to - install the GD Perl module. - - - - 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 - will be at /sw/lib and - /sw/include instead of - /usr/lib and - /usr/include. When the - Perl module config script asks where your libgd - is, be sure to tell it - /sw/lib. - - - - Also available via MacPorts and Fink is - expat. After installing the expat package, you - will be able to install XML::Parser using CPAN. If you use fink, there - is one caveat. Unlike recent versions of - the GD module, XML::Parser doesn't prompt for the location of the - required libraries. When using CPAN, you will need to use the following - command sequence: - - - -# perl -MCPAN -e'look XML::Parser' -# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include -# make; make test; make install -# exit - - - The look command will download the module and spawn - a new shell with the extracted files as the current working directory. - - - You should watch the output from these make commands, - especially make test as errors may prevent - XML::Parser from functioning correctly with Bugzilla. - - - The exit command will return you to your original shell. - -
-
- -
- Linux/BSD Distributions - Many Linux/BSD distributions include Bugzilla and its - dependencies in their native package management systems. - Installing Bugzilla with root access on any Linux/BSD system - should be as simple as finding the Bugzilla package in the - package management application and installing it using the - normal command syntax. Several distributions also perform - the proper web server configuration automatically on installation. - - Please consult the documentation of your Linux/BSD - distribution for instructions on how to install packages, - or for specific instructions on installing Bugzilla with - native package management tools. There is also a - - Bugzilla Wiki Page for distro-specific installation - notes. - -
-
- - -
- UNIX (non-root) Installation Notes - -
- Introduction - - If you are running a *NIX OS as non-root, either due - to lack of access (web hosts, for example) or for security - reasons, this will detail how to install Bugzilla on such - a setup. It is recommended that you read through the - - first to get an idea on the installation steps required. - (These notes will reference to steps in that guide.) - -
- -
- MySQL - - You may have MySQL installed as root. If you're - setting up an account with a web host, a MySQL account - needs to be set up for you. From there, you can create - the bugs account, or use the account given to you. - - - You may have problems trying to set up - GRANT permissions to the database. - If you're using a web host, chances are that you have a - separate database which is already locked down (or one big - database with limited/no access to the other areas), but you - may want to ask your system administrator what the security - settings are set to, and/or run the GRANT - command for you. - - Also, you will probably not be able to change the MySQL - root user password (for obvious reasons), so skip that - step. - - -
- Running MySQL as Non-Root -
- The Custom Configuration Method - Create a file .my.cnf in your - home directory (using /home/foo in this example) - as follows.... - -[mysqld] -datadir=/home/foo/mymysql -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql] -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql.server] -user=mysql -basedir=/var/lib - -[safe_mysqld] -err-log=/home/foo/mymysql/the.log -pid-file=/home/foo/mymysql/the.pid - -
-
- The Custom Built Method - - You can install MySQL as a not-root, if you really need to. - Build it with PREFIX set to /home/foo/mysql, - or use pre-installed executables, specifying that you want - to put all of the data files in /home/foo/mysql/data. - If there is another MySQL server running on the system that you - do not own, use the -P option to specify a TCP port that is not - in use. -
- -
- Starting the Server - After your mysqld program is built and any .my.cnf file is - in place, you must initialize the databases (ONCE). - -bash$ mysql_install_db - - Then start the daemon with - -bash$ safe_mysql & - - After you start mysqld the first time, you then connect to - it as "root" and GRANT permissions to other - users. (Again, the MySQL root account has nothing to do with - the *NIX root account.) - - - You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed. - - - - Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user! - -
-
-
- -
- Perl - - - On the extremely rare chance that you don't have Perl on - the machine, you will have to build the sources - yourself. The following commands should get your system - installed with your own personal version of Perl: - - - -bash$ wget http://perl.org/CPAN/src/stable.tar.gz -bash$ tar zvxf stable.tar.gz -bash$ cd perl-&min-perl-ver; -bash$ sh Configure -de -Dprefix=/home/foo/perl -bash$ make && make test && make install - - - - Once you have Perl installed into a directory (probably - in ~/perl/bin), you will need to - install the Perl Modules, described below. - -
- -
- Perl Modules - - - Installing the Perl modules as a non-root user is accomplished by - running the install-module.pl - script. For more details on this script, see - install-module.pl - documentation - -
- -
- HTTP Server - - Ideally, this also needs to be installed as root and - run under a special web server account. As long as - the web server will allow the running of *.cgi files outside of a - cgi-bin, and a way of denying web access to certain files (such as a - .htaccess file), you should be good in this department. - -
- Running Apache as Non-Root - - You can run Apache as a non-root user, but the port will need - to be set to one above 1024. If you type httpd -V, - you will get a list of the variables that your system copy of httpd - uses. One of those, namely HTTPD_ROOT, tells you where that - installation looks for its config information. - - From there, you can copy the config files to your own home - directory to start editing. When you edit those and then use the -d - option to override the HTTPD_ROOT compiled into the web server, you - get control of your own customized web server. - - - You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed. - - - - Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user! - -
-
- -
- Bugzilla - - - When you run ./checksetup.pl to create - the localconfig file, it will list the Perl - modules it finds. If one is missing, go back and double-check the - module installation from , - then delete the localconfig file and try again. - - - - One option in localconfig you - might have problems with is the web server group. If you can't - successfully browse to the index.cgi (like - a Forbidden error), you may have to relax your permissions, - and blank out the web server group. Of course, this may pose - as a security risk. Having a properly jailed shell and/or - limited access to shell accounts may lessen the security risk, - but use at your own risk. - - -
- suexec or shared hosting - - If you are running on a system that uses suexec (most shared - hosting environments do this), you will need to set the - webservergroup value in localconfig - to match your primary group, rather than the one - the web server runs under. You will need to run the following - shell commands after running ./checksetup.pl, - every time you run it (or modify checksetup.pl - to do them for you via the system() command). - -for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done -for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done -find . -name .htaccess -exec chmod o+r {} \; -chmod o+x . data data/webdot - - Pay particular attention to the number of semicolons and dots. - They are all important. A future version of Bugzilla will - hopefully be able to do this for you out of the box. -
-
-
- - -
- Upgrading to New Releases - - Upgrading to new Bugzilla releases is very simple. There is - a script named checksetup.pl included with - Bugzilla that will automatically do all of the database migration - for you. - - The following sections explain how to upgrade from one - version of Bugzilla to another. Whether you are upgrading - from one bug-fix version to another (such as 4.2 to 4.2.1) - or from one major version to another (such as from 4.0 to 4.2), - the instructions are always the same. - - - - Any examples in the following sections are written as though the - user were updating to version 4.2.1, but the procedures are the - same no matter what version you're updating to. Also, in the - examples, the user's Bugzilla installation is found at - /var/www/html/bugzilla. If that is not the - same as the location of your Bugzilla installation, simply - substitute the proper paths where appropriate. - - - -
- Before You Upgrade - - Before you start your upgrade, there are a few important - steps to take: - - - - - Read the Release - Notes of the version you're upgrading to, - particularly the "Notes for Upgraders" section. - - - - - - View the Sanity Check () page - on your installation before upgrading. Attempt to fix all warnings - that the page produces before you go any further, or you may - experience problems during your upgrade. - - - - - - Shut down your Bugzilla installation by putting some HTML or - text in the shutdownhtml parameter - (see ). - - - - - - Make a backup of the Bugzilla database. - THIS IS VERY IMPORTANT. If - anything goes wrong during the upgrade, your installation - can be corrupted beyond recovery. Having a backup keeps you safe. - - - - - Upgrading is a one-way process. You cannot "downgrade" an - upgraded Bugzilla. If you wish to revert to the old Bugzilla - version for any reason, you will have to restore your database - from this backup. - - - - Here are some sample commands you could use to backup - your database, depending on what database system you're - using. You may have to modify these commands for your - particular setup. - - - - MySQL: - - - mysqldump --opt -u bugs -p bugs > bugs.sql - - - - - - PostgreSQL: - - - pg_dump --no-privileges --no-owner -h localhost -U bugs - > bugs.sql - - - - - - -
- -
- Getting The New Bugzilla - - There are three ways to get the new version of Bugzilla. - We'll list them here briefly and then explain them - more later. - - - - Bzr () - - - If you have bzr installed on your machine - and you have Internet access, this is the easiest way to - upgrade, particularly if you have made modifications - to the code or templates of Bugzilla. - - - - - - Download the tarball () - - - This is a very simple way to upgrade, and good if you - haven't made many (or any) modifications to the code or - templates of your Bugzilla. - - - - - - Patches () - - - If you have made modifications to your Bugzilla, and - you don't have Internet access or you don't want to use - bzr, then this is the best way to upgrade. - - - - You can only do minor upgrades (such as 4.2 to 4.2.1 or - 4.2.1 to 4.2.2) with patches. - - - - - -
- If you have modified your Bugzilla - - - If you have modified the code or templates of your Bugzilla, - then upgrading requires a bit more thought and effort. - A discussion of the various methods of updating compared with - degree and methods of local customization can be found in - . - - - - The larger the jump you are trying to make, the more difficult it - is going to be to upgrade if you have made local customizations. - Upgrading from 4.2 to 4.2.1 should be fairly painless even if - you are heavily customized, but going from 2.18 to 4.2 is going - to mean a fair bit of work re-writing your local changes to use - the new files, logic, templates, etc. If you have done no local - changes at all, however, then upgrading should be approximately - the same amount of work regardless of how long it has been since - your version was released. - -
- -
- Upgrading using Bzr - - - This requires that you have bzr installed (most Unix machines do), - and requires that you are able to access - bzr.mozilla.org, - which may not be an option if you don't have Internet access. - - - - The following shows the sequence of commands needed to update a - Bugzilla installation via Bzr, and a typical series of results. - These commands assume that you already have Bugzilla installed - using Bzr. - - - - - If your installation is still using CVS, you must first convert - it to Bzr. A very detailed step by step documentation can be - found on wiki.mozilla.org. - - - - -bash$ cd /var/www/html/bugzilla -bash$ bzr switch 4.2 (only run this command when not yet running 4.2) -bash$ bzr up -r tag:bugzilla-4.2.1 -+N extensions/MoreBugUrl/ -+N extensions/MoreBugUrl/Config.pm -+N extensions/MoreBugUrl/Extension.pm -... - M Bugzilla/Attachment.pm - M Bugzilla/Attachment/PatchReader.pm - M Bugzilla/Bug.pm -... -All changes applied successfully. - - - - - If a line in the output from bzr up mentions - a conflict, then that represents a file with local changes that - Bzr 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. - - -
- -
- Upgrading using the tarball - - - If you are unable (or unwilling) to use Bzr, another option that's - always available is to obtain the latest tarball from the Download Page and - create a new Bugzilla installation from that. - - - - This sequence of commands shows how to get the tarball from the - command-line; it is also possible to download it from the site - directly in a web browser. If you go that route, save the file - to the /var/www/html - directory (or its equivalent, if you use something else) and - omit the first three lines of the example. - - - -bash$ cd /var/www/html -bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz -(Output omitted) -bash$ tar xzvf bugzilla-4.2.1.tar.gz -bugzilla-4.2.1/ -bugzilla-4.2.1/colchange.cgi -(Output truncated) -bash$ cd bugzilla-4.2.1 -bash$ cp ../bugzilla/localconfig* . -bash$ cp -r ../bugzilla/data . -bash$ cd .. -bash$ mv bugzilla bugzilla.old -bash$ mv bugzilla-4.2.1 bugzilla - - - - - The cp commands both end with periods which - is a very important detail--it means that the destination - directory is the current working directory. - - - - - - If you have some extensions installed, you will have to copy them - to the new bugzilla directory too. Extensions are located in - bugzilla/extensions/. Only copy those you - installed, not those managed by the Bugzilla team. - - - - - This upgrade method will give you a clean install of Bugzilla. - That's fine if you don't have any local customizations that you - want to maintain. If you do have customizations, then you will - need to reapply them by hand to the appropriate files. - -
- -
- Upgrading using patches - - - A patch is a collection of all the bug fixes that have been made - since the last bug-fix release. - - - - If you are doing a bug-fix upgrade—that is, one where only the - last number of the revision changes, such as from 4.2 to - 4.2.1—then you have the option of obtaining and applying a - patch file from the Download Page. - - - - As above, this example starts with obtaining the file via the - command line. If you have already downloaded it, you can omit the - first two commands. - - - -bash$ cd /var/www/html/bugzilla -bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2-to-4.2.1.diff.gz -(Output omitted) -bash$ gunzip bugzilla-4.2-to-4.2.1.diff.gz -bash$ patch -p1 < bugzilla-4.2-to-4.2.1.diff -patching file Bugzilla/Constants.pm -patching file enter_bug.cgi -(etc.) - - - - - Be aware that upgrading from a patch file does not change the - entries in your .bzr directory. - This could make it more difficult to upgrade using Bzr - () in the future. - - - -
-
- -
- Completing Your Upgrade - - - Now that you have the new Bugzilla code, there are a few final - steps to complete your upgrade. - - - - - - If your new Bugzilla installation is in a different - directory or on a different machine than your old Bugzilla - installation, make sure that you have copied the - data directory and the - localconfig file from your old Bugzilla - installation. (If you followed the tarball instructions - above, this has already happened.) - - - - - - If this is a major update, check that the configuration - () for your new Bugzilla is - up-to-date. Sometimes the configuration requirements change - between major versions. - - - - - - If you didn't do it as part of the above configuration step, - now you need to run checksetup.pl, which - will do everything required to convert your existing database - and settings for the new version: - - - -bash$ cd /var/www/html/bugzilla -bash$ ./checksetup.pl - - - - - The period at the beginning of the command - ./checksetup.pl is important and cannot - be omitted. - - - - - - If this is a major upgrade (say, 3.6 to 4.2 or similar), - running checksetup.pl on a large - installation (75,000 or more bugs) can take a long time, - possibly several hours. - - - - - - - Clear any HTML or text that you put into the shutdownhtml - parameter, to re-activate Bugzilla. - - - - - - View the Sanity Check () page in your - upgraded Bugzilla. - - - It is recommended that, if possible, you fix any problems - you see, immediately. Failure to do this may mean that Bugzilla - will not work correctly. Be aware that if the sanity check page - contains more errors after an upgrade, it doesn't necessarily - mean there are more errors in your database than there were - before, as additional tests are added to the sanity check over - time, and it is possible that those errors weren't being - checked for in the old version. - - - - -
- -
- Automatic Notifications of New Releases - - - Bugzilla 3.0 introduced the ability to automatically notify - administrators when new releases are available, based on the - upgrade_notification parameter, see - . Administrators will see these - notifications when they access the index.cgi - page, i.e. generally when logging in. Bugzilla will check once per - day for new releases, unless the parameter is set to - disabled. If you are behind a proxy, you may have to set - the proxy_url parameter accordingly. If the proxy - requires authentication, use the - http://user:pass@proxy_url/ syntax. - -
-
- - - - diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml deleted file mode 100644 index eba87d41d..000000000 --- a/docs/en/xml/modules.xml +++ /dev/null @@ -1,187 +0,0 @@ - - - - %myents; -]> - - - Manual Installation of Perl Modules - -
- Instructions - - If you need to install Perl modules manually, here's how it's done. - Download the module using the link given in the next section, and then - apply this magic incantation, as root: - - - - bash# tar -xzvf <module>.tar.gz -bash# cd <module> -bash# perl Makefile.PL -bash# make -bash# make test -bash# make install - - - - In order to compile source code under Windows you will need to obtain - a 'make' utility. The nmake utility provided with - Microsoft Visual C++ may be used. As an alternative, there is a - utility called dmake available from CPAN which is - written entirely in Perl. - - - As described in , however, most - packages already exist and are available from ActiveState or theory58S. - We highly recommend that you install them using the ppm GUI available with - ActiveState and to add the theory58S repository to your list of repositories. - - -
- -
- Download Locations - - - - Running Bugzilla on Windows requires the use of ActiveState - Perl &min-perl-ver; or higher. Most modules already exist in the core - distribution of ActiveState Perl. - - - - - CGI: - - CPAN Download Page: - Documentation: - - - - - Data-Dumper: - - CPAN Download Page: - Documentation: - - - - - Date::Format (part of TimeDate): - - CPAN Download Page: - Documentation: - - - - - DBI: - - CPAN Download Page: - Documentation: - - - - - DBD::mysql: - - CPAN Download Page: - Documentation: - - - - - DBD::Pg: - - CPAN Download Page: - Documentation: - - - - - Template-Toolkit: - - CPAN Download Page: - Documentation: - - - - - GD: - - CPAN Download Page: - Documentation: - - - - - Template::Plugin::GD: - - CPAN Download Page: - Documentation: - - - - - MIME::Parser (part of MIME-tools): - - CPAN Download Page: - Documentation: - - - -
- -
- Optional Modules - - - Chart::Lines: - - CPAN Download Page: - Documentation: - - - - - GD::Graph: - - CPAN Download Page: - Documentation: - - - - - GD::Text::Align (part of GD::Text::Util): - - CPAN Download Page: - Documentation: - - - - - XML::Twig: - - CPAN Download Page: - Documentation: - - - - - PatchReader: - - CPAN Download Page: - Documentation: - - -
- diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml deleted file mode 100644 index ed7d304c7..000000000 --- a/docs/en/xml/patches.xml +++ /dev/null @@ -1,143 +0,0 @@ - - - - %myents; -]> - - - Contrib - - - There are a number of unofficial Bugzilla add-ons in the - $BUGZILLA_ROOT/contrib/ - directory. This section documents them. - - -
- Command-line Search Interface - - - There are a suite of Unix utilities for searching Bugzilla from the - command line. They live in the - contrib/cmdline directory. - There are three files - query.conf, - buglist and bugs. - - - - - These files pre-date the templatization work done as part of the - 2.16 release, and have not been updated. - - - - - query.conf 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. - - - - buglist is a shell script that 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=. - - - - The column list is taken from the COLUMNLIST environment variable. - This is equivalent to the Change Columns option - that is available when you list bugs in buglist.cgi. If you have - already used Bugzilla, grep for COLUMNLIST in your cookies file - to see your current COLUMNLIST setting. - - - - bugs is a simple shell script which calls - buglist and extracts the - bug numbers from the output. Adding the prefix - http://bugzilla.mozilla.org/buglist.cgi?bug_id= - turns the bug list into a working link if any bugs are found. - Counting bugs is easy. Pipe the results through - sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}' - - - - Akkana Peck says she has good results piping - buglist output through - w3m -T text/html -dump - - -
- -
- Command-line 'Send Unsent Bug-mail' tool - - - Within the contrib directory - exists a utility with the descriptive (if compact) name - of sendunsentbugmail.pl. The purpose of this - script is, simply, to send out any bug-related mail that should - have been sent by now, but for one reason or another has not. - - - - To accomplish this task, sendunsentbugmail.pl uses - the same mechanism as the sanitycheck.cgi script; - it scans through the entire database looking for bugs with changes that - were made more than 30 minutes ago, but where there is no record of - anyone related to that bug having been sent mail. Having compiled a list, - it then uses the standard rules to determine who gets mail, and sends it - out. - - - - As the script runs, it indicates the bug for which it is currently - sending mail; when it has finished, it gives a numerical count of how - many mails were sent and how many people were excluded. (Individual - user names are not recorded or displayed.) If the script produces - no output, that means no unsent mail was detected. - - - - Usage: move the sendunsentbugmail.pl script - up into the main directory, ensure it has execute permission, and run it - from the command line (or from a cron job) with no parameters. - -
- - - - diff --git a/docs/en/xml/security.xml b/docs/en/xml/security.xml deleted file mode 100644 index 582604029..000000000 --- a/docs/en/xml/security.xml +++ /dev/null @@ -1,281 +0,0 @@ - - - - %myents; -]> - - -Bugzilla Security - - While some of the items in this chapter are related to the operating - system Bugzilla is running on or some of the support software required to - run Bugzilla, it is all related to protecting your data. This is not - intended to be a comprehensive guide to securing Linux, Apache, MySQL, or - any other piece of software mentioned. There is no substitute for active - administration and monitoring of a machine. The key to good security is - actually right in the middle of the word: U R It. - - - While programmers in general always strive to write secure code, - accidents can and do happen. The best approach to security is to always - assume that the program you are working with isn't 100% secure and restrict - its access to other parts of your machine as much as possible. - - -
- Operating System - -
- TCP/IP Ports - - - The TCP/IP standard defines more than 65,000 ports for sending - and receiving traffic. Of those, Bugzilla needs exactly one to operate - (different configurations and options may require up to 3). You should - audit your server and make sure that you aren't listening on any ports - you don't need to be. It's also highly recommended that the server - Bugzilla resides on, along with any other machines you administer, be - placed behind some kind of firewall. - - -
- -
- System User Accounts - - Many daemons, such - as Apache's httpd or MySQL's - mysqld, run as either root or - nobody. This is even worse on Windows machines where the - majority of services - run as SYSTEM. While running as root or - SYSTEM introduces obvious security concerns, the - problems introduced by running everything as nobody may - not be so obvious. Basically, if you run every daemon as - nobody and one of them gets compromised it can - compromise every other daemon running as nobody on your - machine. For this reason, it is recommended that you create a user - account for each daemon. - - - - You will need to set the option - in localconfig to the group your web server runs - as. This will allow ./checksetup.pl to set file - permissions on Unix systems so that nothing is world-writable. - - - -
- -
- The <filename>chroot</filename> Jail - - - If your system supports it, you may wish to consider running - Bugzilla inside of a chroot jail. This option - provides unprecedented security by restricting anything running - inside the jail from accessing any information outside of it. If you - wish to use this option, please consult the documentation that came - with your system. - - -
- -
- -
- Web server - -
- Disabling Remote Access to Bugzilla Configuration Files - - - There are many files that are placed in the Bugzilla directory - area that should not be accessible from the web server. Because of the way - Bugzilla is currently layed out, the list of what should and should not - be accessible is rather complicated. A quick way is to run - testserver.pl to check if your web server serves - Bugzilla files as expected. If not, you may want to follow the few - steps below. - - - - Bugzilla ships with the ability to create - .htaccess - files that enforce these rules. Instructions for enabling these - directives in Apache can be found in - - - - - - In the main Bugzilla directory, you should: - - - Block: - - *.pl - *localconfig* - - - - - - - - In data: - - - Block everything - - - - - - In data/webdot: - - - If you use a remote webdot server: - - - Block everything - - - But allow - - *.dot - - only for the remote webdot server - - - - - Otherwise, if you use a local GraphViz: - - - Block everything - - - But allow: - - *.png - *.gif - *.jpg - *.map - - - - - - - And if you don't use any dot: - - - Block everything - - - - - - - - In Bugzilla: - - - Block everything - - - - - - In template: - - - Block everything - - - - - - Be sure to test that data that should not be accessed remotely is - properly blocked. Of particular interest is the localconfig file which - contains your database password. Also, be aware that many editors - create temporary and backup files in the working directory and that - those should also not be accessible. For more information, see - bug 186383 - or - Bugtraq ID 6501. - To test, simply run testserver.pl, as said above. - - - - Be sure to check for instructions - specific to the web server you use. - - - -
- - -
- - -
- Bugzilla - -
- Prevent users injecting malicious Javascript - - If you installed Bugzilla version 2.22 or later from scratch, - then the utf8 parameter is switched on by default. - This makes Bugzilla explicitly set the character encoding, following - a - CERT advisory recommending exactly this. - The following therefore does not apply to you; just keep - utf8 turned on. - - - If you've upgraded from an older version, then it may be possible - for a Bugzilla user to take advantage of character set encoding - ambiguities to inject HTML into Bugzilla comments. - This could include malicious scripts. - This is because due to internationalization concerns, we are unable to - turn the utf8 parameter on by default for upgraded - installations. - Turning it on manually will prevent this problem. - -
- -
- - - - diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml deleted file mode 100644 index 7dcf75238..000000000 --- a/docs/en/xml/troubleshooting.xml +++ /dev/null @@ -1,287 +0,0 @@ - - - - %myents; -]> - - -Troubleshooting - - This section gives solutions to common Bugzilla installation - problems. If none of the section headings seems to match your - problem, read the general advice. - - -
- General Advice - If you can't get checksetup.pl to run to - completion, it normally explains what's wrong and how to fix it. - If you can't work it out, or if it's being uncommunicative, post - the errors in the - mozilla.support.bugzilla - newsgroup. - - - If you have made it all the way through - (Installation) and - (Configuration) but accessing the Bugzilla - URL doesn't work, the first thing to do is to check your web server error - log. For Apache, this is often located at - /etc/logs/httpd/error_log. The error messages - you see may be self-explanatory enough to enable you to diagnose and - fix the problem. If not, see below for some commonly-encountered - errors. If that doesn't help, post the errors to the newsgroup. - - - - Bugzilla can also log all user-based errors (and many code-based errors) - that occur, without polluting the web server's error log. To enable - Bugzilla error logging, create a file that Bugzilla can write to, named - errorlog, in the Bugzilla data - directory. Errors will be logged as they occur, and will include the type - of the error, the IP address and username (if available) of the user who - triggered the error, and the values of all environment variables; if a - form was being submitted, the data in the form will also be included. - To disable error logging, delete or rename the - errorlog file. - -
- -
- The Apache web server is not serving Bugzilla pages - After you have run checksetup.pl twice, - run testserver.pl http://yoursite.yourdomain/yoururl - to confirm that your web server is configured properly for - Bugzilla. - - -bash$ ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip -TEST-OK Webserver is running under group id in $webservergroup. -TEST-OK Got ant picture. -TEST-OK Webserver is executing CGIs. -TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig. - -
- -
- I installed a Perl module, but - <filename>checksetup.pl</filename> claims it's not installed! - - This could be caused by one of two things: - - - You have two versions of Perl on your machine. You are installing - modules into one, and Bugzilla is using the other. Rerun the CPAN - commands (or manual compile) using the full path to Perl from the - top of checksetup.pl. This will make sure you - are installing the modules in the right place. - - - - The permissions on your library directories are set incorrectly. - They must, at the very least, be readable by the web server user or - group. It is recommended that they be world readable. - - - -
- -
- DBD::Sponge::db prepare failed - - The following error message may appear due to a bug in DBD::mysql - (over which the Bugzilla team have no control): - - - - - To fix this, go to - <path-to-perl>/lib/DBD/sponge.pm - in your Perl installation and replace - - -{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } elsif ($attribs->{'NAME'}) { - $numFields = @{$attribs->{NAME}}; -]]> - - with - -{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } elsif ($attribs->{'NAMES'}) { - $numFields = @{$attribs->{NAMES}}; -]]> - - (note the S added to NAME.) -
- -
- cannot chdir(/var/spool/mqueue) - - If you are installing Bugzilla on SuSE Linux, or some other - distributions with paranoid security options, it is - possible that the checksetup.pl script may fail with the error: - - - - This is because your /var/spool/mqueue - directory has a mode of drwx------. - Type chmod 755 /var/spool/mqueue - as root to fix this problem. This will allow any process running on your - machine the ability to read the - /var/spool/mqueue directory. - -
- -
- Everybody is constantly being forced to relogin - - The most-likely cause is that the cookiepath parameter - is not set correctly in the Bugzilla configuration. You can change this (if - you're a Bugzilla administrator) from the editparams.cgi page via the web interface. - - - The value of the cookiepath parameter should be the actual directory - containing your Bugzilla installation, as seen by the end-user's - web browser. Leading and trailing slashes are mandatory. You can - also set the cookiepath to any directory which is a parent of the Bugzilla - directory (such as '/', the root directory). But you can't put something - that isn't at least a partial match or it won't work. What you're actually - doing is restricting the end-user's browser to sending the cookies back only - to that directory. - - - How do you know if you want your specific Bugzilla directory or the - whole site? - - - If you have only one Bugzilla running on the server, and you don't - mind having other applications on the same server with it being able to see - the cookies (you might be doing this on purpose if you have other things on - your site that share authentication with Bugzilla), then you'll want to have - the cookiepath set to "/", or to a sufficiently-high enough directory that - all of the involved apps can see the cookies. - - - - Examples of urlbase/cookiepath pairs for sharing login cookies - -
- -urlbase is http://bugzilla.mozilla.org/ -cookiepath is / - -urlbase is http://tools.mysite.tld/bugzilla/ - but you have http://tools.mysite.tld/someotherapp/ which shares - authentication with your Bugzilla -cookiepath is / - -
- - - On the other hand, if you have more than one Bugzilla running on the - server (some people do - we do on landfill) then you need to have the - cookiepath restricted enough so that the different Bugzillas don't - confuse their cookies with one another. - - - - - Examples of urlbase/cookiepath pairs to restrict the login cookie -
- -urlbase is http://landfill.bugzilla.org/bugzilla-tip/ -cookiepath is /bugzilla-tip/ - -urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/ -cookiepath is /bugzilla-4.0-branch/ - -
- - - If you had cookiepath set to / at any point in the - past and need to set it to something more restrictive - (i.e. /bugzilla/), you can safely do this without - requiring users to delete their Bugzilla-related cookies in their - browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5). - -
- -
- <filename>index.cgi</filename> doesn't show up unless specified in the URL - - You probably need to set up your web server in such a way that it - will serve the index.cgi page as an index page. - - - If you are using Apache, you can do this by adding - index.cgi to the end of the - DirectoryIndex line - as mentioned in . - - -
- -
- - checksetup.pl reports "Client does not support authentication protocol - requested by server..." - - - - This error is occurring because you are using the new password - encryption that comes with MySQL 4.1, while your - DBD::mysql module was compiled against an - older version of MySQL. If you recompile DBD::mysql - against the current MySQL libraries (or just obtain a newer version - of this module) then the error may go away. - - - - If that does not fix the problem, or if you cannot recompile the - existing module (e.g. you're running Windows) and/or don't want to - replace it (e.g. you want to keep using a packaged version), then a - workaround is available from the MySQL docs: - - - -
- - - - diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml deleted file mode 100644 index 4c7239bac..000000000 --- a/docs/en/xml/using.xml +++ /dev/null @@ -1,2087 +0,0 @@ - - - - %myents; -]> - - - Using Bugzilla - -
- Introduction - This section contains information for end-users of Bugzilla. There - is a Bugzilla test installation, called - Landfill, which you are - welcome to play with (if it's up). However, not all of the Bugzilla - installations there will necessarily have all Bugzilla features enabled, - and different installations run different versions, so some things may not - quite work as this document describes. - - - Frequently Asked Questions (FAQ) are available and answered on - wiki.mozilla.org. - They may cover some questions you have which are left unanswered. - -
- -
- Create a Bugzilla Account - - 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: - . - - - - - - On the home page index.cgi, click the - Open a new Bugzilla account link, or the - New Account link available in the footer of pages. - Now enter your email address, then click the Send - button. - - - - - If none of these links is available, this means that the - administrator of the installation has disabled self-registration. - This means that only an administrator can create accounts - for other users. One reason could be that this installation is - private. - - - - - - Also, if only some users are allowed to create an account on - the installation, you may see these links but your registration - may fail if your email address doesn't match the ones accepted - by the installation. This is another way to restrict who can - access and edit bugs in this installation. - - - - - - - Within moments, and if your registration is accepted, you should - receive an email to the address you provided, which contains your - login name (generally the same as the email address), and two URLs - with a token (a random string generated by the installation) to - confirm, respectively cancel, your registration. This is a way to - prevent users from abusing the generation of user accounts, for - instance by entering inexistent email addresses, or email addresses - which do not belong to them. - - - - - - By default, you have 3 days to confirm your registration. Past this - timeframe, the token is invalidated and the registration is - automatically canceled. You can also cancel this registration sooner - by using the appropriate URL in the email you got. - - - - - - If you confirm your registration, Bugzilla will ask you your real name - (optional, but recommended) and your password, which must be between - 3 and 16 characters long. - - - - - - Now all you need to do is to click the Log In - link in the footer at the bottom of the page in your browser, - enter your email address and password you just chose into the - login form, and click the Log in button. - - - - - - You are now logged in. Bugzilla uses cookies to remember you are - logged in so, unless you have cookies disabled or your IP address changes, - you should not have to log in again during your session. - -
- -
- Anatomy of a Bug - - The core of Bugzilla is the screen which displays a particular - bug. It's a good place to explain some Bugzilla concepts. - - Bug 1 on Landfill - - 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. - - - - - Product and Component: - 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: - - - Administration: - - - Administration of a Bugzilla installation. - - - - - - Bugzilla-General: - - - Anything that doesn't fit in the other components, or spans - multiple components. - - - - - - Creating/Changing Bugs: - - - Creating, changing, and viewing bugs. - - - - - - Documentation: - - - The Bugzilla documentation, including The Bugzilla Guide. - - - - - - Email: - - - Anything to do with email sent by Bugzilla. - - - - - - Installation: - - - The installation process of Bugzilla. - - - - - - Query/Buglist: - - - Anything to do with searching for bugs and viewing the - buglists. - - - - - - Reporting/Charting: - - - Getting reports from Bugzilla. - - - - - - User Accounts: - - - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc. - - - - - - User Interface: - - - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc. - - - - - - - - - - Status and Resolution: - - 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. - - - - - Assigned To: - The person responsible for fixing the bug. - - - - - *QA Contact: - The person responsible for quality assurance on this bug. - - - - - *URL: - A URL associated with the bug, if any. - - - - - Summary: - A one-sentence summary of the problem. - - - - - *Status Whiteboard: - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug. - - - - - *Keywords: - 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. - - - - - Platform and OS: - These indicate the computing environment where the bug was - found. - - - - - Version: - 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. - - - - - Priority: - The bug assignee uses this field to prioritize his or her bugs. - It's a good idea not to change this on other people's bugs. - - - - - Severity: - 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. - - - - - *Target: - (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. - - - - - Reporter: - The person who filed the bug. - - - - - CC list: - A list of people who get mail when the bug changes. - - - - - *Time Tracking: - This form can be used for time tracking. - To use this feature, you have to be blessed group membership - specified by the timetrackinggroup parameter. - - - Orig. Est.: - - - This field shows the original estimated time. - - - - - - Current Est.: - - - This field shows the current estimated time. - This number is calculated from Hours Worked - and Hours Left. - - - - - - Hours Worked: - - - This field shows the number of hours worked. - - - - - - Hours Left: - - - This field shows the Current Est. - - Hours Worked. - This value + Hours Worked will become the - new Current Est. - - - - - - %Complete: - - - This field shows what percentage of the task is complete. - - - - - - Gain: - - - This field shows the number of hours that the bug is ahead of the - Orig. Est.. - - - - - - Deadline: - - - This field shows the deadline for this bug. - - - - - - - - - - Attachments: - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. - - - - - - *Dependencies: - 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. - - - - - *Votes: - Whether this bug has any votes. - - - - - Additional Comments: - You can add your two cents to the bug discussion here, if you have - something worthwhile to say. - - -
- -
- Life Cycle of a Bug - - - The life cycle of a bug, also known as workflow, is customizable to match - the needs of your organization, see . - contains a graphical representation of - the default workflow using the default bug statuses. If you wish to - customize this image for your site, the - diagram file - is available in Dia's - native XML format. - - -
- Lifecycle of a Bugzilla Bug - - - - - -
-
- -
- Searching for Bugs - - The Bugzilla Search page is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - . - - The Search page has controls for selecting different possible - values for all of the fields in a bug, as described above. For some - fields, multiple values can be selected. In those cases, Bugzilla - returns bugs where the content of the field matches any one of the selected - values. If none is selected, then the field can take any value. - - - After a search is run, you can save it as a Saved Search, which - will appear in the page footer. If you are in the group defined - by the "querysharegroup" parameter, you may share your queries - with other users, see for more details. - - -
- Boolean Charts - - Highly advanced querying is done using Boolean Charts. - - - The boolean charts further restrict the set of results - returned by a query. It is possible to search for bugs - based on elaborate combinations of criteria. - - - The simplest boolean searches have only one term. These searches - permit the selected left field - to be compared using a - selectable operator to a - specified value. - Using the "And," "Or," and "Add Another Boolean Chart" buttons, - additional terms can be included in the query, further - altering the list of bugs returned by the query. - - - There are three fields in each row of a boolean search. - - - - - Field: - the items being searched - - - - - Operator: - the comparison operator - - - - - Value: - the value to which the field is being compared - - - -
- Pronoun Substitution - - Sometimes, a query needs to compare a user-related field - (such as ReportedBy) with a role-specific user (such as the - user running the query or the user to whom each bug is assigned). - When the operator is either "is equal to" or "is not equal to", the value - can be "%reporter%", "%assignee%", "%qacontact%", or "%user%". - The user pronoun - refers to the user who is executing the query or, in the case - of whining reports, the user who will be the recipient - of the report. The reporter, assignee, and qacontact - pronouns refer to the corresponding fields in the bug. - - - Boolean charts also let you type a group name in any user-related - field if the operator is either "is equal to", "is not equal to" or - "contains the string (exact case)". This will let you query for - any member belonging (or not) to the specified group. The group name - must be entered following the "%group.foo%" syntax, where "foo" is - the group name. So if you are looking for bugs reported by any user - being in the "editbugs" group, then you can type "%group.editbugs%". - -
-
- Negation - - At first glance, negation seems redundant. Rather than - searching for -
- - NOT("summary" "contains the string" "foo"), - -
- one could search for -
- - ("summary" "does not contain the string" "foo"). - -
- However, the search -
- - ("CC" "does not contain the string" "@mozilla.org") - -
- would find every bug where anyone on the CC list did not contain - "@mozilla.org" while -
- - NOT("CC" "contains the string" "@mozilla.org") - -
- would find every bug where there was nobody on the CC list who - did contain the string. Similarly, the use of negation also permits - complex expressions to be built using terms OR'd together and then - negated. Negation permits queries such as -
- - NOT(("product" "is equal to" "update") OR - ("component" "is equal to" "Documentation")) - -
- to find bugs that are neither - in the update product or in the documentation component or -
- - NOT(("commenter" "is equal to" "%assignee%") OR - ("component" "is equal to" "Documentation")) - -
- to find non-documentation - bugs on which the assignee has never commented. - -
-
- Multiple Charts - - The terms within a single row of a boolean chart are all - constraints on a single piece of data. If you are looking for - a bug that has two different people cc'd on it, then you need - to use two boolean charts. A search for -
- - ("cc" "contains the string" "foo@") AND - ("cc" "contains the string" "@mozilla.org") - -
- would return only bugs with "foo@mozilla.org" on the cc list. - If you wanted bugs where there is someone on the cc list - containing "foo@" and someone else containing "@mozilla.org", - then you would need two boolean charts. -
- - First chart: ("cc" "contains the string" "foo@") - - - Second chart: ("cc" "contains the string" "@mozilla.org") - -
- The bugs listed will be only the bugs where ALL the charts are true. - -
-
- -
- Quicksearch - - - Quicksearch is a single-text-box query tool which uses - metacharacters to indicate what is to be searched. For example, typing - "foo|bar" - into Quicksearch would search for "foo" or "bar" in the - summary and status whiteboard of a bug; adding - ":BazProduct" would - search only in that product. - You can use it to find a bug by its number or its alias, too. - - - - You'll find the Quicksearch box in Bugzilla's footer area. - On Bugzilla's front page, there is an additional - Help - link which details how to use it. - -
-
- Case Sensitivity in Searches - - Bugzilla queries are case-insensitive and accent-insensitive, when - used with either MySQL or Oracle databases. When using Bugzilla with - PostgreSQL, however, some queries are case-sensitive. This is due to - the way PostgreSQL handles case and accent sensitivity. - -
-
- Bug Lists - - If you run a search, a list of matching bugs will be returned. - - - 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: - - - Long Format: - - - this gives you a large page with a non-editable summary of the fields - of each bug. - - - - - - XML: - - - get the buglist in the XML format. - - - - - - CSV: - - - get the buglist as comma-separated values, for import into e.g. - a spreadsheet. - - - - - - Feed: - - - get the buglist as an Atom feed. Copy this link into your - favorite feed reader. If you are using Firefox, you can also - save the list as a live bookmark by clicking the live bookmark - icon in the status bar. To limit the number of bugs in the feed, - add a limit=n parameter to the URL. - - - - - - iCalendar: - - - Get the buglist as an iCalendar file. Each bug is represented as a - to-do item in the imported calendar. - - - - - - Change Columns: - - - change the bug attributes which appear in the list. - - - - - - Change several bugs at once: - - - If your account is sufficiently empowered, and more than one bug - appear in the bug list, this link is displayed which lets you make - the same change to all the bugs in the list - for example, changing - their assignee. - - - - - - Send mail to bug assignees: - - - If more than one bug appear in the bug list and there are at least - two distinct bug assignees, this links is displayed which lets you - easily send a mail to the assignees of all bugs on the list. - - - - - - Edit Search: - - - 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. - - - - - - Remember Search As: - - - You can give a search a name and remember it; a link will appear - in your page footer giving you quick access to run it again later. - - - - - -
- -
- Adding/removing tags to/from bugs - - You can add and remove tags from individual bugs, which let you find and - manage bugs more easily. Tags are per-user and so are only visible and editable - by the user who created them. You can then run queries using tags as a criteria, - either by using the Advanced Search form, or simply by typing "tag:my_tag_name" - in the QuickSearch box at the top (or bottom) of the page. Tags can also be - displayed in buglists. - - - - This feature is useful when you want to keep track of several bugs, but - for different reasons. Instead of adding yourself to the CC list of all - these bugs and mixing all these reasons, you can now store these bugs in - separate lists, e.g. Keep in mind, Interesting bugs, - or Triage. One big advantage of this way to manage bugs - is that you can easily add or remove tags from bugs one by one. - -
-
- -
- Filing Bugs - -
- Reporting a New Bug - - Years of bug writing experience has been distilled for your - reading pleasure into the - - Bug Writing Guidelines. - 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. - - The procedure for filing a bug is as follows: - - - - - Click the New link available in the footer - of pages, or the Enter a new bug report link - displayed on the home page of the Bugzilla installation. - - - - - If you want to file a test bug to see how Bugzilla works, - you can do it on one of our test installations on - Landfill. - - - - - - - You first have to select the product in which you found a bug. - - - - - - You now see a form where you can specify the component (part of - the product which is affected by the bug you discovered; if you have - no idea, just select General if such a component exists), - the version of the program you were using, the Operating System and - platform your program is running on and the severity of the bug (if the - bug you found crashes the program, it's probably a major or a critical - bug; if it's a typo somewhere, that's something pretty minor; if it's - something you would like to see implemented, then that's an enhancement). - - - - - - You now have to give a short but descriptive summary of the bug you found. - My program is crashing all the time is a very poor summary - and doesn't help developers at all. Try something more meaningful or - your bug will probably be ignored due to a lack of precision. - The next step is to give a very detailed list of steps to reproduce - the problem you encountered. Try to limit these steps to a minimum set - required to reproduce the problem. This will make the life of - developers easier, and the probability that they consider your bug in - a reasonable timeframe will be much higher. - - - - - Try to make sure that everything in the summary is also in the first - comment. Summaries are often updated and this will ensure your original - information is easily accessible. - - - - - - - As you file the bug, you can also attach a document (testcase, patch, - or screenshot of the problem). - - - - - - Depending on the Bugzilla installation you are using and the product in - which you are filing the bug, you can also request developers to consider - your bug in different ways (such as requesting review for the patch you - just attached, requesting your bug to block the next release of the - product, and many other product specific requests). - - - - - - Now is a good time to read your bug report again. Remove all misspellings, - otherwise your bug may not be found by developers running queries for some - specific words, and so your bug would not get any attention. - Also make sure you didn't forget any important information developers - should know in order to reproduce the problem, and make sure your - description of the problem is explicit and clear enough. - When you think your bug report is ready to go, the last step is to - click the Commit button to add your report into the database. - - - - - - 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. - - - 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. - -
- -
- Clone an Existing Bug - - - Starting with version 2.20, Bugzilla has a feature that allows you - to clone an existing bug. The newly created bug will inherit - most settings from the old bug. This allows you to track more - easily similar concerns in a new bug. To use this, go to the bug - that you want to clone, then click the Clone This Bug - link on the bug page. This will take you to the Enter Bug - page that is filled with the values that the old bug has. - You can change those values and/or texts if needed. - -
- -
- -
- Attachments - - - You should use attachments, rather than comments, for large chunks of ASCII - data, such as trace, debugging output files, or log files. That way, it - doesn't bloat the bug for everyone who wants to read it, and cause people to - receive fat, useless mails. - - - You should make sure to trim screenshots. There's no need to show the - whole screen if you are pointing out a single-pixel problem. - - - Bugzilla stores and uses a Content-Type for each attachment - (e.g. text/html). To download an attachment as a different - Content-Type (e.g. application/xhtml+xml), you can override this - using a 'content_type' parameter on the URL, e.g. - &content_type=text/plain. - - - - Also, you can enter the URL pointing to the attachment instead of - uploading the attachment itself. For example, this is useful if you want to - point to an external application, a website or a very large file. Note that - there is no guarantee that the source file will always be available, nor - that its content will remain unchanged. - - - - Another way to attach data is to paste text directly in the text field, - and Bugzilla will convert it into an attachment. This is pretty useful - when you do copy and paste, and you don't want to put the text in a temporary - file first. - - -
- Patch Viewer - - Viewing and reviewing patches in Bugzilla is often difficult due to - lack of context, improper format and the inherent readability issues that - raw patches present. Patch Viewer is an enhancement to Bugzilla designed - to fix that by offering increased context, linking to sections, and - integrating with Bonsai, LXR and CVS. - - Patch viewer allows you to: - - - View patches in color, with side-by-side view rather than trying - to interpret the contents of the patch. - See the difference between two patches. - Get more context in a patch. - Collapse and expand sections of a patch for easy - reading. - Link to a particular section of a patch for discussion or - review - Go to Bonsai or LXR to see more context, blame, and - cross-references for the part of the patch you are looking at - Create a rawtext unified format diff out of any patch, no - matter what format it came from - - -
- Viewing Patches in Patch Viewer - The main way to view a patch in patch viewer is to click on the - "Diff" link next to a patch in the Attachments list on a bug. You may - also do this within the edit window by clicking the "View Attachment As - Diff" button in the Edit Attachment screen. -
- -
- Seeing the Difference Between Two Patches - To see the difference between two patches, you must first view the - newer patch in Patch Viewer. Then select the older patch from the - dropdown at the top of the page ("Differences between [dropdown] and - this patch") and click the "Diff" button. This will show you what - is new or changed in the newer patch. -
- -
- Getting More Context in a Patch - To get more context in a patch, you put a number in the textbox at - the top of Patch Viewer ("Patch / File / [textbox]") and hit enter. - This will give you that many lines of context before and after each - change. Alternatively, you can click on the "File" link there and it - will show each change in the full context of the file. This feature only - works against files that were diffed using "cvs diff". -
- -
- Collapsing and Expanding Sections of a Patch - To view only a certain set of files in a patch (for example, if a - patch is absolutely huge and you want to only review part of it at a - time), you can click the "(+)" and "(-)" links next to each file (to - expand it or collapse it). If you want to collapse all files or expand - all files, you can click the "Collapse All" and "Expand All" links at the - top of the page. -
- - - -
- Going to Bonsai and LXR - To go to Bonsai to get blame for the lines you are interested in, - you can click the "Lines XX-YY" link on the section header you are - interested in. This works even if the patch is against an old - version of the file, since Bonsai stores all versions of the file. - - To go to LXR, you click on the filename on the file header - (unfortunately, since LXR only does the most recent version, line - numbers are likely to rot). -
- -
- Creating a Unified Diff - If the patch is not in a format that you like, you can turn it - into a unified diff format by clicking the "Raw Unified" link at the top - of the page. -
-
-
- -
- Hints and Tips - - This section distills some Bugzilla tips and best practices - that have been developed. - -
- Autolinkification - Bugzilla comments are plain text - so typing <U> will - produce less-than, U, greater-than rather than underlined text. - However, Bugzilla will automatically make hyperlinks out of certain - sorts of text in comments. For example, the text - "http://www.bugzilla.org" will be turned into a link: - . - Other strings which get linkified in the obvious manner are: - - bug 12345 - comment 7 - bug 23456, comment 53 - attachment 4321 - mailto:george@example.com - george@example.com - ftp://ftp.mozilla.org - Most other sorts of URL - - - - 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. - -
- -
- Comments - - 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. - - - - Don't use sigs in comments. Signing your name ("Bill") is acceptable, - if you do it out of habit, but full mail/news-style - four line ASCII art creations are not. - -
- -
- Server-Side Comment Wrapping - - Bugzilla stores comments unwrapped and wraps them at display time. This - ensures proper wrapping in all browsers. Lines beginning with the ">" - character are assumed to be quotes, and are not wrapped. - -
- -
- Dependency Tree - - - On the Dependency tree page linked from each bug - page, you can see the dependency relationship from the bug as a - tree structure. - - - - You can change how much depth to show, and you can hide resolved bugs - from this page. You can also collaps/expand dependencies for - each bug on the tree view, using the [-]/[+] buttons that appear - before its summary. This option is not available for terminal - bugs in the tree (that don't have further dependencies). - -
-
- -
- Time Tracking Information - - - Users who belong to the group specified by the timetrackinggroup - parameter have access to time-related fields. Developers can see - deadlines and estimated times to fix bugs, and can provide time spent - on these bugs. Users who do not belong to this group can only see the deadline, - but not edit it. Other time-related fields remain invisible to them. - - - - At any time, a summary of the time spent by developers on bugs is - accessible either from bug lists when clicking the Time Summary - button or from individual bugs when clicking the Summarize time - link in the time tracking table. The summarize_time.cgi - page lets you view this information either per developer or per bug, - and can be split on a month basis to have greater details on how time - is spent by developers. - - - - As soon as a bug is marked as RESOLVED, the remaining time expected - to fix the bug is set to zero. This lets QA people set it again for - their own usage, and it will be set to zero again when the bug will - be marked as CLOSED. - -
- -
- User Preferences - - - Once logged in, you can customize various aspects of - Bugzilla via the "Preferences" link in the page footer. - The preferences are split into five tabs: - -
- General Preferences - - - This tab allows you to change several default settings of Bugzilla. - - - - - - Bugzilla's general appearance (skin) - select which skin to use. - Bugzilla supports adding custom skins. - - - - - Quote the associated comment when you click on its reply link - sets - the behavior of the comment "Reply" link. Options include quoting the - full comment, just reference the comment number, or turn the link off. - - - - - Language used in email - select which language email will be sent in, - from the list of available languages. - - - - - After changing a bug - This controls what page is displayed after - changes to a bug are submitted. The options include to show the bug - just modified, to show the next bug in your list, or to do nothing. - - - - - Enable tags for bugs - turn bug tagging on or off. - - - - - Zoom textareas large when in use (requires JavaScript) - enable or - disable the automatic expanding of text areas when text is being - entered into them. - - - - - Field separator character for CSV files - - Select between a comma and semi-colon for exported CSV bug lists. - - - - - Automatically add me to the CC list of bugs I change - set default - behavior of CC list. Options include "Always", "Never", and "Only - if I have no role on them". - - - - - When viewing a bug, show comments in this order - - controls the order of comments. Options include "Oldest - to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the - bug description at the top". - - - - - Show a quip at the top of each bug list - controls - whether a quip will be shown on the Bug list page. - - - -
- -
- Email Preferences - - - This tab allows you to enable or disable email notification on - specific events. - - - - In general, users have almost complete control over how much (or - how little) email Bugzilla sends them. If you want to receive the - maximum amount of email possible, click the Enable All - Mail button. If you don't want to receive any email from - Bugzilla at all, click the Disable All Mail button. - - - - - A Bugzilla administrator can stop a user from receiving - bugmail by clicking the Bugmail Disabled checkbox - when editing the user account. This is a drastic step - best taken only for disabled accounts, as it overrides - the user's individual mail preferences. - - - - - There are two global options -- Email me when someone - asks me to set a flag and Email me when someone - sets a flag I asked for. These define how you want to - receive bugmail with regards to flags. Their use is quite - straightforward; enable the checkboxes if you want Bugzilla to - send you mail under either of the above conditions. - - - - If you'd like to set your bugmail to something besides - 'Completely ON' and 'Completely OFF', the - Field/recipient specific options table - allows you to do just that. The rows of the table - define events that can happen to a bug -- things like - attachments being added, new comments being made, the - priority changing, etc. The columns in the table define - your relationship with the bug: - - - - - - Reporter - Where you are the person who initially - reported the bug. Your name/account appears in the - Reporter: field. - - - - - Assignee - Where you are the person who has been - designated as the one responsible for the bug. Your - name/account appears in the Assigned To: - field of the bug. - - - - - QA Contact - You are one of the designated - QA Contacts for the bug. Your account appears in the - QA Contact: text-box of the bug. - - - - - CC - You are on the list CC List for the bug. - Your account appears in the CC: text box - of the bug. - - - - - Voter - You have placed one or more votes for the bug. - Your account appears only if someone clicks on the - Show votes for this bug link on the bug. - - - - - - - Some columns may not be visible for your installation, depending - on your site's configuration. - - - - - To fine-tune your bugmail, decide the events for which you want - to receive bugmail; then decide if you want to receive it all - the time (enable the checkbox for every column), or only when - you have a certain relationship with a bug (enable the checkbox - only for those columns). For example: if you didn't want to - receive mail when someone added themselves to the CC list, you - could uncheck all the boxes in the CC Field Changes - line. As another example, if you never wanted to receive email - on bugs you reported unless the bug was resolved, you would - un-check all boxes in the Reporter column - except for the one on the The bug is resolved or - verified row. - - - - - Bugzilla adds the X-Bugzilla-Reason header to - all bugmail it sends, describing the recipient's relationship - (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug. - This header can be used to do further client-side filtering. - - - - - Bugzilla has a feature called Users Watching. - When you enter one or more comma-delineated user accounts (usually email - addresses) into the text entry box, you will receive a copy of all the - bugmail those users are sent (security settings permitting). - This powerful functionality enables seamless transitions as developers - change projects or users go on holiday. - - - - - The ability to watch other users may not be available in all - Bugzilla installations. If you don't see this feature, and feel - that you need it, speak to your administrator. - - - - - Each user listed in the Users watching you field - has you listed in their Users to watch list - and can get bugmail according to your relationship to the bug and - their Field/recipient specific options setting. - - - - The Ignore Bugs section lets you specify a - comma-separated list of bugs from which you never want to get any - email notification of any kind. Removing a bug from this list will - re-enable email notification for this bug. This is especially useful - e.g. if you are the reporter of a very noisy bug which you are not - interested in anymore or if you are watching someone who is in such - a noisy bug. - -
- -
- Saved Searches - - On this tab you can view and run any Saved Searches that you have - created, and also any Saved Searches that other members of the group - defined in the "querysharegroup" parameter have shared. - Saved Searches can be added to the page footer from this screen. - If somebody is sharing a Search with a group she or he is allowed to - assign users to, the sharer may opt to have - the Search show up in the footer of the group's direct members by default. - -
- -
- Name and Password - - 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 - current password into the Password - 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. -
- -
- Permissions - - - This is a purely informative page which outlines your current - permissions on this installation of Bugzilla. - - - - A complete list of permissions is below. Only users with - editusers privileges can change the permissions - of other users. - - - - - - admin - - - - Indicates user is an Administrator. - - - - - - - bz_canusewhineatothers - - - - Indicates user can configure whine reports for other users. - - - - - - - bz_canusewhines - - - - Indicates user can configure whine reports for self. - - - - - - - bz_quip_moderators - - - - Indicates user can moderate quips. - - - - - - - bz_sudoers - - - - Indicates user can perform actions as other users. - - - - - - - bz_sudo_protect - - - - Indicates user cannot be impersonated by other users. - - - - - - - canconfirm - - - - Indicates user can confirm a bug or mark it a duplicate. - - - - - - - creategroups - - - - Indicates user can create and destroy groups. - - - - - - - editbugs - - - - Indicates user can edit all bug fields. - - - - - - - editclassifications - - - - Indicates user can create, destroy, and edit classifications. - - - - - - - editcomponents - - - - Indicates user can create, destroy, and edit components. - - - - - - - editkeywords - - - - Indicates user can create, destroy, and edit keywords. - - - - - - - editusers - - - - Indicates user can edit or disable users. - - - - - - - tweakparams - - - - Indicates user can change Parameters. - - - - - - - - - For more information on how permissions work in Bugzilla (i.e. who can - change what), see . - - - -
-
- - -
- Reports and Charts - - As well as the standard buglist, Bugzilla has two more ways of - viewing sets of bugs. These are the reports (which give different - views of the current state of the database) and charts (which plot - the changes in particular sets of bugs over time.) - -
- Reports - - - A report is a view of the current state of the bug database. - - - - You can run either an HTML-table-based report, or a graphical - line/pie/bar-chart-based one. The two have different pages to - define them, but are close cousins - once you've defined and - viewed a report, you can switch between any of the different - views of the data at will. - - - - Both report types are based on the idea of defining a set of bugs - using the standard search interface, and then choosing some - aspect of that set to plot on the horizontal and/or vertical axes. - You can also get a form of 3-dimensional report by choosing to have - multiple images or tables. - - - - So, for example, you could use the search form to choose "all - bugs in the WorldControl product", and then plot their severity - against their component to see which component had had the largest - number of bad bugs reported against it. - - - - Once you've defined your parameters and hit "Generate Report", - you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie - is only available if you didn't define a vertical axis, as pie - charts don't have one.) The other controls are fairly self-explanatory; - you can change the size of the image if you find text is overwriting - other text, or the bars are too thin to see. - - -
- -
- Charts - - - A chart is a view of the state of the bug database over time. - - - - Bugzilla currently has two charting systems - Old Charts and New - Charts. Old Charts have been part of Bugzilla for a long time; they - chart each status and resolution for each product, and that's all. - They are deprecated, and going away soon - we won't say any more - about them. - New Charts are the future - they allow you to chart anything you - can define as a search. - - - - - Both charting forms require the administrator to set up the - data-gathering script. If you can't see any charts, ask them whether - they have done so. - - - - - An individual line on a chart is called a data set. - All data sets are organised into categories and subcategories. The - data sets that Bugzilla defines automatically use the Product name - as a Category and Component names as Subcategories, but there is no - need for you to follow that naming scheme with your own charts if - you don't want to. - - - - Data sets may be public or private. Everyone sees public data sets in - the list, but only their creator sees private data sets. Only - administrators can make data sets public. - No two data sets, even two private ones, can have the same set of - category, subcategory and name. So if you are creating private data - sets, one idea is to have the Category be your username. - - -
- Creating Charts - - - You create a chart by selecting a number of data sets from the - list, and pressing Add To List for each. In the List Of Data Sets - To Plot, you can define the label that data set will have in the - chart's legend, and also ask Bugzilla to Sum a number of data sets - (e.g. you could Sum data sets representing RESOLVED, VERIFIED and - CLOSED in a particular product to get a data set representing all - the resolved bugs in that product.) - - - - If you've erroneously added a data set to the list, select it - using the checkbox and click Remove. Once you add more than one - data set, a "Grand Total" line - automatically appears at the bottom of the list. If you don't want - this, simply remove it as you would remove any other line. - - - - You may also choose to plot only over a certain date range, and - to cumulate the results - that is, to plot each one using the - previous one as a baseline, so the top line gives a sum of all - the data sets. It's easier to try than to explain :-) - - - - Once a data set is in the list, one can also perform certain - actions on it. For example, one can edit the - data set's parameters (name, frequency etc.) if it's one you - created or if you are an administrator. - - - - Once you are happy, click Chart This List to see the chart. - - -
- -
- Creating New Data Sets - - - You may also create new data sets of your own. To do this, - click the "create a new data set" link on the Create Chart page. - This takes you to a search-like interface where you can define - the search that Bugzilla will plot. At the bottom of the page, - you choose the category, sub-category and name of your new - data set. - - - - If you have sufficient permissions, you can make the data set public, - and reduce the frequency of data collection to less than the default - seven days. - -
- -
- -
- -
- Flags - - - A flag is a kind of status that can be set on bugs or attachments - to indicate that the bugs/attachments are in a certain state. - Each installation can define its own set of flags that can be set - on bugs or attachments. - - - - If your installation has defined a flag, you can set or unset that flag, - and if your administrator has enabled requesting of flags, you can submit - a request for another user to set the flag. - - - - To set a flag, select either "+" or "-" from the drop-down menu next to - the name of the flag in the "Flags" list. The meaning of these values are - flag-specific and thus cannot be described in this documentation, - but by way of example, setting a flag named "review" to "+" may indicate - that the bug/attachment has passed review, while setting it to "-" - may indicate that the bug/attachment has failed review. - - - - To unset a flag, click its drop-down menu and select the blank value. - Note that marking an attachment as obsolete automatically cancels all - pending requests for the attachment. - - - - If your administrator has enabled requests for a flag, request a flag - by selecting "?" from the drop-down menu and then entering the username - of the user you want to set the flag in the text field next to the menu. - - - - A set flag appears in bug reports and on "edit attachment" pages with the - abbreviated username of the user who set the flag prepended to the - flag name. For example, if Jack sets a "review" flag to "+", it appears - as Jack: review [ + ] - - - - A requested flag appears with the user who requested the flag prepended - to the flag name and the user who has been requested to set the flag - appended to the flag name within parentheses. For example, if Jack - asks Jill for review, it appears as Jack: review [ ? ] (Jill). - - - - You can browse through open requests made of you and by you by selecting - 'My Requests' from the footer. You can also look at open requests limited - by other requesters, requestees, products, components, and flag names from - this page. Note that you can use '-' for requestee to specify flags with - 'no requestee' set. - -
- -
- Whining - - - Whining is a feature in Bugzilla that can regularly annoy users at - specified times. Using this feature, users can execute saved searches - at specific times (i.e. the 15th of the month at midnight) or at - regular intervals (i.e. every 15 minutes on Sundays). The results of the - searches are sent to the user, either as a single email or as one email - per bug, along with some descriptive text. - - - - - Throughout this section it will be assumed that all users are members - of the bz_canusewhines group, membership in which is required in order - to use the Whining system. You can easily make all users members of - the bz_canusewhines group by setting the User RegExp to ".*" (without - the quotes). - - - - Also worth noting is the bz_canusewhineatothers group. Members of this - group can create whines for any user or group in Bugzilla using a - extended form of the whining interface. Features only available to - members of the bz_canusewhineatothers group will be noted in the - appropriate places. - - - - - - For whining to work, a special Perl script must be executed at regular - intervals. More information on this is available in - . - - - - - - This section does not cover the whineatnews.pl script. See - for more information on - The Whining Cron. - - - -
- The Event - - - The whining system defines an "Event" as one or more queries being - executed at regular intervals, with the results of said queries (if - there are any) being emailed to the user. Events are created by - clicking on the "Add new event" button. - - - - Once a new event is created, the first thing to set is the "Email - subject line". The contents of this field will be used in the subject - line of every email generated by this event. In addition to setting a - subject, space is provided to enter some descriptive text that will be - included at the top of each message (to help you in understanding why - you received the email in the first place). - - - - The next step is to specify when the Event is to be run (the Schedule) - and what searches are to be performed (the Searches). - - -
- -
- Whining Schedule - - - Each whining event is associated with zero or more schedules. A - schedule is used to specify when the search (specified below) is to be - run. A new event starts out with no schedules (which means it will - never run, as it is not scheduled to run). To add a schedule, press - the "Add a new schedule" button. - - - - Each schedule includes an interval, which you use to tell Bugzilla - when the event should be run. An event can be run on certain days of - the week, certain days of the month, during weekdays (defined as - Monday through Friday), or every day. - - - - - Be careful if you set your event to run on the 29th, 30th, or 31st of - the month, as your event may not run exactly when expected. If you - want your event to run on the last day of the month, select "Last day - of the month" as the interval. - - - - - Once you have specified the day(s) on which the event is to be run, you - should now specify the time at which the event is to be run. You can - have the event run at a certain hour on the specified day(s), or - every hour, half-hour, or quarter-hour on the specified day(s). - - - - If a single schedule does not execute an event as many times as you - would want, you can create another schedule for the same event. For - example, if you want to run an event on days whose numbers are - divisible by seven, you would need to add four schedules to the event, - setting the schedules to run on the 7th, 14th, 21st, and 28th (one day - per schedule) at whatever time (or times) you choose. - - - - - If you are a member of the bz_canusewhineatothers group, then you - will be presented with another option: "Mail to". Using this you - can control who will receive the emails generated by this event. You - can choose to send the emails to a single user (identified by email - address) or a single group (identified by group name). To send to - multiple users or groups, create a new schedule for each additional - user/group. - - -
- -
- Whining Searches - - - Each whining event is associated with zero or more searches. A search - is any saved search to be run as part of the specified schedule (see - above). You start out without any searches associated with the event - (which means that the event will not run, as there will never be any - results to return). To add a search, press the "Add a search" button. - - - - The first field to examine in your newly added search is the Sort field. - Searches are run, and results included, in the order specified by the - Sort field. Searches with smaller Sort values will run before searches - with bigger Sort values. - - - - The next field to examine is the Search field. This is where you - choose the actual search that is to be run. Instead of defining search - parameters here, you are asked to choose from the list of saved - searches (the same list that appears at the bottom of every Bugzilla - page). You are only allowed to choose from searches that you have - saved yourself (the default saved search, "My Bugs", is not a valid - choice). If you do not have any saved searches, you can take this - opportunity to create one (see ). - - - - - When running searches, the whining system acts as if you are the user - executing the search. This means that the whining system will ignore - bugs that match your search, but that you cannot access. - - - - - Once you have chosen the saved search to be executed, give the search a - descriptive title. This title will appear in the email, above the - results of the search. If you choose "One message per bug", the search - title will appear at the top of each email that contains a bug matching - your search. - - - - Finally, decide if the results of the search should be sent in a single - email, or if each bug should appear in its own email. - - - - - Think carefully before checking the "One message per bug" box. If - you create a search that matches thousands of bugs, you will receive - thousands of emails! - - -
- -
- Saving Your Changes - - - Once you have defined at least one schedule, and created at least one - search, go ahead and "Update/Commit". This will save your Event and make - it available for immediate execution. - - - - - If you ever feel like deleting your event, you may do so using the - "Remove Event" button in the upper-right corner of each Event. You - can also modify an existing event, so long as you "Update/Commit" - after completing your modifications. - - -
- -
- - - - diff --git a/docs/makedocs.pl b/docs/makedocs.pl index ea08d8258..74843c7a3 100755 --- a/docs/makedocs.pl +++ b/docs/makedocs.pl @@ -7,6 +7,19 @@ # defined by the Mozilla Public License, v. 2.0. # This script compiles all the documentation. +# +# Required software: +# +# 1) Sphinx documentation builder (python-sphinx package on Debian/Ubuntu) +# +# 2) pdflatex, which means the following Debian/Ubuntu packages: +# * texlive-latex-base +# * texlive-latex-recommended +# * texlive-latex-extra +# * texlive-fonts-recommended +# +# All these TeX packages together are close to a gig :-| But after you've +# installed them, you can remove texlive-latex-extra-doc to save 400MB. use 5.10.1; use strict; @@ -33,7 +46,7 @@ if (eval { require Pod::Simple }) { $pod_simple = 1; }; -use Bugzilla::Install::Requirements +use Bugzilla::Install::Requirements qw(REQUIRED_MODULES OPTIONAL_MODULES); use Bugzilla::Constants qw(DB_MODULE BUGZILLA_VERSION); @@ -46,15 +59,19 @@ my $opt_modules = OPTIONAL_MODULES; my $template; { - open(TEMPLATE, '<', 'bugzilla.ent.tmpl') - or die('Could not open bugzilla.ent.tmpl: ' . $!); + open(TEMPLATE, '<', 'definitions.rst.tmpl') + or die('Could not open definitions.rst.tmpl: ' . $!); local $/; $template =