| <!-- <!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> |
| </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>Click the |
| <quote>Open a new Bugzilla account</quote> |
| |
| link, enter your email address and, optionally, your name in the |
| spaces provided, then click |
| <quote>Create Account</quote> |
| |
| .</para> |
| </listitem> |
| |
| <listitem> |
| <para>Within moments, you should receive an email to the address |
| you provided, which contains your login name (generally the |
| same as the email address), and a password. |
| This password is randomly generated, but can be |
| changed to something more memorable.</para> |
| </listitem> |
| |
| <listitem> |
| <para>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 into the spaces provided, and |
| click |
| <quote>Login</quote>. |
| </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.</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>*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 prioritise 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>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 and (unlike attachments |
| kept in the database) may be deleted at some future time. |
| </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 |
| repsentation 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. |
| </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>Once you've run a search, you can save it as a Saved Search, which |
| appears in the page footer.</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 critera. |
| </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, |
| additonal 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 field containing |
| a user's ID (such as ReportedBy) with |
| a user's ID (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 |
| referes 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> |
| </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> |
| |
| <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>CSV:</emphasis> |
| |
| get the buglist as comma-separated values, for import into e.g. |
| a spreadsheet.</member> |
| |
| <member> |
| <emphasis>RSS</emphasis> |
| |
| get the buglist as an RSS 1.0 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, you can 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> |
| |
| Sends 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. The supported formats |
| are: Comma Separated Values (ctype=csv), iCalendar (ctype=ics), |
| RDF Site Summary (RSS) 1.0 (ctype=rss), ECMAScript, also known |
| as JavaScript (ctype=js), and finally Resource Description Framework |
| RDF/XML (ctype=rdf). |
| </para> |
| </section> |
| |
| <section id="bugreports"> |
| <title>Filing Bugs</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 test bug is as follows:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Go to |
| <ulink url="&landfillbase;"> |
| Landfill</ulink> |
| in your browser and click |
| <ulink |
| url="&landfillbase;enter_bug.cgi"> |
| Enter a new bug report</ulink>. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para>Select a product - any one will do.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Fill in the fields. Bugzilla should have made reasonable |
| guesses, based upon your browser, for the "Platform" and "OS" |
| drop-down boxes. If they are wrong, change them.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Select "Commit" and send in your bug report.</para> |
| </listitem> |
| </orderedlist> |
| |
| <para>Try to make sure that everything said in the summary is also |
| said in the first comment. Summaries are often updated and this will |
| ensure your original information is easily accessible. |
| </para> |
| |
| <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="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. (Copy Link |
| Location in Mozilla works as well.)</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 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="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 |
| "<filename>foo|bar</filename>" |
| into Quicksearch would search for "foo" or "bar" in the |
| summary and status whiteboard of a bug; adding |
| "<filename>:BazProduct</filename>" would |
| search only in that product. |
| </para> |
| |
| <para>You'll find the Quicksearch box on Bugzilla's |
| front page, along with a |
| <ulink url="../../quicksearch.html">Help</ulink> |
| link which details how to use it.</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="attachments"> |
| <title>Attachments</title> |
| |
| <para> |
| 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>Trim screenshots. There's no need to show the whole screen if |
| you are pointing out a single-pixel problem. |
| </para> |
| |
| <para>Don't attach simple test cases (e.g. one HTML file, one |
| CSS file and an image) as a ZIP file. Instead, upload them in |
| reverse order and edit the referring file so that they point to the |
| attached files. This way, the test case works immediately |
| out of the bug. |
| </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), you can mark your |
| attachment as a Big File, Assuming the administrator of the |
| installation has enabled this feature. Big Files are stored directly on |
| disk instead of in the database, and can be deleted when it is no longer |
| needed. The maximum size of a Big File is normally larger than the |
| maximum size of a regular attachment. |
| </para> |
| </section> |
| </section> |
| |
| <section id="userpreferences"> |
| <title>User Preferences</title> |
| |
| <para>Once you have logged in, you can customise various aspects of |
| Bugzilla via the "Edit prefs" link in the page footer. |
| The preferences are split into three tabs:</para> |
| |
| <section id="accountsettings" xreflabel="Account Settings"> |
| <title>Account Settings</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="emailsettings"> |
| <title>Email Settings</title> |
| |
| <para> |
| This tab controls the amount of email Bugzilla sends you. |
| </para> |
| |
| <para> |
| The first item on this page is marked <quote>Users to watch</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> |
| 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> |
| Your Bugzilla administrator can stop a user from receiving |
| bugmail by adding the user's name to the |
| <filename>data/nomail</filename> file. This is a drastic step |
| best taken only for disabled accounts, as it overrides the |
| the user's individual mail preferences. |
| </para> |
| </note> |
| |
| <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> |
| Two items not in the table (<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>) 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> |
| By default, Bugzilla sends out email regardless of who made the |
| change... even if you were the one responsible for generating |
| the email in the first place. If you don't care to receive bugmail |
| from your own changes, check the box marked <quote>Only email me |
| reports of changes made by other people</quote>. |
| </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 - what product groups you |
| are in, and whether you can edit bugs or perform various administration |
| functions.</para> |
| </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> |
| <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. |
| </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 Queries). |
| </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 Queries</title> |
| |
| <para> |
| Each whining event is associated with zero or more queries. A query is |
| a saved search that is executed on the schedule specified (see above). |
| You start out with zero queries attached to the event (which means that |
| the event will not run, as there will never be any results to return). |
| To add a query, press the "Add a new query" button. |
| </para> |
| |
| <para> |
| The first field to examine in your new query is the Sort field. Queries |
| are executed, and results returned, in the order specified by the Sort |
| field. Queries with lower Sort values will run before queries with |
| higher 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: |
| --> |
| |
