diff options
Diffstat (limited to 'docs/en/xml/using.xml')
| -rw-r--r-- | docs/en/xml/using.xml | 2072 |
1 files changed, 0 insertions, 2072 deletions
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml deleted file mode 100644 index c806da269..000000000 --- a/docs/en/xml/using.xml +++ /dev/null @@ -1,2072 +0,0 @@ -<?xml version="1.0"?> -<!-- This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. - - This Source Code Form is "Incompatible With Secondary Licenses", as - defined by the Mozilla Public License, v. 2.0. ---> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - <!ENTITY % myents SYSTEM "bugzilla.ent"> - %myents; -]> - -<chapter id="using"> - <title>Using Bugzilla</title> - - <section id="using-intro"> - <title>Introduction</title> - <para>This section contains information for end-users of Bugzilla. There - is a Bugzilla test installation, called - <ulink url="http://landfill.bugzilla.org/">Landfill</ulink>, which you are - welcome to play with (if it's up). However, not all of the Bugzilla - installations there will necessarily have all Bugzilla features enabled, - and different installations run different versions, so some things may not - quite work as this document describes.</para> - - <para> - Frequently Asked Questions (FAQ) are available and answered on - <ulink url="http://wiki.mozilla.org/Bugzilla:FAQ">wiki.mozilla.org</ulink>. - They may cover some questions you have which are left unanswered. - </para> - </section> - - <section id="myaccount"> - <title>Create a Bugzilla Account</title> - - <para>If you want to use Bugzilla, first you need to create an account. - Consult with the administrator responsible for your installation of - Bugzilla for the URL you should use to access it. If you're - test-driving Bugzilla, use this URL: - <ulink url="&landfillbase;"/>. - </para> - - <orderedlist> - <listitem> - <para> - On the home page <filename>index.cgi</filename>, click the - <quote>Open a new Bugzilla account</quote> link, or the - <quote>New Account</quote> link available in the footer of pages. - Now enter your email address, then click the <quote>Send</quote> - button. - </para> - - <note> - <para> - If none of these links is available, this means that the - administrator of the installation has disabled self-registration. - This means that only an administrator can create accounts - for other users. One reason could be that this installation is - private. - </para> - </note> - - <note> - <para> - Also, if only some users are allowed to create an account on - the installation, you may see these links but your registration - may fail if your email address doesn't match the ones accepted - by the installation. This is another way to restrict who can - access and edit bugs in this installation. - </para> - </note> - </listitem> - - <listitem> - <para> - Within moments, and if your registration is accepted, you should - receive an email to the address you provided, which contains your - login name (generally the same as the email address), and two URLs - with a token (a random string generated by the installation) to - confirm, respectively cancel, your registration. This is a way to - prevent users from abusing the generation of user accounts, for - instance by entering inexistent email addresses, or email addresses - which do not belong to them. - </para> - </listitem> - - <listitem> - <para> - By default, you have 3 days to confirm your registration. Past this - timeframe, the token is invalidated and the registration is - automatically canceled. You can also cancel this registration sooner - by using the appropriate URL in the email you got. - </para> - </listitem> - - <listitem> - <para> - If you confirm your registration, Bugzilla will ask you your real name - (optional, but recommended) and your password, which must be between - 3 and 16 characters long. - </para> - </listitem> - - <listitem> - <para> - Now all you need to do is to click the <quote>Log In</quote> - link in the footer at the bottom of the page in your browser, - enter your email address and password you just chose into the - login form, and click the <quote>Log in</quote> button. - </para> - </listitem> - </orderedlist> - - <para> - You are now logged in. Bugzilla uses cookies to remember you are - logged in so, unless you have cookies disabled or your IP address changes, - you should not have to log in again during your session. - </para> - </section> - - <section id="bug_page"> - <title>Anatomy of a Bug</title> - - <para>The core of Bugzilla is the screen which displays a particular - bug. It's a good place to explain some Bugzilla concepts. - <ulink - url="&landfillbase;show_bug.cgi?id=1"> - Bug 1 on Landfill</ulink> - - is a good example. Note that the labels for most fields are hyperlinks; - clicking them will take you to context-sensitive help on that - particular field. Fields marked * may not be present on every - installation of Bugzilla.</para> - - <orderedlist> - <listitem> - <para> - <emphasis>Product and Component</emphasis>: - Bugs are divided up by Product and Component, with a Product - having one or more Components in it. For example, - bugzilla.mozilla.org's "Bugzilla" Product is composed of several - Components: - <variablelist> - <varlistentry> - <term>Administration:</term> - <listitem> - <para> - Administration of a Bugzilla installation. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Bugzilla-General:</term> - <listitem> - <para> - Anything that doesn't fit in the other components, or spans - multiple components. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Creating/Changing Bugs:</term> - <listitem> - <para> - Creating, changing, and viewing bugs. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Documentation:</term> - <listitem> - <para> - The Bugzilla documentation, including The Bugzilla Guide. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Email:</term> - <listitem> - <para> - Anything to do with email sent by Bugzilla. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Installation:</term> - <listitem> - <para> - The installation process of Bugzilla. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Query/Buglist:</term> - <listitem> - <para> - Anything to do with searching for bugs and viewing the - buglists. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Reporting/Charting:</term> - <listitem> - <para> - Getting reports from Bugzilla. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>User Accounts:</term> - <listitem> - <para> - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>User Interface:</term> - <listitem> - <para> - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Status and Resolution:</emphasis> - - These define exactly what state the bug is in - from not even - being confirmed as a bug, through to being fixed and the fix - confirmed by Quality Assurance. The different possible values for - Status and Resolution on your installation should be documented in the - context-sensitive help for those items.</para> - </listitem> - - <listitem> - <para> - <emphasis>Assigned To:</emphasis> - The person responsible for fixing the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*QA Contact:</emphasis> - The person responsible for quality assurance on this bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*URL:</emphasis> - A URL associated with the bug, if any.</para> - </listitem> - - <listitem> - <para> - <emphasis>Summary:</emphasis> - A one-sentence summary of the problem.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Status Whiteboard:</emphasis> - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Keywords:</emphasis> - The administrator can define keywords which you can use to tag and - categorise bugs - e.g. The Mozilla Project has keywords like crash - and regression.</para> - </listitem> - - <listitem> - <para> - <emphasis>Platform and OS:</emphasis> - These indicate the computing environment where the bug was - found.</para> - </listitem> - - <listitem> - <para> - <emphasis>Version:</emphasis> - The "Version" field is usually used for versions of a product which - have been released, and is set to indicate which versions of a - Component have the particular problem the bug report is - about.</para> - </listitem> - - <listitem> - <para> - <emphasis>Priority:</emphasis> - The bug assignee uses this field to prioritize his or her bugs. - It's a good idea not to change this on other people's bugs.</para> - </listitem> - - <listitem> - <para> - <emphasis>Severity:</emphasis> - This indicates how severe the problem is - from blocker - ("application unusable") to trivial ("minor cosmetic issue"). You - can also use this field to indicate whether a bug is an enhancement - request.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Target:</emphasis> - (a.k.a. Target Milestone) A future version by which the bug is to - be fixed. e.g. The Bugzilla Project's milestones for future - Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not - restricted to numbers, thought - you can use any text strings, such - as dates.</para> - </listitem> - - <listitem> - <para> - <emphasis>Reporter:</emphasis> - The person who filed the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>CC list:</emphasis> - A list of people who get mail when the bug changes.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Time Tracking:</emphasis> - This form can be used for time tracking. - To use this feature, you have to be blessed group membership - specified by the <quote>timetrackinggroup</quote> parameter. - <variablelist> - <varlistentry> - <term>Orig. Est.:</term> - <listitem> - <para> - This field shows the original estimated time. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Current Est.:</term> - <listitem> - <para> - This field shows the current estimated time. - This number is calculated from <quote>Hours Worked</quote> - and <quote>Hours Left</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Hours Worked:</term> - <listitem> - <para> - This field shows the number of hours worked. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Hours Left:</term> - <listitem> - <para> - This field shows the <quote>Current Est.</quote> - - <quote>Hours Worked</quote>. - This value + <quote>Hours Worked</quote> will become the - new Current Est. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>%Complete:</term> - <listitem> - <para> - This field shows what percentage of the task is complete. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Gain:</term> - <listitem> - <para> - This field shows the number of hours that the bug is ahead of the - <quote>Orig. Est.</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Deadline:</term> - <listitem> - <para> - This field shows the deadline for this bug. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Attachments:</emphasis> - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. - </para> - </listitem> - - <listitem> - <para> - <emphasis>*Dependencies:</emphasis> - If this bug cannot be fixed unless other bugs are fixed (depends - on), or this bug stops other bugs being fixed (blocks), their - numbers are recorded here.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Votes:</emphasis> - Whether this bug has any votes.</para> - </listitem> - - <listitem> - <para> - <emphasis>Additional Comments:</emphasis> - You can add your two cents to the bug discussion here, if you have - something worthwhile to say.</para> - </listitem> - </orderedlist> - </section> - - <section id="lifecycle"> - <title>Life Cycle of a Bug</title> - - <para> - The life cycle of a bug, also known as workflow, is customizable to match - the needs of your organization, see <xref linkend="bug_status_workflow"/>. - <xref linkend="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 - <ulink url="../images/bzLifecycle.xml">diagram file</ulink> - is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink> - native XML format. - </para> - - <figure id="lifecycle-image"> - <title>Lifecycle of a Bugzilla Bug</title> - <mediaobject> - <imageobject> - <imagedata fileref="../images/bzLifecycle.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - - <section id="query"> - <title>Searching for Bugs</title> - - <para>The Bugzilla Search page is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - <ulink url="&landfillbase;query.cgi"/>.</para> - - <para>The Search page has controls for selecting different possible - values for all of the fields in a bug, as described above. For some - fields, multiple values can be selected. In those cases, Bugzilla - returns bugs where the content of the field matches any one of the selected - values. If none is selected, then the field can take any value.</para> - - <para> - After a search is run, you can save it as a Saved Search, which - will appear in the page footer. If you are in the group defined - by the "querysharegroup" parameter, you may share your queries - with other users, see <xref linkend="savedsearches"/> for more details. - </para> - - <section id="boolean"> - <title>Boolean Charts</title> - <para> - Highly advanced querying is done using Boolean Charts. - </para> - <para> - The boolean charts further restrict the set of results - returned by a query. It is possible to search for bugs - based on elaborate combinations of criteria. - </para> - <para> - The simplest boolean searches have only one term. These searches - permit the selected left <emphasis>field</emphasis> - to be compared using a - selectable <emphasis>operator</emphasis> to a - specified <emphasis>value.</emphasis> - Using the "And," "Or," and "Add Another Boolean Chart" buttons, - additional terms can be included in the query, further - altering the list of bugs returned by the query. - </para> - <para> - There are three fields in each row of a boolean search. - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>Field:</emphasis> - the items being searched - </para> - </listitem> - <listitem> - <para> - <emphasis>Operator:</emphasis> - the comparison operator - </para> - </listitem> - <listitem> - <para> - <emphasis>Value:</emphasis> - the value to which the field is being compared - </para> - </listitem> - </itemizedlist> - <section id="pronouns"> - <title>Pronoun Substitution</title> - <para> - Sometimes, a query needs to compare a user-related field - (such as ReportedBy) with a role-specific user (such as the - user running the query or the user to whom each bug is assigned). - When the operator is either "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. - </para> - <para> - 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%". - </para> - </section> - <section id="negation"> - <title>Negation</title> - <para> - At first glance, negation seems redundant. Rather than - searching for - <blockquote> - <para> - NOT("summary" "contains the string" "foo"), - </para> - </blockquote> - one could search for - <blockquote> - <para> - ("summary" "does not contain the string" "foo"). - </para> - </blockquote> - However, the search - <blockquote> - <para> - ("CC" "does not contain the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where anyone on the CC list did not contain - "@mozilla.org" while - <blockquote> - <para> - NOT("CC" "contains the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where there was nobody on the CC list who - did contain the string. Similarly, the use of negation also permits - complex expressions to be built using terms OR'd together and then - negated. Negation permits queries such as - <blockquote> - <para> - NOT(("product" "is equal to" "update") OR - ("component" "is equal to" "Documentation")) - </para> - </blockquote> - to find bugs that are neither - in the update product or in the documentation component or - <blockquote> - <para> - NOT(("commenter" "is equal to" "%assignee%") OR - ("component" "is equal to" "Documentation")) - </para> - </blockquote> - to find non-documentation - bugs on which the assignee has never commented. - </para> - </section> - <section id="multiplecharts"> - <title>Multiple Charts</title> - <para> - The terms within a single row of a boolean chart are all - constraints on a single piece of data. If you are looking for - a bug that has two different people cc'd on it, then you need - to use two boolean charts. A search for - <blockquote> - <para> - ("cc" "contains the string" "foo@") AND - ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - would return only bugs with "foo@mozilla.org" on the cc list. - If you wanted bugs where there is someone on the cc list - containing "foo@" and someone else containing "@mozilla.org", - then you would need two boolean charts. - <blockquote> - <para> - First chart: ("cc" "contains the string" "foo@") - </para> - <para> - Second chart: ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - The bugs listed will be only the bugs where ALL the charts are true. - </para> - </section> - </section> - - <section id="quicksearch"> - <title>Quicksearch</title> - - <para> - Quicksearch is a single-text-box query tool which uses - metacharacters to indicate what is to be searched. For example, typing - "<literal>foo|bar</literal>" - into Quicksearch would search for "foo" or "bar" in the - summary and status whiteboard of a bug; adding - "<literal>:BazProduct</literal>" would - search only in that product. - You can use it to find a bug by its number or its alias, too. - </para> - - <para> - You'll find the Quicksearch box in Bugzilla's footer area. - On Bugzilla's front page, there is an additional - <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink> - link which details how to use it. - </para> - </section> - <section id="casesensitivity"> - <title>Case Sensitivity in Searches</title> - <para> - Bugzilla queries are case-insensitive and accent-insensitive, when - used with either MySQL or Oracle databases. When using Bugzilla with - PostgreSQL, however, some queries are case-sensitive. This is due to - the way PostgreSQL handles case and accent sensitivity. - </para> - </section> - <section id="list"> - <title>Bug Lists</title> - - <para>If you run a search, a list of matching bugs will be returned. - </para> - - <para>The format of the list is configurable. For example, it can be - sorted by clicking the column headings. Other useful features can be - accessed using the links at the bottom of the list: - <variablelist> - <varlistentry> - <term>Long Format:</term> - <listitem> - <para> - this gives you a large page with a non-editable summary of the fields - of each bug. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XML:</term> - <listitem> - <para> - get the buglist in the XML format. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>CSV:</term> - <listitem> - <para> - get the buglist as comma-separated values, for import into e.g. - a spreadsheet. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Feed:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>iCalendar:</term> - <listitem> - <para> - Get the buglist as an iCalendar file. Each bug is represented as a - to-do item in the imported calendar. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Change Columns:</term> - <listitem> - <para> - change the bug attributes which appear in the list. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Change several bugs at once:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Send mail to bug assignees:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Edit Search:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Remember Search As:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </section> - - <section id="individual-buglists"> - <title>Adding/removing tags to/from bugs</title> - <para> - You can add and remove tags from individual bugs, which let you find and - manage 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. - </para> - - <para> - This feature is useful when you want to keep track of several bugs, but - for different reasons. Instead of adding yourself to the CC list of all - these bugs and mixing all these reasons, you can now store these bugs in - separate lists, e.g. <quote>Keep in mind</quote>, <quote>Interesting bugs</quote>, - or <quote>Triage</quote>. One big advantage of this way to manage bugs - is that you can easily add or remove tags from bugs one by one. - </para> - </section> - </section> - - <section id="bugreports"> - <title>Filing Bugs</title> - - <section id="fillingbugs"> - <title>Reporting a New Bug</title> - - <para>Years of bug writing experience has been distilled for your - reading pleasure into the - <ulink - url="&landfillbase;page.cgi?id=bug-writing.html"> - Bug Writing Guidelines</ulink>. - While some of the advice is Mozilla-specific, the basic principles of - reporting Reproducible, Specific bugs, isolating the Product you are - using, the Version of the Product, the Component which failed, the - Hardware Platform, and Operating System you were using at the time of - the failure go a long way toward ensuring accurate, responsible fixes - for the bug that bit you.</para> - - <para>The procedure for filing a bug is as follows:</para> - - <orderedlist> - <listitem> - <para> - Click the <quote>New</quote> link available in the footer - of pages, or the <quote>Enter a new bug report</quote> link - displayed on the home page of the Bugzilla installation. - </para> - - <note> - <para> - If you want to file a test bug to see how Bugzilla works, - you can do it on one of our test installations on - <ulink url="&landfillbase;">Landfill</ulink>. - </para> - </note> - </listitem> - - <listitem> - <para> - You first have to select the product in which you found a bug. - </para> - </listitem> - - <listitem> - <para> - You now see a form where you can specify the component (part of - the product which is affected by the bug you discovered; if you have - no idea, just select <quote>General</quote> if such a component exists), - the version of the program you were using, the Operating System and - platform your program is running on and the severity of the bug (if the - bug you found crashes the program, it's probably a major or a critical - bug; if it's a typo somewhere, that's something pretty minor; if it's - something you would like to see implemented, then that's an enhancement). - </para> - </listitem> - - <listitem> - <para> - You now have to give a short but descriptive summary of the bug you found. - <quote>My program is crashing all the time</quote> is a very poor summary - and doesn't help developers at all. Try something more meaningful or - your bug will probably be ignored due to a lack of precision. - The next step is to give a very detailed list of steps to reproduce - the problem you encountered. Try to limit these steps to a minimum set - required to reproduce the problem. This will make the life of - developers easier, and the probability that they consider your bug in - a reasonable timeframe will be much higher. - </para> - - <note> - <para> - Try to make sure that everything in the summary is also in the first - comment. Summaries are often updated and this will ensure your original - information is easily accessible. - </para> - </note> - </listitem> - - <listitem> - <para> - As you file the bug, you can also attach a document (testcase, patch, - or screenshot of the problem). - </para> - </listitem> - - <listitem> - <para> - Depending on the Bugzilla installation you are using and the product in - which you are filing the bug, you can also request developers to consider - your bug in different ways (such as requesting review for the patch you - just attached, requesting your bug to block the next release of the - product, and many other product specific requests). - </para> - </listitem> - - <listitem> - <para> - Now is a good time to read your bug report again. Remove all misspellings, - otherwise your bug may not be found by developers running queries for some - specific words, and so your bug would not get any attention. - Also make sure you didn't forget any important information developers - should know in order to reproduce the problem, and make sure your - description of the problem is explicit and clear enough. - When you think your bug report is ready to go, the last step is to - click the <quote>Commit</quote> button to add your report into the database. - </para> - </listitem> - </orderedlist> - - <para> - You do not need to put "any" or similar strings in the URL field. - If there is no specific URL associated with the bug, leave this - field blank. - </para> - - <para>If you feel a bug you filed was incorrectly marked as a - DUPLICATE of another, please question it in your bug, not - the bug it was duped to. Feel free to CC the person who duped it - if they are not already CCed. - </para> - </section> - - <section id="cloningbugs"> - <title>Clone an Existing Bug</title> - - <para> - Starting with version 2.20, Bugzilla has a feature that allows you - to clone an existing bug. The newly created bug will inherit - most settings from the old bug. This allows you to track more - easily similar concerns in a new bug. To use this, go to the bug - that you want to clone, then click the <quote>Clone This Bug</quote> - link on the bug page. This will take you to the <quote>Enter Bug</quote> - page that is filled with the values that the old bug has. - You can change those values and/or texts if needed. - </para> - </section> - - </section> - - <section id="attachments"> - <title>Attachments</title> - - <para> - You should use attachments, rather than comments, for large chunks of ASCII - data, such as trace, debugging output files, or log files. That way, it - doesn't bloat the bug for everyone who wants to read it, and cause people to - receive fat, useless mails. - </para> - - <para>You should make sure to trim screenshots. There's no need to show the - whole screen if you are pointing out a single-pixel problem. - </para> - - <para>Bugzilla stores and uses a Content-Type for each attachment - (e.g. text/html). To download an attachment as a different - Content-Type (e.g. application/xhtml+xml), you can override this - using a 'content_type' parameter on the URL, e.g. - <filename>&content_type=text/plain</filename>. - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <section id="patchviewer"> - <title>Patch Viewer</title> - - <para>Viewing and reviewing patches in Bugzilla is often difficult due to - lack of context, improper format and the inherent readability issues that - raw patches present. Patch Viewer is an enhancement to Bugzilla designed - to fix that by offering increased context, linking to sections, and - integrating with Bonsai, LXR and CVS.</para> - - <para>Patch viewer allows you to:</para> - - <simplelist> - <member>View patches in color, with side-by-side view rather than trying - to interpret the contents of the patch.</member> - <member>See the difference between two patches.</member> - <member>Get more context in a patch.</member> - <member>Collapse and expand sections of a patch for easy - reading.</member> - <member>Link to a particular section of a patch for discussion or - review</member> - <member>Go to Bonsai or LXR to see more context, blame, and - cross-references for the part of the patch you are looking at</member> - <member>Create a rawtext unified format diff out of any patch, no - matter what format it came from</member> - </simplelist> - - <section id="patchviewer_view"> - <title>Viewing Patches in Patch Viewer</title> - <para>The main way to view a patch in patch viewer is to click on the - "Diff" link next to a patch in the Attachments list on a bug. You may - also do this within the edit window by clicking the "View Attachment As - Diff" button in the Edit Attachment screen.</para> - </section> - - <section id="patchviewer_diff"> - <title>Seeing the Difference Between Two Patches</title> - <para>To see the difference between two patches, you must first view the - newer patch in Patch Viewer. Then select the older patch from the - dropdown at the top of the page ("Differences between [dropdown] and - this patch") and click the "Diff" button. This will show you what - is new or changed in the newer patch.</para> - </section> - - <section id="patchviewer_context"> - <title>Getting More Context in a Patch</title> - <para>To get more context in a patch, you put a number in the textbox at - the top of Patch Viewer ("Patch / File / [textbox]") and hit enter. - This will give you that many lines of context before and after each - change. Alternatively, you can click on the "File" link there and it - will show each change in the full context of the file. This feature only - works against files that were diffed using "cvs diff".</para> - </section> - - <section id="patchviewer_collapse"> - <title>Collapsing and Expanding Sections of a Patch</title> - <para>To view only a certain set of files in a patch (for example, if a - patch is absolutely huge and you want to only review part of it at a - time), you can click the "(+)" and "(-)" links next to each file (to - expand it or collapse it). If you want to collapse all files or expand - all files, you can click the "Collapse All" and "Expand All" links at the - top of the page.</para> - </section> - - <section id="patchviewer_link"> - <title>Linking to a Section of a Patch</title> - <para>To link to a section of a patch (for example, if you want to be - able to give someone a URL to show them which part you are talking - about) you simply click the "Link Here" link on the section header. The - resulting URL can be copied and used in discussion.</para> - </section> - - <section id="patchviewer_bonsai_lxr"> - <title>Going to Bonsai and LXR</title> - <para>To go to Bonsai to get blame for the lines you are interested in, - you can click the "Lines XX-YY" link on the section header you are - interested in. This works even if the patch is against an old - version of the file, since Bonsai stores all versions of the file.</para> - - <para>To go to LXR, you click on the filename on the file header - (unfortunately, since LXR only does the most recent version, line - numbers are likely to rot).</para> - </section> - - <section id="patchviewer_unified_diff"> - <title>Creating a Unified Diff</title> - <para>If the patch is not in a format that you like, you can turn it - into a unified diff format by clicking the "Raw Unified" link at the top - of the page.</para> - </section> - </section> - </section> - - <section id="hintsandtips"> - <title>Hints and Tips</title> - - <para>This section distills some Bugzilla tips and best practices - that have been developed.</para> - - <section> - <title>Autolinkification</title> - <para>Bugzilla comments are plain text - so typing <U> will - produce less-than, U, greater-than rather than underlined text. - However, Bugzilla will automatically make hyperlinks out of certain - sorts of text in comments. For example, the text - "http://www.bugzilla.org" will be turned into a link: - <ulink url="http://www.bugzilla.org"/>. - Other strings which get linkified in the obvious manner are: - <simplelist> - <member>bug 12345</member> - <member>comment 7</member> - <member>bug 23456, comment 53</member> - <member>attachment 4321</member> - <member>mailto:george@example.com</member> - <member>george@example.com</member> - <member>ftp://ftp.mozilla.org</member> - <member>Most other sorts of URL</member> - </simplelist> - </para> - - <para>A corollary here is that if you type a bug number in a comment, - you should put the word "bug" before it, so it gets autolinkified - for the convenience of others. - </para> - </section> - - <section id="commenting"> - <title>Comments</title> - - <para>If you are changing the fields on a bug, only comment if - either you have something pertinent to say, or Bugzilla requires it. - Otherwise, you may spam people unnecessarily with bug mail. - To take an example: a user can set up their account to filter out messages - where someone just adds themselves to the CC field of a bug - (which happens a lot.) If you come along, add yourself to the CC field, - and add a comment saying "Adding self to CC", then that person - gets a pointless piece of mail they would otherwise have avoided. - </para> - - <para> - Don't use sigs in comments. Signing your name ("Bill") is acceptable, - if you do it out of habit, but full mail/news-style - four line ASCII art creations are not. - </para> - </section> - - <section id="comment-wrapping"> - <title>Server-Side Comment Wrapping</title> - <para> - Bugzilla stores comments unwrapped and wraps them at display time. This - ensures proper wrapping in all browsers. Lines beginning with the ">" - character are assumed to be quotes, and are not wrapped. - </para> - </section> - - <section id="dependencytree"> - <title>Dependency Tree</title> - - <para> - On the <quote>Dependency tree</quote> page linked from each bug - page, you can see the dependency relationship from the bug as a - tree structure. - </para> - - <para> - You can change how much depth to show, and you can hide resolved bugs - from this page. You can also collaps/expand dependencies for - each bug on the tree view, using the [-]/[+] buttons that appear - before its summary. This option is not available for terminal - bugs in the tree (that don't have further dependencies). - </para> - </section> - </section> - - <section id="timetracking"> - <title>Time Tracking Information</title> - - <para> - Users who belong to the group specified by the <quote>timetrackinggroup</quote> - parameter have access to time-related fields. Developers can see - deadlines and estimated times to fix bugs, and can provide time spent - on these bugs. - </para> - - <para> - At any time, a summary of the time spent by developers on bugs is - accessible either from bug lists when clicking the <quote>Time Summary</quote> - button or from individual bugs when clicking the <quote>Summarize time</quote> - link in the time tracking table. The <filename>summarize_time.cgi</filename> - page lets you view this information either per developer or per bug, - and can be split on a month basis to have greater details on how time - is spent by developers. - </para> - - <para> - As soon as a bug is marked as RESOLVED, the remaining time expected - to fix the bug is set to zero. This lets QA people set it again for - their own usage, and it will be set to zero again when the bug will - be marked as CLOSED. - </para> - </section> - - <section id="userpreferences"> - <title>User Preferences</title> - - <para> - Once logged in, you can customize various aspects of - Bugzilla via the "Preferences" link in the page footer. - The preferences are split into five tabs:</para> - - <section id="generalpreferences" xreflabel="General Preferences"> - <title>General Preferences</title> - - <para> - This tab allows you to change several default settings of Bugzilla. - </para> - - <itemizedlist spacing="compact"> - <listitem> - <para> - Bugzilla's general appearance (skin) - select which skin to use. - Bugzilla supports adding custom skins. - </para> - </listitem> - <listitem> - <para> - Quote the associated comment when you click on its reply link - sets - the behavior of the comment "Reply" link. Options include quoting the - full comment, just reference the comment number, or turn the link off. - </para> - </listitem> - <listitem> - <para> - Language used in email - select which language email will be sent in, - from the list of available languages. - </para> - </listitem> - <listitem> - <para> - After changing a bug - This controls what page is displayed after - changes to a bug are submitted. The options include to show the bug - just modified, to show the next bug in your list, or to do nothing. - </para> - </listitem> - <listitem> - <para> - Zoom textareas large when in use (requires JavaScript) - enable or - disable the automatic expanding of text areas when text is being - entered into them. - </para> - </listitem> - <listitem> - <para> - Field separator character for CSV files - - Select between a comma and semi-colon for exported CSV bug lists. - </para> - </listitem> - <listitem> - <para> - Automatically add me to the CC list of bugs I change - set default - behavior of CC list. Options include "Always", "Never", and "Only - if I have no role on them". - </para> - </listitem> - <listitem> - <para> - When viewing a bug, show comments in this order - - controls the order of comments. Options include "Oldest - to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the - bug description at the top". - </para> - </listitem> - <listitem> - <para> - Show a quip at the top of each bug list - controls - whether a quip will be shown on the Bug list page. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="emailpreferences"> - <title>Email Preferences</title> - - <para> - This tab allows you to enable or disable email notification on - specific events. - </para> - - <para> - In general, users have almost complete control over how much (or - how little) email Bugzilla sends them. If you want to receive the - maximum amount of email possible, click the <quote>Enable All - Mail</quote> button. If you don't want to receive any email from - Bugzilla at all, click the <quote>Disable All Mail</quote> button. - </para> - - <note> - <para> - A Bugzilla administrator can stop a user from receiving - bugmail by clicking the <quote>Bugmail Disabled</quote> checkbox - when editing the user account. This is a drastic step - best taken only for disabled accounts, as it overrides - the user's individual mail preferences. - </para> - </note> - - <para> - There are two global options -- <quote>Email me when someone - asks me to set a flag</quote> and <quote>Email me when someone - sets a flag I asked for</quote>. These define how you want to - receive bugmail with regards to flags. Their use is quite - straightforward; enable the checkboxes if you want Bugzilla to - send you mail under either of the above conditions. - </para> - - <para> - If you'd like to set your bugmail to something besides - 'Completely ON' and 'Completely OFF', the - <quote>Field/recipient specific options</quote> table - allows you to do just that. The rows of the table - define events that can happen to a bug -- things like - attachments being added, new comments being made, the - priority changing, etc. The columns in the table define - your relationship with the bug: - </para> - - <itemizedlist spacing="compact"> - <listitem> - <para> - Reporter - Where you are the person who initially - reported the bug. Your name/account appears in the - <quote>Reporter:</quote> field. - </para> - </listitem> - <listitem> - <para> - Assignee - Where you are the person who has been - designated as the one responsible for the bug. Your - name/account appears in the <quote>Assigned To:</quote> - field of the bug. - </para> - </listitem> - <listitem> - <para> - QA Contact - You are one of the designated - QA Contacts for the bug. Your account appears in the - <quote>QA Contact:</quote> text-box of the bug. - </para> - </listitem> - <listitem> - <para> - CC - You are on the list CC List for the bug. - Your account appears in the <quote>CC:</quote> text box - of the bug. - </para> - </listitem> - <listitem> - <para> - Voter - You have placed one or more votes for the bug. - Your account appears only if someone clicks on the - <quote>Show votes for this bug</quote> link on the bug. - </para> - </listitem> - </itemizedlist> - - <note> - <para> - Some columns may not be visible for your installation, depending - on your site's configuration. - </para> - </note> - - <para> - To fine-tune your bugmail, decide the events for which you want - to receive bugmail; then decide if you want to receive it all - the time (enable the checkbox for every column), or only when - you have a certain relationship with a bug (enable the checkbox - only for those columns). For example: if you didn't want to - receive mail when someone added themselves to the CC list, you - could uncheck all the boxes in the <quote>CC Field Changes</quote> - line. As another example, if you never wanted to receive email - on bugs you reported unless the bug was resolved, you would - un-check all boxes in the <quote>Reporter</quote> column - except for the one on the <quote>The bug is resolved or - verified</quote> row. - </para> - - <note> - <para> - Bugzilla adds the <quote>X-Bugzilla-Reason</quote> header to - all bugmail it sends, describing the recipient's relationship - (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug. - This header can be used to do further client-side filtering. - </para> - </note> - - <para> - Bugzilla has a feature called <quote>Users Watching</quote>. - When you enter one or more comma-delineated user accounts (usually email - addresses) into the text entry box, you will receive a copy of all the - bugmail those users are sent (security settings permitting). - This powerful functionality enables seamless transitions as developers - change projects or users go on holiday. - </para> - - <note> - <para> - The ability to watch other users may not be available in all - Bugzilla installations. If you don't see this feature, and feel - that you need it, speak to your administrator. - </para> - </note> - - <para> - Each user listed in the <quote>Users watching you</quote> field - has you listed in their <quote>Users to watch</quote> list - and can get bugmail according to your relationship to the bug and - their <quote>Field/recipient specific options</quote> setting. - </para> - - </section> - - <section id="savedsearches" xreflabel="Saved Searches"> - <title>Saved Searches</title> - <para> - On this tab you can view and run any Saved Searches that you have - created, and also any Saved Searches that other members of the group - defined in the "querysharegroup" parameter have shared. - Saved Searches can be added to the page footer from this screen. - If somebody is sharing a Search with a group she or he is allowed to - <link linkend="groups">assign users to</link>, the sharer may opt to have - the Search show up in the footer of the group's direct members by default. - </para> - </section> - - <section id="accountpreferences" xreflabel="Name and Password"> - <title>Name and Password</title> - - <para>On this tab, you can change your basic account information, - including your password, email address and real name. For security - reasons, in order to change anything on this page you must type your - <emphasis>current</emphasis> password into the <quote>Password</quote> - field at the top of the page. - If you attempt to change your email address, a confirmation - email is sent to both the old and new addresses, with a link to use to - confirm the change. This helps to prevent account hijacking.</para> - </section> - - <section id="permissionsettings"> - <title>Permissions</title> - - <para> - This is a purely informative page which outlines your current - permissions on this installation of Bugzilla. - </para> - - <para> - A complete list of permissions is below. Only users with - <emphasis>editusers</emphasis> privileges can change the permissions - of other users. - </para> - - <variablelist> - <varlistentry> - <term> - admin - </term> - <listitem> - <para> - Indicates user is an Administrator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhineatothers - </term> - <listitem> - <para> - Indicates user can configure whine reports for other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhines - </term> - <listitem> - <para> - Indicates user can configure whine reports for self. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_quip_moderators - </term> - <listitem> - <para> - Indicates user can moderate quips. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudoers - </term> - <listitem> - <para> - Indicates user can perform actions as other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudo_protect - </term> - <listitem> - <para> - Indicates user cannot be impersonated by other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - canconfirm - </term> - <listitem> - <para> - Indicates user can confirm a bug or mark it a duplicate. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - creategroups - </term> - <listitem> - <para> - Indicates user can create and destroy groups. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editbugs - </term> - <listitem> - <para> - Indicates user can edit all bug fields. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editclassifications - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit classifications. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editcomponents - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit components. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editkeywords - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit keywords. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editusers - </term> - <listitem> - <para> - Indicates user can edit or disable users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - tweakparams - </term> - <listitem> - <para> - Indicates user can change Parameters. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <note> - <para> - For more information on how permissions work in Bugzilla (i.e. who can - change what), see <xref linkend="cust-change-permissions"/>. - </para> - </note> - - </section> - </section> - - - <section id="reporting"> - <title>Reports and Charts</title> - - <para>As well as the standard buglist, Bugzilla has two more ways of - viewing sets of bugs. These are the reports (which give different - views of the current state of the database) and charts (which plot - the changes in particular sets of bugs over time.)</para> - - <section id="reports"> - <title>Reports</title> - - <para> - A report is a view of the current state of the bug database. - </para> - - <para> - You can run either an HTML-table-based report, or a graphical - line/pie/bar-chart-based one. The two have different pages to - define them, but are close cousins - once you've defined and - viewed a report, you can switch between any of the different - views of the data at will. - </para> - - <para> - Both report types are based on the idea of defining a set of bugs - using the standard search interface, and then choosing some - aspect of that set to plot on the horizontal and/or vertical axes. - You can also get a form of 3-dimensional report by choosing to have - multiple images or tables. - </para> - - <para> - So, for example, you could use the search form to choose "all - bugs in the WorldControl product", and then plot their severity - against their component to see which component had had the largest - number of bad bugs reported against it. - </para> - - <para> - Once you've defined your parameters and hit "Generate Report", - you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie - is only available if you didn't define a vertical axis, as pie - charts don't have one.) The other controls are fairly self-explanatory; - you can change the size of the image if you find text is overwriting - other text, or the bars are too thin to see. - </para> - - </section> - - <section id="charts"> - <title>Charts</title> - - <para> - A chart is a view of the state of the bug database over time. - </para> - - <para> - Bugzilla currently has two charting systems - Old Charts and New - Charts. Old Charts have been part of Bugzilla for a long time; they - chart each status and resolution for each product, and that's all. - They are deprecated, and going away soon - we won't say any more - about them. - New Charts are the future - they allow you to chart anything you - can define as a search. - </para> - - <note> - <para> - Both charting forms require the administrator to set up the - data-gathering script. If you can't see any charts, ask them whether - they have done so. - </para> - </note> - - <para> - An individual line on a chart is called a data set. - All data sets are organised into categories and subcategories. The - data sets that Bugzilla defines automatically use the Product name - as a Category and Component names as Subcategories, but there is no - need for you to follow that naming scheme with your own charts if - you don't want to. - </para> - - <para> - Data sets may be public or private. Everyone sees public data sets in - the list, but only their creator sees private data sets. Only - administrators can make data sets public. - No two data sets, even two private ones, can have the same set of - category, subcategory and name. So if you are creating private data - sets, one idea is to have the Category be your username. - </para> - - <section> - <title>Creating Charts</title> - - <para> - You create a chart by selecting a number of data sets from the - list, and pressing Add To List for each. In the List Of Data Sets - To Plot, you can define the label that data set will have in the - chart's legend, and also ask Bugzilla to Sum a number of data sets - (e.g. you could Sum data sets representing RESOLVED, VERIFIED and - CLOSED in a particular product to get a data set representing all - the resolved bugs in that product.) - </para> - - <para> - If you've erroneously added a data set to the list, select it - using the checkbox and click Remove. Once you add more than one - data set, a "Grand Total" line - automatically appears at the bottom of the list. If you don't want - this, simply remove it as you would remove any other line. - </para> - - <para> - You may also choose to plot only over a certain date range, and - to cumulate the results - that is, to plot each one using the - previous one as a baseline, so the top line gives a sum of all - the data sets. It's easier to try than to explain :-) - </para> - - <para> - Once a data set is in the list, one can also perform certain - actions on it. For example, one can edit the - data set's parameters (name, frequency etc.) if it's one you - created or if you are an administrator. - </para> - - <para> - Once you are happy, click Chart This List to see the chart. - </para> - - </section> - - <section id="charts-new-series"> - <title>Creating New Data Sets</title> - - <para> - You may also create new data sets of your own. To do this, - click the "create a new data set" link on the Create Chart page. - This takes you to a search-like interface where you can define - the search that Bugzilla will plot. At the bottom of the page, - you choose the category, sub-category and name of your new - data set. - </para> - - <para> - If you have sufficient permissions, you can make the data set public, - and reduce the frequency of data collection to less than the default - seven days. - </para> - </section> - - </section> - - </section> - - <section id="flags"> - <title>Flags</title> - - <para> - A flag is a kind of status that can be set on bugs or attachments - to indicate that the bugs/attachments are in a certain state. - Each installation can define its own set of flags that can be set - on bugs or attachments. - </para> - - <para> - If your installation has defined a flag, you can set or unset that flag, - and if your administrator has enabled requesting of flags, you can submit - a request for another user to set the flag. - </para> - - <para> - To set a flag, select either "+" or "-" from the drop-down menu next to - the name of the flag in the "Flags" list. The meaning of these values are - flag-specific and thus cannot be described in this documentation, - but by way of example, setting a flag named "review" to "+" may indicate - that the bug/attachment has passed review, while setting it to "-" - may indicate that the bug/attachment has failed review. - </para> - - <para> - To unset a flag, click its drop-down menu and select the blank value. - Note that marking an attachment as obsolete automatically cancels all - pending requests for the attachment. - </para> - - <para> - If your administrator has enabled requests for a flag, request a flag - by selecting "?" from the drop-down menu and then entering the username - of the user you want to set the flag in the text field next to the menu. - </para> - - <para> - A set flag appears in bug reports and on "edit attachment" pages with the - abbreviated username of the user who set the flag prepended to the - flag name. For example, if Jack sets a "review" flag to "+", it appears - as Jack: review [ + ] - </para> - - <para> - A requested flag appears with the user who requested the flag prepended - to the flag name and the user who has been requested to set the flag - appended to the flag name within parentheses. For example, if Jack - asks Jill for review, it appears as Jack: review [ ? ] (Jill). - </para> - - <para> - You can browse through open requests made of you and by you by selecting - 'My Requests' from the footer. You can also look at open requests limited - by other requesters, requestees, products, components, and flag names from - this page. Note that you can use '-' for requestee to specify flags with - 'no requestee' set. - </para> - </section> - - <section id="whining"> - <title>Whining</title> - - <para> - Whining is a feature in Bugzilla that can regularly annoy users at - specified times. Using this feature, users can execute saved searches - at specific times (i.e. the 15th of the month at midnight) or at - regular intervals (i.e. every 15 minutes on Sundays). The results of the - searches are sent to the user, either as a single email or as one email - per bug, along with some descriptive text. - </para> - - <warning> - <para> - Throughout this section it will be assumed that all users are members - of the bz_canusewhines group, membership in which is required in order - to use the Whining system. You can easily make all users members of - the bz_canusewhines group by setting the User RegExp to ".*" (without - the quotes). - </para> - - <para> - Also worth noting is the bz_canusewhineatothers group. Members of this - group can create whines for any user or group in Bugzilla using a - extended form of the whining interface. Features only available to - members of the bz_canusewhineatothers group will be noted in the - appropriate places. - </para> - </warning> - - <note> - <para> - For whining to work, a special Perl script must be executed at regular - intervals. More information on this is available in - <xref linkend="installation-whining"/>. - </para> - </note> - - <note> - <para> - This section does not cover the whineatnews.pl script. See - <xref linkend="installation-whining-cron"/> for more information on - The Whining Cron. - </para> - </note> - - <section id="whining-overview"> - <title>The Event</title> - - <para> - The whining system defines an "Event" as one or more queries being - executed at regular intervals, with the results of said queries (if - there are any) being emailed to the user. Events are created by - clicking on the "Add new event" button. - </para> - - <para> - Once a new event is created, the first thing to set is the "Email - subject line". The contents of this field will be used in the subject - line of every email generated by this event. In addition to setting a - subject, space is provided to enter some descriptive text that will be - included at the top of each message (to help you in understanding why - you received the email in the first place). - </para> - - <para> - The next step is to specify when the Event is to be run (the Schedule) - and what searches are to be performed (the Searches). - </para> - - </section> - - <section id="whining-schedule"> - <title>Whining Schedule</title> - - <para> - Each whining event is associated with zero or more schedules. A - schedule is used to specify when the query (specified below) is to be - run. A new event starts out with no schedules (which means it will - never run, as it is not scheduled to run). To add a schedule, press - the "Add a new schedule" button. - </para> - - <para> - Each schedule includes an interval, which you use to tell Bugzilla - when the event should be run. An event can be run on certain days of - the week, certain days of the month, during weekdays (defined as - Monday through Friday), or every day. - </para> - - <warning> - <para> - Be careful if you set your event to run on the 29th, 30th, or 31st of - the month, as your event may not run exactly when expected. If you - want your event to run on the last day of the month, select "Last day - of the month" as the interval. - </para> - </warning> - - <para> - Once you have specified the day(s) on which the event is to be run, you - should now specify the time at which the event is to be run. You can - have the event run at a certain hour on the specified day(s), or - every hour, half-hour, or quarter-hour on the specified day(s). - </para> - - <para> - If a single schedule does not execute an event as many times as you - would want, you can create another schedule for the same event. For - example, if you want to run an event on days whose numbers are - divisible by seven, you would need to add four schedules to the event, - setting the schedules to run on the 7th, 14th, 21st, and 28th (one day - per schedule) at whatever time (or times) you choose. - </para> - - <note> - <para> - If you are a member of the bz_canusewhineatothers group, then you - will be presented with another option: "Mail to". Using this you - can control who will receive the emails generated by this event. You - can choose to send the emails to a single user (identified by email - address) or a single group (identified by group name). To send to - multiple users or groups, create a new schedule for each additional - user/group. - </para> - </note> - </section> - - <section id="whining-query"> - <title>Whining Searches</title> - - <para> - Each whining event is associated with zero or more searches. A search - is any saved search to be run as part of the specified schedule (see - above). You start out without any searches associated with the event - (which means that the event will not run, as there will never be any - results to return). To add a search, press the "Include search" button. - </para> - - <para> - The first field to examine in your newly added search is the Sort field. - Searches are run, and results included, in the order specified by the - Sort field. Searches with smaller Sort values will run before searches - with bigger Sort values. - </para> - - <para> - The next field to examine is the Search field. This is where you - choose the actual search that is to be run. Instead of defining search - parameters here, you are asked to choose from the list of saved - searches (the same list that appears at the bottom of every Bugzilla - page). You are only allowed to choose from searches that you have - saved yourself (the default saved search, "My Bugs", is not a valid - choice). If you do not have any saved searches, you can take this - opportunity to create one (see <xref linkend="list"/>). - </para> - - <note> - <para> - When running queries, the whining system acts as if you are the user - executing the query. This means that the whining system will ignore - bugs that match your query, but that you cannot access. - </para> - </note> - - <para> - Once you have chosen the saved search to be executed, give the query a - descriptive title. This title will appear in the email, above the - results of the query. If you choose "One message per bug", the query - title will appear at the top of each email that contains a bug matching - your query. - </para> - - <para> - Finally, decide if the results of the query should be sent in a single - email, or if each bug should appear in its own email. - </para> - - <warning> - <para> - Think carefully before checking the "One message per bug" box. If - you create a query that matches thousands of bugs, you will receive - thousands of emails! - </para> - </warning> - </section> - - <section> - <title>Saving Your Changes</title> - - <para> - Once you have defined at least one schedule, and created at least one - query, go ahead and "Update/Commit". This will save your Event and make - it available for immediate execution. - </para> - - <note> - <para> - If you ever feel like deleting your event, you may do so using the - "Remove Event" button in the upper-right corner of each Event. You - can also modify an existing event, so long as you "Update/Commit" - after completing your modifications. - </para> - </note> - </section> - - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> |