mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-19 00:05:36 +00:00
Bug 274404 - Document the new whining functionality that will be available in 2.20. Patch by A. Karl Kornel <karl@kornel.name> r=colin (carrying forward joel's content r)
This commit is contained in:
mozilla%colinogilvie.co.uk
parent
b568af749a
commit
ad21d3becf
@ -1,5 +1,5 @@
|
||||
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
|
||||
<!-- $Id: installation.xml,v 1.97 2005/07/01 16:21:42 mozilla%colinogilvie.co.uk Exp $ -->
|
||||
<!-- $Id: installation.xml,v 1.98 2005/07/01 22:41:31 mozilla%colinogilvie.co.uk Exp $ -->
|
||||
<chapter id="installing-bugzilla">
|
||||
<title>Installing Bugzilla</title>
|
||||
|
||||
@ -1176,7 +1176,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="installation-whining-cron">
|
||||
<title>The Whining Cron</title>
|
||||
|
||||
<para>What good are
|
||||
@ -1202,6 +1202,45 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section id="installation-whining">
|
||||
<title>Whining</title>
|
||||
|
||||
<para>
|
||||
As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
|
||||
them at regular intervals, by having Bugzilla execute saved searches
|
||||
at certain times and emailing the results to the user. This is known
|
||||
as "Whining". The process of configuring Whining is described
|
||||
in <xref linkend="whining"/>, but for it to work a Perl script must be
|
||||
executed at regular intervals.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This can be done by adding the following command as a daily
|
||||
crontab entry, in the same manner as explained above for bug
|
||||
graphs. This example runs it every 15 minutes.
|
||||
</para>
|
||||
|
||||
<programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Whines can be executed as often as every 15 minutes, so if you specify
|
||||
longer intervals between executions of whine.pl, some users may not
|
||||
be whined at as often as they would expect. Depending on the person,
|
||||
this can either be a very Good Thing or a very Bad Thing.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Windows does not have 'cron', but it does have the Task
|
||||
Scheduler, which performs the same duties. There are also
|
||||
third-party tools that can be used to implement cron, such as
|
||||
<ulink url="http://www.nncron.ru/">nncron</ulink>.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section id="patch-viewer">
|
||||
<title>Patch Viewer</title>
|
||||
|
||||
|
||||
@ -1160,6 +1160,214 @@
|
||||
</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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user