<listitem>
<para>
<emphasis>Attachments:</emphasis>
- You can attach files (e.g. testcases or patches) to bugs. If there
- are any attachments, they are listed in this section.</para>
+ 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>
</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>Once you've run a search, you can save it as a Saved Search, which
appears in the page footer.</para>
- <para>Highly advanced querying is done using Boolean Charts. See the
- Boolean Charts help link on the Search page for more information.</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">
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>
If your account is sufficiently empowered, you can make the same
change to all the bugs in the list - for example, changing their
- owner.</member>
+ assignee.</member>
<member>
- <emphasis>Send mail to bug owners:</emphasis>
+ <emphasis>Send mail to bug assignees:</emphasis>
- Sends mail to the owners of all bugs on the list.</member>
+ Sends mail to the assignees of all bugs on the list.</member>
<member>
<emphasis>Edit Search:</emphasis>
</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">
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>
+
+ <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="emailsettings">
<title>Email Settings</title>
- <para>On this tab you can reduce or increase the amount of email sent
- you from Bugzilla, opting in our out depending on your relationship to
- the bug and the change that was made to it.
+ <para>
+ This tab controls the amount of email Bugzilla sends you.
</para>
-
+
<para>
- You can also do further filtering on the client side by
- using the X-Bugzilla-Reason mail header which Bugzilla
- adds to all bugmail. This tells you what relationship you have to the
- bug in question,
- and can be any of Owner, Reporter, QAcontact, CClist, Voter and
- WatchingComponent.</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>
- <para>By entering user email names, delineated by commas, into the
- "Users to watch" text entry box you can receive a copy of all the
- bugmail of other users (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>The ability to watch other users may not be available in all
- Bugzilla installations. If you can't see it, ask your
- administrator.</para>
+ <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">
</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
projects / thirdparty / bugzilla.git / commitdiff
