diff options
| author | barnboy%trilobyte.net <> | 2008-04-04 13:45:52 +0200 |
|---|---|---|
| committer | barnboy%trilobyte.net <> | 2008-04-04 13:45:52 +0200 |
| commit | e5b9f4fac1e56c36d72304c313432dc34edd80c9 (patch) | |
| tree | e750545dddb07577ecc5244fb4eacabbf0cb02c4 /docs/en/xml/using.xml | |
| parent | 7016a5a014f8d3c87a4bdf7d1ad8286bc06a9193 (diff) | |
| download | bugzilla-e5b9f4fac1e56c36d72304c313432dc34edd80c9.tar.gz bugzilla-e5b9f4fac1e56c36d72304c313432dc34edd80c9.tar.xz | |
Updated Bugzilla Guide and README to fix bug 76156, bug 76841, and bug 26242.
The README is now gutted, pointers to Guide. Also some new sections added,
old ones fixed, and notes appended to deprecated sections I've not yet had
the heart to remove.
Diffstat (limited to 'docs/en/xml/using.xml')
| -rw-r--r-- | docs/en/xml/using.xml | 2654 |
1 files changed, 787 insertions, 1867 deletions
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index 101a9d131..bc8159835 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -1,1957 +1,877 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<!-- TOC +Chapter: Using Bugzilla + Create an account + Logging in + Setting up preferences + Account Settings + Email Settings + Page Footer + Permissions + Life cycle of a bug + Creating a bug + Checking for duplicates + Overview of all bug fields + Setting bug permissions + The Query Interface + Standard Queries + Email Queries + Boolean Queries + Regexp Queries + The Query Results + Changing Columns + Changing sorting order + Mass changes + Miscellaneous usage hints -<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> +--> +<chapter id="using"> +<title>Using Bugzilla</title> + <epigraph> <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. + What, Why, How, & What's in it for me? </para> - </section> - - <section id="myaccount"> - <title>Create a Bugzilla Account</title> + </epigraph> - <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;"/>. + <section id="whatis"> + <title>What is Bugzilla?</title> + <para> + Bugzilla is one example of a class of programs called "Defect Tracking Systems", + or, more commonly, "Bug-Tracking Systems". Defect Tracking Systems allow individual or + groups of developers to keep track of outstanding bugs in their product effectively. + Bugzilla was originally written by Terry Weissman in a programming language called + "TCL", to replace a crappy + bug-tracking database used internally for Netscape Communications. Terry later ported + Bugzilla to + Perl from TCL, and in Perl it remains to this day. + Most commercial defect-tracking software vendors at the + time charged enormous licensing fees, and Bugzilla quickly became a favorite of the + open-source crowd (with its genesis in the open-source browser project, Mozilla). It + is now the de-facto standard defect-tracking system against which all others are + measured. </para> - - <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. + Bugzilla has matured immensely, and now boasts many advanced features. These include: + <itemizedlist> + <listitem> + <para> + integrated, product-based granular security schema + </para> + </listitem> + <listitem> + <para> + inter-bug dependencies and dependency graphing + </para> + </listitem> + <listitem> + <para> + advanced reporting capabilities + </para> + </listitem> + <listitem> + <para> + a robust, stable RDBMS back-end + </para> + </listitem> + <listitem> + <para> + extensive configurability + </para> + </listitem> + <listitem> + <para> + a very well-understood and well-thought-out natural bug resolution protocol + </para> + </listitem> + <listitem> + <para> + email, XML, and HTTP APIs + </para> + </listitem> + <listitem> + <para> + available integration with automated software configuration management systems, including + Perforce and CVS. + </para> + </listitem> + <listitem> + <para> + too many more features to list + </para> + </listitem> + </itemizedlist> </para> - </section> - - <section id="bug_page"> - <title>Anatomy of a Bug</title> - - <para>The core of Bugzilla is the screen which displays a particular - bug. It's a good place to explain some Bugzilla concepts. - <ulink - url="&landfillbase;show_bug.cgi?id=1"> - Bug 1 on Landfill</ulink> - - is a good example. Note that the labels for most fields are hyperlinks; - clicking them will take you to context-sensitive help on that - particular field. Fields marked * may not be present on every - installation of Bugzilla.</para> - - <orderedlist> - <listitem> - <para> - <emphasis>Product and Component</emphasis>: - Bugs are divided up by Product and Component, with a Product - having one or more Components in it. For example, - bugzilla.mozilla.org's "Bugzilla" Product is composed of several - Components: - <simplelist> - <member> - <emphasis>Administration:</emphasis> - Administration of a Bugzilla installation.</member> - - <member> - <emphasis>Bugzilla-General:</emphasis> - Anything that doesn't fit in the other components, or spans - multiple components.</member> - - <member> - <emphasis>Creating/Changing Bugs:</emphasis> - Creating, changing, and viewing bugs.</member> - - <member> - <emphasis>Documentation:</emphasis> - The Bugzilla documentation, including The Bugzilla Guide.</member> - - <member> - <emphasis>Email:</emphasis> - Anything to do with email sent by Bugzilla.</member> - - <member> - <emphasis>Installation:</emphasis> - The installation process of Bugzilla.</member> - - <member> - <emphasis>Query/Buglist:</emphasis> - Anything to do with searching for bugs and viewing the - buglists.</member> - - <member> - <emphasis>Reporting/Charting:</emphasis> - Getting reports from Bugzilla.</member> - - <member> - <emphasis>User Accounts:</emphasis> - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc.</member> - - <member> - <emphasis>User Interface:</emphasis> - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc.</member> - </simplelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Status and Resolution:</emphasis> - - These define exactly what state the bug is in - from not even - being confirmed as a bug, through to being fixed and the fix - confirmed by Quality Assurance. The different possible values for - Status and Resolution on your installation should be documented in the - context-sensitive help for those items.</para> - </listitem> - - <listitem> - <para> - <emphasis>Assigned To:</emphasis> - The person responsible for fixing the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*QA Contact:</emphasis> - The person responsible for quality assurance on this bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*URL:</emphasis> - A URL associated with the bug, if any.</para> - </listitem> - - <listitem> - <para> - <emphasis>Summary:</emphasis> - A one-sentence summary of the problem.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Status Whiteboard:</emphasis> - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Keywords:</emphasis> - The administrator can define keywords which you can use to tag and - categorise bugs - e.g. The Mozilla Project has keywords like crash - and regression.</para> - </listitem> - - <listitem> - <para> - <emphasis>Platform and OS:</emphasis> - These indicate the computing environment where the bug was - found.</para> - </listitem> - - <listitem> - <para> - <emphasis>Version:</emphasis> - The "Version" field is usually used for versions of a product which - have been released, and is set to indicate which versions of a - Component have the particular problem the bug report is - about.</para> - </listitem> - - <listitem> - <para> - <emphasis>Priority:</emphasis> - The bug assignee uses this field to prioritize his or her bugs. - It's a good idea not to change this on other people's bugs.</para> - </listitem> - - <listitem> - <para> - <emphasis>Severity:</emphasis> - This indicates how severe the problem is - from blocker - ("application unusable") to trivial ("minor cosmetic issue"). You - can also use this field to indicate whether a bug is an enhancement - request.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Target:</emphasis> - (a.k.a. Target Milestone) A future version by which the bug is to - be fixed. e.g. The Bugzilla Project's milestones for future - Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not - restricted to numbers, thought - you can use any text strings, such - as dates.</para> - </listitem> - - <listitem> - <para> - <emphasis>Reporter:</emphasis> - The person who filed the bug.</para> - </listitem> - - <listitem> - <para> - <emphasis>CC list:</emphasis> - A list of people who get mail when the bug changes.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Time Tracking:</emphasis> - This form can be used for time tracking. - To use this feature, you have to be blessed group membership - specified by the <quote>timetrackinggroup</quote> parameter. - <simplelist> - <member> - <emphasis>Orig. Est.:</emphasis> - This field shows the original estimated time.</member> - - <member> - <emphasis>Current Est.:</emphasis> - This field shows the current estimated time. - This number is calculated from <quote>Hours Worked</quote> - and <quote>Hours Left</quote>.</member> - - <member> - <emphasis>Hours Worked:</emphasis> - This field shows the number of hours worked.</member> - - <member> - <emphasis>Hours Left:</emphasis> - This field shows the <quote>Current Est.</quote> - - <quote>Hours Worked</quote>. - This value + <quote>Hours Worked</quote> will become the - new Current Est.</member> - - <member> - <emphasis>%Complete:</emphasis> - This field shows what percentage of the task is complete.</member> - - <member> - <emphasis>Gain:</emphasis> - This field shows the number of hours that the bug is ahead of the - <quote>Orig. Est.</quote>.</member> - - <member> - <emphasis>Deadline:</emphasis> - This field shows the deadline for this bug.</member> - </simplelist> - </para> - </listitem> - - <listitem> - <para> - <emphasis>Attachments:</emphasis> - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. Attachments are - normally stored in the Bugzilla database, unless they are marked as - Big Files, which are stored directly on disk. - </para> - </listitem> - - <listitem> - <para> - <emphasis>*Dependencies:</emphasis> - If this bug cannot be fixed unless other bugs are fixed (depends - on), or this bug stops other bugs being fixed (blocks), their - numbers are recorded here.</para> - </listitem> - - <listitem> - <para> - <emphasis>*Votes:</emphasis> - Whether this bug has any votes.</para> - </listitem> - - <listitem> - <para> - <emphasis>Additional Comments:</emphasis> - You can add your two cents to the bug discussion here, if you have - something worthwhile to say.</para> - </listitem> - </orderedlist> - </section> - - <section id="lifecycle"> - <title>Life Cycle of a Bug</title> - <para> - The life cycle, also known as work flow, of a bug is currently hardcoded - into Bugzilla. <xref linkend="lifecycle-image"/> contains a graphical - representation of this life cycle. If you wish to customize this image for - your site, the <ulink url="../images/bzLifecycle.xml">diagram file</ulink> - is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink> - native XML format. + Despite its current robustness and popularity, however, Bugzilla + faces some near-term challenges, such as reliance on a single database, a lack of + abstraction of the user interface and program logic, verbose email bug + notifications, a powerful but daunting query interface, little reporting configurability, + problems with extremely large queries, some unsupportable bug resolution options, + no internationalization, and dependence on some nonstandard libraries. </para> - - <figure id="lifecycle-image"> - <title>Lifecycle of a Bugzilla Bug</title> - <mediaobject> - <imageobject> - <imagedata fileref="../images/bzLifecycle.png" scale="66" /> - </imageobject> - </mediaobject> - </figure> - </section> - - <section id="query"> - <title>Searching for Bugs</title> - - <para>The Bugzilla Search page is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - <ulink url="&landfillbase;query.cgi"/>.</para> - - <para>The Search page has controls for selecting different possible - values for all of the fields in a bug, as described above. For some - fields, multiple values can be selected. In those cases, Bugzilla - returns bugs where the content of the field matches any one of the selected - values. If none is selected, then the field can take any value.</para> - <para> - After a search is run, you can save it as a Saved Search, which - will appear in the page footer. If you are in the group defined - by the "querysharegroup" parameter, you may share your queries - with other users, see <xref linkend="savedsearches"/> for more details. + Some recent headway has been made on the query front, however. If you are using the latest + version of Bugzilla, you should see a "simple search" form on the default front page of + your Bugzilla install. Type in two or three search terms and you should pull up some + relevant information. This is also available as "queryhelp.cgi". + </para> + <para> + Despite these small problems, Bugzilla is very hard to beat. It is under <emphasis>very</emphasis> + active development to address the current issues, and a long-awaited overhaul in the form + of Bugzilla 3.0 is expected sometime later this year. </para> - - <section id="boolean"> - <title>Boolean Charts</title> - <para> - Highly advanced querying is done using Boolean Charts. - </para> - <para> - The boolean charts further restrict the set of results - returned by a query. It is possible to search for bugs - based on elaborate combinations of criteria. - </para> - <para> - The simplest boolean searches have only one term. These searches - permit the selected left <emphasis>field</emphasis> - to be compared using a - selectable <emphasis>operator</emphasis> to a - specified <emphasis>value.</emphasis> - Using the "And," "Or," and "Add Another Boolean Chart" buttons, - additional terms can be included in the query, further - altering the list of bugs returned by the query. - </para> - <para> - There are three fields in each row of a boolean search. - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>Field:</emphasis> - the items being searched - </para> - </listitem> - <listitem> - <para> - <emphasis>Operator:</emphasis> - the comparison operator - </para> - </listitem> - <listitem> - <para> - <emphasis>Value:</emphasis> - the value to which the field is being compared - </para> - </listitem> - </itemizedlist> - <section id="pronouns"> - <title>Pronoun Substitution</title> - <para> - Sometimes, a query needs to compare a user-related field - (such as ReportedBy) with a role-specific user (such as the - user running the query or the user to whom each bug is assigned). - When the operator is either "equals" or "notequals", the value - can be "%reporter%", "%assignee%", "%qacontact%", or "%user%". - The user pronoun - refers to the user who is executing the query or, in the case - of whining reports, the user who will be the recipient - of the report. The reporter, assignee, and qacontact - pronouns refer to the corresponding fields in the bug. - </para> - <para> - Boolean charts also let you type a group name in any user-related - field if the operator is either "equals", "notequals" or "anyexact". - This will let you query for any member belonging (or not) to the - specified group. The group name must be entered following the - "%group.foo%" syntax, where "foo" is the group name. - So if you are looking for bugs reported by any user being in the - "editbugs" group, then you can type "%group.editbugs%". - </para> - </section> - <section id="negation"> - <title>Negation</title> - <para> - At first glance, negation seems redundant. Rather than - searching for - <blockquote> - <para> - NOT("summary" "contains the string" "foo"), - </para> - </blockquote> - one could search for - <blockquote> - <para> - ("summary" "does not contain the string" "foo"). - </para> - </blockquote> - However, the search - <blockquote> - <para> - ("CC" "does not contain the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where anyone on the CC list did not contain - "@mozilla.org" while - <blockquote> - <para> - NOT("CC" "contains the string" "@mozilla.org") - </para> - </blockquote> - would find every bug where there was nobody on the CC list who - did contain the string. Similarly, the use of negation also permits - complex expressions to be built using terms OR'd together and then - negated. Negation permits queries such as - <blockquote> - <para> - NOT(("product" "equals" "update") OR - ("component" "equals" "Documentation")) - </para> - </blockquote> - to find bugs that are neither - in the update product or in the documentation component or - <blockquote> - <para> - NOT(("commenter" "equals" "%assignee%") OR - ("component" "equals" "Documentation")) - </para> - </blockquote> - to find non-documentation - bugs on which the assignee has never commented. - </para> - </section> - <section id="multiplecharts"> - <title>Multiple Charts</title> - <para> - The terms within a single row of a boolean chart are all - constraints on a single piece of data. If you are looking for - a bug that has two different people cc'd on it, then you need - to use two boolean charts. A search for - <blockquote> - <para> - ("cc" "contains the string" "foo@") AND - ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - would return only bugs with "foo@mozilla.org" on the cc list. - If you wanted bugs where there is someone on the cc list - containing "foo@" and someone else containing "@mozilla.org", - then you would need two boolean charts. - <blockquote> - <para> - First chart: ("cc" "contains the string" "foo@") - </para> - <para> - Second chart: ("cc" "contains the string" "@mozilla.org") - </para> - </blockquote> - The bugs listed will be only the bugs where ALL the charts are true. - </para> - </section> - </section> - - <section id="quicksearch"> - <title>Quicksearch</title> - - <para> - Quicksearch is a single-text-box query tool which uses - metacharacters to indicate what is to be searched. For example, typing - "<literal>foo|bar</literal>" - into Quicksearch would search for "foo" or "bar" in the - summary and status whiteboard of a bug; adding - "<literal>:BazProduct</literal>" would - search only in that product. - You can use it to find a bug by its number or its alias, too. - </para> - - <para> - You'll find the Quicksearch box in Bugzilla's footer area. - On Bugzilla's front page, there is an additional - <ulink url="../../page.cgi?id=quicksearch.html">Help</ulink> - link which details how to use it. - </para> - </section> - <section id="casesensitivity"> - <title>Case Sensitivity in Searches</title> - <para> - Bugzilla queries are case-insensitive and accent-insensitive, when - used with either MySQL or Oracle databases. When using Bugzilla with - PostgreSQL, however, some queries are case-sensitive. This is due to - the way PostgreSQL handles case and accent sensitivity. - </para> - </section> - <section id="list"> - <title>Bug Lists</title> - - <para>If you run a search, a list of matching bugs will be returned. - </para> - - <para>The format of the list is configurable. For example, it can be - sorted by clicking the column headings. Other useful features can be - accessed using the links at the bottom of the list: - <simplelist> - <member> - <emphasis>Long Format:</emphasis> - - this gives you a large page with a non-editable summary of the fields - of each bug.</member> - - <member> - <emphasis>XML:</emphasis> - - get the buglist in the XML format.</member> - - <member> - <emphasis>CSV:</emphasis> - - get the buglist as comma-separated values, for import into e.g. - a spreadsheet.</member> - - <member> - <emphasis>Feed:</emphasis> - - get the buglist as an Atom feed. Copy this link into your - favorite feed reader. If you are using Firefox, you can also - save the list as a live bookmark by clicking the live bookmark - icon in the status bar. To limit the number of bugs in the feed, - add a limit=n parameter to the URL.</member> - - <member> - <emphasis>iCalendar:</emphasis> - - Get the buglist as an iCalendar file. Each bug is represented as a - to-do item in the imported calendar.</member> - - <member> - <emphasis>Change Columns:</emphasis> - - change the bug attributes which appear in the list.</member> - - <member> - <emphasis>Change several bugs at once:</emphasis> - - If your account is sufficiently empowered, and more than one bug - appear in the bug list, this link is displayed which lets you make - the same change to all the bugs in the list - for example, changing - their assignee.</member> - - <member> - <emphasis>Send mail to bug assignees:</emphasis> - - If more than one bug appear in the bug list and there are at least - two distinct bug assignees, this links is displayed which lets you - easily send a mail to the assignees of all bugs on the list.</member> - - <member> - <emphasis>Edit Search:</emphasis> - - If you didn't get exactly the results you were looking for, you can - return to the Query page through this link and make small revisions - to the query you just made so you get more accurate results.</member> - - <member> - <emphasis>Remember Search As:</emphasis> - - You can give a search a name and remember it; a link will appear - in your page footer giving you quick access to run it again later. - </member> - </simplelist> - </para> - - <para> - If you would like to access the bug list from another program - it is often useful to have the list returned in something other - than HTML. By adding the ctype=type parameter into the bug list URL - you can specify several alternate formats. Besides the types described - above, the following formats are also supported: ECMAScript, also known - as JavaScript (ctype=js), and Resource Description Framework RDF/XML - (ctype=rdf). - </para> - </section> - - <section id="individual-buglists"> - <title>Adding/removing tags to/from bugs</title> - <para> - You can add and remove tags from individual bugs, which let you find and - manage them more easily. Creating a new tag automatically generates a saved - search - whose name is the name of the tag - which lists bugs with this tag. - This saved search will be displayed in the footer of pages by default, as - all other saved searches. The main difference between tags and normal saved - searches is that saved searches, as described in the previous section, are - stored in the form of a list of matching criteria, while the saved search - generated by tags is a list of bug numbers. Consequently, you can easily - edit this list by either adding or removing tags from bugs. To enable this - feature, you have to turn on the <quote>Enable tags for bugs</quote> user - preference, see <xref linkend="userpreferences" />. This feature is disabled - by default. - </para> - - <para> - This feature is useful when you want to keep track of several bugs, but - for different reasons. Instead of adding yourself to the CC list of all - these bugs and mixing all these reasons, you can now store these bugs in - separate lists, e.g. <quote>Keep in mind</quote>, <quote>Interesting bugs</quote>, - or <quote>Triage</quote>. One big advantage of this way to manage bugs - is that you can easily add or remove bugs one by one, which is not - possible to do with saved searches without having to edit the search - criteria again. - </para> - </section> </section> - - <section id="bugreports"> - <title>Filing Bugs</title> - - <section id="fillingbugs"> - <title>Reporting a New Bug</title> - - <para>Years of bug writing experience has been distilled for your - reading pleasure into the - <ulink - url="&landfillbase;page.cgi?id=bug-writing.html"> - Bug Writing Guidelines</ulink>. - While some of the advice is Mozilla-specific, the basic principles of - reporting Reproducible, Specific bugs, isolating the Product you are - using, the Version of the Product, the Component which failed, the - Hardware Platform, and Operating System you were using at the time of - the failure go a long way toward ensuring accurate, responsible fixes - for the bug that bit you.</para> - - <para>The procedure for filing a bug is as follows:</para> - - <orderedlist> - <listitem> - <para> - Click the <quote>New</quote> link available in the footer - of pages, or the <quote>Enter a new bug report</quote> link - displayed on the home page of the Bugzilla installation. - </para> - - <note> - <para> - If you want to file a test bug to see how Bugzilla works, - you can do it on one of our test installations on - <ulink url="&landfillbase;">Landfill</ulink>. - </para> - </note> - </listitem> - - <listitem> - <para> - You first have to select the product in which you found a bug. - </para> - </listitem> - - <listitem> - <para> - You now see a form where you can specify the component (part of - the product which is affected by the bug you discovered; if you have - no idea, just select <quote>General</quote> if such a component exists), - the version of the program you were using, the Operating System and - platform your program is running on and the severity of the bug (if the - bug you found crashes the program, it's probably a major or a critical - bug; if it's a typo somewhere, that's something pretty minor; if it's - something you would like to see implemented, then that's an enhancement). - </para> - </listitem> - - <listitem> - <para> - You now have to give a short but descriptive summary of the bug you found. - <quote>My program is crashing all the time</quote> is a very poor summary - and doesn't help developers at all. Try something more meaningful or - your bug will probably be ignored due to a lack of precision. - The next step is to give a very detailed list of steps to reproduce - the problem you encountered. Try to limit these steps to a minimum set - required to reproduce the problem. This will make the life of - developers easier, and the probability that they consider your bug in - a reasonable timeframe will be much higher. - </para> - - <note> - <para> - Try to make sure that everything in the summary is also in the first - comment. Summaries are often updated and this will ensure your original - information is easily accessible. - </para> - </note> - </listitem> - - <listitem> - <para> - As you file the bug, you can also attach a document (testcase, patch, - or screenshot of the problem). - </para> - </listitem> - - <listitem> - <para> - Depending on the Bugzilla installation you are using and the product in - which you are filing the bug, you can also request developers to consider - your bug in different ways (such as requesting review for the patch you - just attached, requesting your bug to block the next release of the - product, and many other product specific requests). - </para> - </listitem> - - <listitem> - <para> - Now is a good time to read your bug report again. Remove all misspellings, - otherwise your bug may not be found by developers running queries for some - specific words, and so your bug would not get any attention. - Also make sure you didn't forget any important information developers - should know in order to reproduce the problem, and make sure your - description of the problem is explicit and clear enough. - When you think your bug report is ready to go, the last step is to - click the <quote>Commit</quote> button to add your report into the database. - </para> - </listitem> - </orderedlist> - - <para> - You do not need to put "any" or similar strings in the URL field. - If there is no specific URL associated with the bug, leave this - field blank. - </para> - - <para>If you feel a bug you filed was incorrectly marked as a - DUPLICATE of another, please question it in your bug, not - the bug it was duped to. Feel free to CC the person who duped it - if they are not already CCed. - </para> - </section> - - <section id="cloningbugs"> - <title>Clone an Existing Bug</title> - + + <section id="why"> + <title>Why Should We Use Bugzilla?</title> + <epigraph> <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. + No, Who's on first... </para> - </section> - - </section> - - <section id="attachments"> - <title>Attachments</title> - + </epigraph> <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. + For many years, defect-tracking software has remained principally the domain + of large software development houses. Even then, most shops never bothered + with bug-tracking software, and instead simply relied on shared lists and + email to monitor the status of defects. This procedure is error-prone and + tends to cause those bugs judged least significant by developers to be + dropped or ignored </para> - - <para>You should make sure to trim screenshots. There's no need to show the - whole screen if you are pointing out a single-pixel problem. - </para> - - <para>Bugzilla stores and uses a Content-Type for each attachment - (e.g. text/html). To download an attachment as a different - Content-Type (e.g. application/xhtml+xml), you can override this - using a 'content_type' parameter on the URL, e.g. - <filename>&content_type=text/plain</filename>. - </para> - <para> - If you have a really large attachment, something that does not need to - be recorded forever (as most attachments are), or something that is too - big for your database, you can mark your attachment as a - <quote>Big File</quote>, assuming the administrator of the installation - has enabled this feature. Big Files are stored directly on disk instead - of in the database. The maximum size of a <quote>Big File</quote> is - normally larger than the maximum size of a regular attachment. Independently - of the storage system used, an administrator can delete these attachments - at any time. Nevertheless, if these files are stored in the database, the - <quote>allow_attachment_deletion</quote> parameter (which is turned off - by default) must be enabled in order to delete them. + These days, many companies are finding that integrated defect-tracking + systems reduce downtime, increase productivity, and raise customer + satisfaction with their systems. Along with full disclosure, an open + bug-tracker allows manufacturers to keep in touch with their clients + and resellers, to communicate about problems effectively throughout + the data management chain. Many corporations have also discovered that + defect-tracking helps reduce costs by providing IT support accountability, + telephone support knowledge bases, and a common, well-understood system + for accounting for unusual system or software issues. </para> - <para> - Also, if the administrator turned on the <quote>allow_attach_url</quote> - parameter, you can enter the URL pointing to the attachment instead of - uploading the attachment itself. For example, this is useful if you want to - point to an external application, a website or a very large file. Note that - there is no guarantee that the source file will always be available, nor - that its content will remain unchanged. + But why should <emphasis>you</emphasis> use Bugzilla? </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. + Bugzilla is very adaptable to various situations. Known uses currently + include IT support queues, Systems Administration deployment management, + chip design and development problem tracking (both pre-and-post fabrication), + and software and hardware bug tracking for luminaries such as Redhat, Loki software, + Linux-Mandrake, and VA Systems. Combined with systems such as CVS, Bonsai, + or Perforce SCM, Bugzilla provides a powerful, easy-to-use solution to + configuration management and replication problems </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. + Bugzilla can dramatically increase the productivity and accountability + of individual employees by providing a documented workflow and positive + feedback for good performance. How many times do you wake up in the + morning, remembering that you were supposed to do *something* today, + but you just can't quite remember? Put it in Bugzilla, and you have a record + of it from which you can extrapolate milestones, predict product versions + for integration, and by using Bugzilla's e-mail integration features + be able to follow the discussion trail that led to critical decisions. </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. + Ultimately, Bugzilla puts the power in your hands to improve your value + to your employer or business while providing a usable framework for your natural + attention to detail and knowledge store to flourish. </para> </section> - - <section id="userpreferences"> - <title>User Preferences</title> - - <para> - Once logged in, you can customize various aspects of - Bugzilla via the "Preferences" link in the page footer. - The preferences are split into five tabs:</para> - - <section id="generalpreferences" xreflabel="General Preferences"> - <title>General Preferences</title> - - <para> - This tab allows you to change several default settings of Bugzilla. - </para> - - <itemizedlist spacing="compact"> - <listitem> - <para> - Bugzilla's general appearance (skin) - select which skin to use. - Bugzilla supports adding custom skins. - </para> - </listitem> - <listitem> - <para> - Quote the associated comment when you click on its reply link - sets - the behavior of the comment "Reply" link. Options include quoting the - full comment, just reference the comment number, or turn the link off. - </para> - </listitem> - <listitem> - <para> - Language used in email - select which language email will be sent in, - from the list of available languages. - </para> - </listitem> - <listitem> - <para> - After changing a bug - This controls what page is displayed after - changes to a bug are submitted. The options include to show the bug - just modified, to show the next bug in your list, or to do nothing. - </para> - </listitem> - <listitem> - <para> - Enable tags for bugs - turn bug tagging on or off. - </para> - </listitem> - <listitem> - <para> - Zoom textareas large when in use (requires JavaScript) - enable or - disable the automatic expanding of text areas when text is being - entered into them. - </para> - </listitem> - <listitem> - <para> - Field separator character for CSV files - - Select between a comma and semi-colon for exported CSV bug lists. - </para> - </listitem> - <listitem> - <para> - Automatically add me to the CC list of bugs I change - set default - behavior of CC list. Options include "Always", "Never", and "Only - if I have no role on them". - </para> - </listitem> - <listitem> - <para> - When viewing a bug, show comments in this order - - controls the order of comments. Options include "Oldest - to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the - bug description at the top". - </para> - </listitem> - <listitem> - <para> - Show a quip at the top of each bug list - controls - whether a quip will be shown on the Bug list page. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="emailpreferences"> - <title>Email Preferences</title> - - <para> - This tab allows you to enable or disable email notification on - specific events. - </para> - - <para> - In general, users have almost complete control over how much (or - how little) email Bugzilla sends them. If you want to receive the - maximum amount of email possible, click the <quote>Enable All - Mail</quote> button. If you don't want to receive any email from - Bugzilla at all, click the <quote>Disable All Mail</quote> button. - </para> - - <note> - <para> - A Bugzilla administrator can stop a user from receiving - bugmail by clicking the <quote>Bugmail Disabled</quote> checkbox - when editing the user account. This is a drastic step - best taken only for disabled accounts, as it overrides - the user's individual mail preferences. - </para> - </note> + <section id="how"> + <title>How do I use Bugzilla?</title> + <epigraph> <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. + Hey! I'm Woody! Howdy, Howdy, Howdy! </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> - + </epigraph> + + <para> + Bugzilla is a large, complex system. Describing how to use it + requires some time. If you are only interested in installing or administering + a Bugzilla installation, please consult the Installing and Administering + Bugzilla portions of this Guide. This section is principally aimed towards + developing end-user mastery of Bugzilla, so you may fully enjoy the benefits + afforded by using this reliable open-source bug-tracking software. + </para> + <para> + Throughout this portion of the Guide, we will refer to user account + options available at the Bugzilla test installation, + <ulink url="http://landfill.tequilarista.org/"> + landfill.tequilarista.org</ulink>. <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> + <para> + Some people have run into difficulties completing this tutorial. If + you run into problems, please check the updated, online documentation available + at <ulink url="http://www.trilobyte.net/barnsons/">http://www.trilobyte.net/barnsons</ulink>. + If you're still stumped, please subscribe to the newsgroup and provide details of exactly + what's stumping you! If enough people complain, I'll have to fix it in the next + version of this Guide. You can subscribe to the newsgroup at + <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools"> + news://news.mozilla.org/netscape.public.mozilla.webtools</ulink> + </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> - + Although Landfill serves as a great introduction to Bugzilla, it does not offer + all the options you would have as a user on your own installation of Bugzilla, + nor can it do more than serve as a general introduction to Bugzilla. Additionally, + Landfill often runs cutting-edge versions of Bugzilla for testing, so some things + may work slightly differently than mentioned here. + </para> + + <section id="myaccount"> + <title>Create a Bugzilla Account</title> <para> - This is a purely informative page which outlines your current - permissions on this installation of Bugzilla. + First thing's first! 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 the end-user Bugzilla experience, use this URL: + <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/"> + http://landfill.tequilarista.org/mozilla/bugzilla/</ulink> </para> - + <orderedlist> + <listitem> + <para> + Click the "Open a new Bugzilla account" link. + </para> + </listitem> + <listitem> + <para> + Enter your "E-mail address" and "Real Name" (or whatever name you want to call yourself) + in the spaces provided, then select the "Create Account" button. + </para> + </listitem> + <listitem> + <para> + Within 5-10 minutes, you should receive an email to the address you provided above, + which contains your login name (generally the same as the email address), and + a password you can use to access your account. This password is randomly generated, + and should be changed at your nearest opportunity (we'll go into how to do it later). + </para> + </listitem> + <listitem> + <para> + Click the "Log In" link in the yellow area at the bottom of the page in your browser, + then enter your "E-mail address" and "Password" you just received into the spaces provided, + and select "Login". + <note> + <para> + If you ever forget your password, you can come back to this page, enter your + "E-mail address", then select the "E-mail me a password" button to have your password + mailed to you again so that you can login. + </para> + </note> + <caution> + <para> + Many modern browsers include an "Auto-Complete" or "Form Fill" feature to + remember the user names and passwords you type in at many sites. Unfortunately, + sometimes they attempt to "guess" what you will put in as your password, and guess + wrong. If you notice a text box is already filled out, please overwrite the contents + of the text box so you can be sure to input the correct information. + </para> + </caution> + </para> + </listitem> + </orderedlist> <para> - A complete list of permissions is below. Only users with - <emphasis>editusers</emphasis> privileges can change the permissions - of other users. + Congratulations! If you followed these directions, you now are the + proud owner of a user account on landfill.tequilarista.org (Landfill) or + your local Bugzilla install. You should now see in your browser a + page called the "Bugzilla Query Page". It may look daunting, but + with this Guide to walk you through it, you will master it in no time. </para> - - <variablelist> - <varlistentry> - <term> - admin - </term> - <listitem> - <para> - Indicates user is an Administrator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhineatothers - </term> - <listitem> - <para> - Indicates user can configure whine reports for other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_canusewhines - </term> - <listitem> - <para> - Indicates user can configure whine reports for self. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudoers - </term> - <listitem> - <para> - Indicates user can perform actions as other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - bz_sudo_protect - </term> - <listitem> - <para> - Indicates user can not be impersonated by other users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - canconfirm - </term> - <listitem> - <para> - Indicates user can confirm a bug or mark it a duplicate. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - creategroups - </term> - <listitem> - <para> - Indicates user can create and destroy groups. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editbugs - </term> - <listitem> - <para> - Indicates user can edit all bug fields. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editclassifications - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit classifications. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editcomponents - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit components. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editkeywords - </term> - <listitem> - <para> - Indicates user can create, destroy, and edit keywords. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - editusers - </term> - <listitem> - <para> - Indicates user can edit or disable users. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - tweakparams - </term> - <listitem> - <para> - Indicates user can change Parameters. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <note> - <para> - For more information on how permissions work in Bugzilla (i.e. who can - change what), see <xref linkend="cust-change-permissions"/>. - </para> - </note> - </section> - </section> - - - <section id="reporting"> - <title>Reports and Charts</title> - - <para>As well as the standard buglist, Bugzilla has two more ways of - viewing sets of bugs. These are the reports (which give different - views of the current state of the database) and charts (which plot - the changes in particular sets of bugs over time.)</para> - <section id="reports"> - <title>Reports</title> - + <section id="query"> + <title>The Bugzilla Query Page</title> <para> - A report is a view of the current state of the bug database. + The Bugzilla Query Page is the heart and soul of Bugzilla. It is the master + interface where you can find any bug report, comment, or patch currently in the Bugzilla + system. We'll go into how to create your own bug report later on. </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. + There are efforts underway to simplify query usage. If you have a local installation + of Bugzilla 2.12 or higher, you should have "quicksearch.html" available + to use and simplify your searches. There is also, or shortly will be, a helper + for the query interface, called "queryhelp.cgi". Landfill tends to run the latest code, + so these two utilities should be available there for your perusal. </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. + At this point, please visit the main Bugzilla site, + <ulink url="http://bugzilla.mozilla.org/query.cgi"> + bugzilla.mozilla.org</ulink>, to see a more fleshed-out query page. </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. + The first thing you need to notice about the Bugzilla Query Page is that + nearly every box you see on your screen has a hyperlink nearby, explaining what + it is or what it does. Near the upper-left-hand corner of your browser window + you should see the word "Status" underlined. Select 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. + Notice the page that popped up? Every underlined word you see on your screen + is a hyperlink that will take you to context-sensitive help. + Click around for a while, and learn what everything here does. To return + to the query interface after pulling up a help page, use the "Back" button in + your browser. </para> - - </section> - - <section id="charts"> - <title>Charts</title> - <para> - A chart is a view of the state of the bug database over time. + I'm sure that after checking out the online help, you are now an Expert + on the Bugzilla Query Page. If, however, you feel you haven't mastered it yet, + let me walk you through making a few successful queries to find out what there + are in the Bugzilla bug-tracking system itself. </para> - + <orderedlist> + <listitem> + <para> + Ensure you are back on the "Bugzilla Query Page" + Do nothing in the boxes marked "Status", "Resolution", "Platform", "OpSys", + "Priority", or "Severity". The default query for "Status" is to find all bugs that + are NEW, ASSIGNED, or REOPENED, which is what we want. If you don't select anything + in the other 5 scrollboxes there, then you are saying that "any of these are OK"; + we're not locking ourselves into only finding bugs on the "DEC" Platform, or "Windows 95" + OpSys (Operating System). You're smart, I think you have it figured out. + </para> + <para> + Basically, selecting <emphasis>anything</emphasis> on the query page narrows your search + down. Leaving stuff unselected, or text boxes unfilled, broadens your search! + </para> + </listitem> + + <listitem> + <para> + You see the box immediately below the top six boxes that contains an "Email" text box, + with the words "matching as", a drop-down selection box, then some checkboxes with + "Assigned To" checked by default? This allows you to filter your search down based upon + email address. Let's put my email address in there, and see what happens. + </para> + <para> + Type "barnboy@trilobyte.net" in the top Email text box. + </para> + </listitem> + + <listitem> + <para> + Let's narrow the search some more. Scroll down until you find the box with the word + "Program" over the top of it. This is where we can narrow our search down to only + specific products (software programs or product lines) in our Bugzilla database. + Please notice the box is a <emphasis>scrollbox</emphasis>. Using the down arrow on the + scrollbox, scroll down until you can see an entry called "Webtools". Select this entry. + </para> + </listitem> + <listitem> + <para> + Did you notice that some of the boxes to the right changed when you selected "Webtools"? + Every Program (or Product) has different Versions, Components, and Target Milestones associated + with it. A "Version" is the number of a software program. + <example> + <title>Some Famous Software Versions</title> + <informalexample> + <para> + Do you remember the hype in 1995 when Microsoft Windows 95(r) was released? + It may have been several years + ago, but Microsoft(tm) spent over $300 Million advertising this new Version of their + software. Three years later, they released Microsoft Windows 98(r), + another new version, to great fanfare, and then in 2000 quietly + released Microsoft Windows ME(Millenium Edition)(r). + </para> + <para> + Software "Versions" help a manufacturer differentiate + their current product from their + previous products. Most do not identify their products + by the year they were released. + Instead, the "original" version of their software will + often be numbered "1.0", with + small bug-fix releases on subsequent tenths of a digit. In most cases, it's not + a decimal number; for instance, often 1.9 is an <emphasis>older</emphasis> version + of the software than 1.11, + but is a <emphasis>newer</emphasis> version than 1.1.1. + </para> + <para> + In general, a "Version" in Bugzilla should refer to + <emphasis>released</emphasis> + products, not products that have not yet been released + to the public. Forthcoming products + are what the Target Milestone field is for. + </para> + </informalexample> + </example> + </para> + <para> + A "Component" is a piece of a Product. + It may be a standalone program, or some other logical + division of a Product or Program. + Normally, a Component has a single Owner, who is responsible + for overseeing efforts to improve that Component. + <example> + <title>Mozilla Webtools Components</title> + <informalexample> + <para> + Mozilla's "Webtools" Product is composed of several pieces (Components): + <simplelist> + <member><emphasis>Bonsai</emphasis>, + a tool to show recent changes to Mozilla</member> + <member><emphasis>Bugzilla</emphasis>, + a defect-tracking tool</member> + <member><emphasis>Build</emphasis>, + a tool to automatically compile source code + into machine-readable form</member> + <member><emphasis>Despot</emphasis>, + a program that controls access to the other Webtools</member> + <member><emphasis>LXR</emphasis>, + a utility that automatically marks up text files + to make them more readable</member> + <member><emphasis>MozBot</emphasis>, + a "robot" that announces changes to Mozilla in Chat</member> + <member><emphasis>TestManager</emphasis>, + a tool to help find bugs in Mozilla</member> + <member><emphasis>Tinderbox</emphasis>, + which displays reports from Build</member> + </simplelist> + </para> + <para> + A different person is responsible for each of these Components. + Tara Hernandez keeps + the "Bugzilla" component up-to-date. + </para> + </informalexample> + </example> + </para> + <para> + A "Milestone", or "Target Milestone" is a often a planned future "Version" of a + product. In many cases, though, Milestones simply represent significant dates for + a developer. Having certain features in your Product is frequently + tied to revenue (money) + the developer will receive if the features work by the time she + reaches the Target Milestone. + Target Milestones are a great tool to organize your time. + If someone will pay you $100,000 for + incorporating certain features by a certain date, + those features by that Milestone date become + a very high priority. Milestones tend to be highly malleable creatures, + though, that appear + to be in reach but are out of reach by the time the important day arrives. + </para> + <para> + The Bugzilla Project has set up Milestones for future + Bugzilla versions 2.14, 2.16, 2.18, 3.0, etc. However, + a Target Milestone can just as easily be a specific date, + code name, or weird alphanumeric + combination, like "M19". + </para> + </listitem> + + <listitem> + <para> + OK, now let's select the "Bugzilla" component from its scrollbox. + </para> + </listitem> + <listitem> + <para> + Skip down the page a bit -- do you see the "submit query" button? + Select it, and let's run + this query! + </para> + </listitem> + <listitem> + <para> + Congratulations! You've completed your first Query, and have before you the Bug List + of the author of this Guide, Matthew P. Barnson (barnboy@trilobyte.net). If I'm + doing well, + you'll have a cryptic "Zarro Boogs Found" message on your screen. It is just + a happy hacker's way of saying "Zero Bugs Found". However, I am fairly certain I will + always have some bugs assigned to me that aren't done yet, + so you won't often see that message! + </para> + </listitem> + </orderedlist> <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. + I encourage you to click the bug numbers in the left-hand column and examine + my bugs. Also notice that if you click the underlined + links near the top of this page, they do + not take you to context-sensitive help here, + but instead sort the columns of bugs on the screen! + When you need to sort your bugs by priority, severity, + or the people they are assigned to, this + is a tremendous timesaver. + </para> + <para> + A couple more interesting things about the Bug List page: + <simplelist> + <member><emphasis>Change Columns</emphasis>: + by selecting this link, you can show all kinds + of information in the Bug List</member> + <member><emphasis>Change several bugs at once</emphasis>: + If you have sufficient rights to change all + the bugs shown in the Bug List, you can mass-modify them. + This is a big time-saver.</member> + <member><emphasis>Send mail to bug owners</emphasis>: + If you have many related bugs, you can request + an update from every person who owns the bugs in + the Bug List asking them the status.</member> + <member><emphasis>Edit this query</emphasis>: + If you didn't get exactly the results you were looking for, + you can return to the Query page through this link and make + small revisions to the query you just made so + you get more accurate results.</member> + </simplelist> </para> - <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> + <para> + There are many more options to the Bugzilla Query Page + and the Bug List than I have shown you. + But this should be enough for you to learn to get around. + I encourage you to check out the + <ulink url="http://www.mozilla.org/bugs/">Bugzilla Home Page</ulink> + to learn about the Anatomy + and Life Cycle of a Bug before continuing. + </para> </note> + </section> + + + <section id="bugreports"> + <title>Creating and Managing Bug Reports</title> + <epigraph> + <para>And all this time, I thought we were taking bugs <emphasis>out</emphasis>...</para> + </epigraph> - <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 id="bug_writing"> + <title>Writing a Great Bug Report</title> + <para> + Before we plunge into writing your first bug report, I encourage you to read + <ulink url="http://www.mozilla.org/quality/bug-writing-guidelines.html">Mozilla.org's 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> + While you are at it, why not learn how to find previously reported bugs? Mozilla.org + has published a great tutorial on finding duplicate bugs, available at + <ulink url="http://www.mozilla.org/quality/help/beginning-duplicate-finding.html"> + http://www.mozilla.org/quality/help/beginning-duplicate-finding.html</ulink>. + </para> + <para> + I realize this was a lot to read. However, understanding the mentality of writing + great bug reports will help us on the next part! + </para> + <orderedlist> + <listitem> + <para> + Go back to <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/"> + http://landfill.tequilarista.org/mozilla/bugzilla/</ulink> + in your browser. + </para> + </listitem> + <listitem> + <para> + Select the + <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/enter_bug.cgi"> + Enter a new bug report</ulink> link. + </para> + </listitem> + <listitem> + <para> + Select a product. + </para> + </listitem> + <listitem> + <para> + Now you should be at the "Enter Bug" form. + The "reporter" should have been automatically filled out + for you (or else Bugzilla prompted you to Log In again + -- you did keep the email with your username + and password, didn't you?). + </para> + </listitem> + <listitem> + <para> + Select a Component in the scrollbox. + </para> + </listitem> + <listitem> + <para> + Bugzilla should have made reasonable guesses, based upon your browser, + for the "Platform" and "OS" drop-down + boxes. If those are wrong, change them -- if you're on an SGI box + running IRIX, we want to know! + </para> + </listitem> + <listitem> + <para> + Fill in the "Assigned To" box with the email address you provided earlier. + This way you don't end up sending copies of your bug to lots of other people, + since it's just a test bug. + </para> + </listitem> + <listitem> + <para> + Leave the "CC" text box blank. + Fill in the "URL" box with "http://www.mozilla.org". + </para> + </listitem> + <listitem> + <para> + Enter "The Bugzilla Guide" in the Summary text box, + and place any comments you have on this + tutorial, or the Guide in general, into the Description box. + </para> + </listitem> + </orderedlist> + <para> + Voila! Select "Commit" and send in your bug report! + Next we'll look at resolving bugs. + </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 id="bug_manage"> + <title>Managing your Bug Reports</title> + <para> + OK, you should have a link to the bug you just created near the top of your page. + It should say + "Bug XXXX posted", with a link to the right saying "Back to BUG# XXXX". + Select this link. + </para> + <orderedlist> + <listitem> + <para> + Scroll down a bit on the subsequent page, + until you see the "Resolve bug, changing resolution to (dropdown box). + Normally, you would + "Accept bug (change status to ASSIGNED)", fix it, and then resolve. + But in this case, we're + going to short-circuit the process because this wasn't a real bug. + Change the dropdown next to + "Resolve Bug" to "INVALID", make sure the radio button is + marked next to "Resolve Bug", then + click "Commit". + </para> + </listitem> + <listitem> + <para> + Hey! It said it couldn't take the change in a big red box! + That's right, you must specify + a Comment in order to make this change. Select the "Back" + button in your browser, add a + Comment, then try Resolving the bug with INVALID status again. + This time it should work. + </para> + </listitem> + </orderedlist> + <para> + You have now learned the basics of Bugzilla navigation, + entering a bug, and bug maintenance. + I encourage you to explore these features, and see what you can do with them! + We'll spend no more time on individual Bugs or Queries from this point on, so you are + on your own there. + </para> + <para> + But I'll give a few last hints! + </para> + <para> + There is a <ulink url="http://bugzilla.mozilla.org/help.html">CLUE</ulink> + on the Query page + that will teach you more how to use the form. + </para> + <para> + If you click the hyperlink on the + <ulink url="http://bugzilla.mozilla.org/describecomponents.cgi">Component</ulink> + box of the Query page, you will be presented a form that will describe what all + the components are. + </para> + <para> + Possibly the most powerful feature of the Query page is the + <ulink url="http://bugzilla.mozilla.org/booleanchart.html">Boolean Chart</ulink> section. + It's a bit confusing to use the first time, but can provide unparalleled + flexibility in your queries, + allowing you to build extremely powerful requests. + </para> + <para> + Finally, you can build some nifty + <ulink url="http://bugzilla.mozilla.org/reports.cgi">Reports</ulink> + using the "Bug Reports" link near the bottom of the query page, and also + available via the "Reports" link + at the footer of each page. + </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> + <section id="init4me"> + <title>What's in it for me?</title> + <epigraph> <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). + Indiana, it feels like we walking on fortune cookies! </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. + These ain't fortune cookies, kid... </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). + </epigraph> + <para> + Customized User Preferences offer tremendous versatility to + your individual Bugzilla experience. + Let's plunge into what you can do! The first step is to click + the "Edit prefs" link at the footer of each page once you + have logged in to + <ulink url="http://landfill.tequilarista.org/mozilla/bugzilla/query.cgi?GoAheadAndLogIn=1"> + Landfill</ulink>. + </para> + <section id="accountsettings"> + <title>Account Settings</title> + <para> + On this page, you can change your basic Account Settings, + including your password and full name. + For security reasons, in order to change anything on this page you + must type your <emphasis>current</emphasis> + password into the "Old Password" field. + If you wish to change your password, type the new password you + want into the "New Password" field and again into the "Re-enter + new password" field to ensure + you typed your new password correctly. Select the "Submit" button and you're done! </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 id="emailsettings"> + <title>Email Settings</title> + <section id="notification"> + <title>Email Notification</title> + <note> + <para> + The email notification settings described below have been obsoleted in Bugzilla 2.12, and + this section will be replaced with a comprehensive description of the amazing array of + new options at your disposal. However, in the meantime, throw this chunk out the window + and go crazy with goofing around with different notification options. + </para> + </note> + <para> + Ahh, here you can reduce or increase the amount of email sent you from Bugzilla! + In the drop-down "Notify me of changes to", select one of + <simplelist> + <member><emphasis>All qualifying bugs</emphasis>: sends you every change to every bug + where your name is somewhere on it, regardless of who changed it.</member> + <member><emphasis>Only those bugs which I am listed in the CC line</emphasis>: prevents + you from receiving mail for which you are the reporter,' + owner, or QA contact. If you are on the CC + list, presumably someone had a <emphasis>good</emphasis> + reason for you to get the email.</member> + <member><emphasis>All qulifying bugs except those which I change</emphasis>: + This is the default, and + a sensible setting. If someone else changes your bugs, you will get emailed, + but if you change bugs + yourself you will receive no notification of the change.</member> + </simplelist> + </para> + </section> + <section id="newemailtech"> + <title>New Email Technology</title> + <note> + <para> + This option may not be available in all Bugzilla installations, depending upon + the preferences of the systems administrator responsible for the setup of your Bugzilla. + However, if you really want this functionality, ask her to "enable newemailtech + in Params" + and "make it the default for all new users", referring her to the Administration section + of this Guide. + </para> + </note> + <para> + Disregard the warnings about "experimental and bleeding edge"; the code to handle email + in a cleaner manner than that historically used for Bugzilla is + quite robust and well-tested now. + </para> + <para> + I recommend you enable the option, "Click here to sign up (and risk any bugs)". + Your email-box + will thank you for it. The fundamental shift in "newemailtech" is away from standard UNIX + "diff" output, which is quite ugly, to a prettier, better laid-out email. + </para> + </section> + <section id="watchsettings"> + <title>"Watching" Users</title> + <note> + <para> + This option may not be available in all Bugzilla installations, depending upon + the preferences of the systems administrator responsible for the setup of your Bugzilla. + However, if you really want this functionality, ask her to "enable watchers in Params". + </para> + </note> + <para> + By entering user email names into the "Users to watch" text entry box, delineated by commas, + you can watch bugs of other users. This powerful functionality enables seamless transitions + as developers change projects, managers wish to get in touch with the issues faced by their + direct reports, or users go on vacation. If any of these three situations apply + to you, you will undoubtedly find this feature quite convenient. + </para> + </section> </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> - + <section id="footersettings"> + <title>Page Footer</title> <note> - <para> - When running queries, the whining system acts as if you are the user - executing the query. This means that the whining system will ignore - bugs that match your query, but that you can not access. - </para> + <para> + By default, this page is quite barren. However, go explore the Query Page some more; you will + find that you can store numerous queries on the server, so if you regularly run a particular query + it is just a drop-down menu away. On this page of Preferences, if you have many stored + queries you can elect to have them always one-click away! + </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> + If you have many stored queries on the server, here you will find individual drop-downs for each + stored query. Each drop-down gives you the option of that query appearing on the footer of every + page in Bugzilla! This gives you powerful one-click access to any complex searches you may set up, + and is an excellent way to impress your boss... + </para> + <tip> + <para>By default, the "My Bugs" link appears at the bottom of each page. However, this query + gives you both the bugs you have reported, as well as those you are assigned. One of the most + common uses for this page is to remove the "My Bugs" link, replacing it with two other queries, + commonly called "My Bug Reports" and "My Bugs" (but only referencing bugs assigned to you). This + allows you to distinguish those bugs you have reported from those you are assigned. I commonly + set up complex Boolean queries in the Query page and link them to my footer in this page. When + they are significantly complex, a one-click reference can save hours of work.</para> + </tip> </section> - - <section> - <title>Saving Your Changes</title> - + <section id="permissionsettings"> + <title>Permissions</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. + This is a purely informative page which outlines your current permissions on + this installation of Bugzilla. If you have permissions to grant certain permissions to + other users, the "other users" link appears on this page as well as the footer. + For more information regarding user administration, please consult the Administration + section of this Guide. </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> + <section id="usingbz-conc"> + <title>Using Bugzilla-Conclusion</title> + <para> + Thank you for reading through this portion of the Bugzilla Guide. I anticipate + it may not yet meet the needs of all readers. If you have additional comments or + corrections to make, please submit your contributions to the + <ulink url="mailto://mozilla-webtools@mozilla.org">mozilla-webtools</ulink> + mailing list/newsgroup. The mailing list is mirrored to the netscape.public.mozilla.webtools + newsgroup, and the newsgroup is mirrored to mozilla-webtools@mozilla.org + </para> + </section> </chapter> + <!-- Keep this comment at the end of the file Local variables: mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil +sgml-omittag:t +sgml-shorttag:t +sgml-namecase-general:t sgml-general-insert-case:lower -sgml-indent-data:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:Bugzilla-Guide\.sgml +sgml-exposed-tags:nil 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: --> - |