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