09a844f763
Patch by Marc Schumann <wurblzap@gmail.com>, r=vladd, a=myk git-svn-id: svn://10.0.0.236/trunk@249418 18797224-902f-48f8-a5cc-f745e15eee43
1547 lines
58 KiB
XML
1547 lines
58 KiB
XML
<!-- <!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>*Time Tracking:</emphasis>
|
|
This form can be used for time tracking.
|
|
To use this feature, you have to be blessed group membership
|
|
specified by the <quote>timetrackinggroup</quote> parameter.
|
|
<simplelist>
|
|
<member>
|
|
<emphasis>Orig. Est.:</emphasis>
|
|
This field shows the original estimated time.</member>
|
|
|
|
<member>
|
|
<emphasis>Current Est.:</emphasis>
|
|
This field shows the current estimated time.
|
|
This number is calculated from <quote>Hours Worked</quote>
|
|
and <quote>Hours Left</quote>.</member>
|
|
|
|
<member>
|
|
<emphasis>Hours Worked:</emphasis>
|
|
This field shows the number of hours worked.</member>
|
|
|
|
<member>
|
|
<emphasis>Hours Left:</emphasis>
|
|
This field shows the <quote>Current Est.</quote> -
|
|
<quote>Hours Worked</quote>.
|
|
This value + <quote>Hours Worked</quote> will become the
|
|
new Current Est.</member>
|
|
|
|
<member>
|
|
<emphasis>%Complete:</emphasis>
|
|
This field shows what percentage of the task is complete.</member>
|
|
|
|
<member>
|
|
<emphasis>Gain:</emphasis>
|
|
This field shows the number of hours that the bug is ahead of the
|
|
<quote>Orig. Est.</quote>.</member>
|
|
|
|
<member>
|
|
<emphasis>Deadline:</emphasis>
|
|
This field shows the deadline for this bug.</member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Attachments:</emphasis>
|
|
You can attach files (e.g. testcases or patches) to bugs. If there
|
|
are any attachments, they are listed in this section. Attachments are
|
|
normally stored in the Bugzilla database, unless they are marked as
|
|
Big Files, which are stored directly on disk 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.
|
|
On the Saved Searches tab of your User Preferences page (the Prefs link
|
|
in Bugzilla's footer), members of the group defined in the
|
|
querysharegroup parameter can share such Saved Searches with user groups
|
|
so that other users may use them.
|
|
At the same place, you can see Saved Searches other users are sharing, and
|
|
have them show up in your personal Bugzilla footer along with your own
|
|
Saved Searches.
|
|
If somebody is sharing a Search with a group she or he is allowed to
|
|
<xref linkend="groups">assign users to</a>, it will show up in the
|
|
group's direct members' footers by default.
|
|
</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 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.
|
|
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="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 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="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="accountpreferences" xreflabel="Account Preferences">
|
|
<title>Account Preferences</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="generalpreferences" xreflabel="General Preferences">
|
|
<title>General Preferences</title>
|
|
|
|
<para>
|
|
This tab allows you to change several Bugzilla behavior.
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
Field separator character for CSV files -
|
|
This controls separator character used in CSV formatted Bug List.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
After changing bugs - This controls which bugs or no bugs
|
|
are shown in the page after you changed bugs.
|
|
You can select the bug you've changed this time, or the next
|
|
bug of the list.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Add individual bugs to saved searches - this controls
|
|
whether you can add individual bugs to saved searches
|
|
or you can't.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
When viewing a bug, show comments in this order -
|
|
This controls the order of comments, you can select below:
|
|
<simplelist>
|
|
<member>Initial description, comment 1, comment 2, ...</member>
|
|
<member>Initial description, last comment, ..., comment 2, comment 1.</member>
|
|
<member>Initial last comment, ..., comment 2, comment 1, description.</member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Show a quip at the top of each bug list - This controls
|
|
whether a quip will be shown on the Bug list page or not.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="emailpreferences">
|
|
<title>Email Preferences</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>
|
|
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>
|
|
|
|
<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 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:
|
|
-->
|
|
|