diff options
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: --> - |