274404 - There are no docs for Whining

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Dave Miller [:justdave]]

There appear to be no docs at all for Whining, either how to configure it
(adding the cron job, putting people in the group) or how to use it.  This is
currently a "documentation?" flag on bug 185090, but I'm separating it out so I
can make it a release blocker.  This is one of our advertised major new
features, we can't release without having docs for it. :)

Comment 1

[Jacob Steenhagen]

Whew, 2.20

You had me worried that this was another crunch item for 2.18 :).

Comment 2

[Myk Melez [:myk] [@mykmelez]]

"If it's not a regression from 2.18 and it's not a critical problem with
something that's already landed, let's push it off." - Dave

Comment 3

[Max Kanat-Alexander]

I'd count this as a critical problem with something that's already landed.
Although the editwhines page is pretty decent at self-documentation.

However, I'd say that this is probably the most important doc bug for 2.20, at
the moment.

Comment 4

[Colin Ogilvie [:cso]]

Erik, are you going to have time to document whining before 2.20 (final)?

Comment 5

[A. Karl Kornel]

Attachment: Whining docs, draft 1

I hope nobody minds; I went ahead and threw together some whining
documentation!

This includes both a section on how to use whining, and a section (under
"optional configuration") on how to set up Cron to run the whining script.

I'm requesting review from documentation, for obvious reasons and
not-so-obvious reasons (I don't have a working docbook installation, and can't
completely check everything).

Comment 6

[A. Karl Kornel]

Comment on attachment 187097 [details] [diff] [review]
Whining docs, draft 1

I'm also requesting review from erik.  He's listed as the reviewer for
editwhines.cgi, so I assume that he would know the most about the new Whining
system, and will be able to point out errors and omissions.

Comment 7

[Colin Ogilvie [:cso]]

Comment on attachment 187097 [details] [diff] [review]
Whining docs, draft 1

>Index: installation.xml
>+    <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

Missing / on the xref tag.

>+        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>0-59/15 * * * * cd &lt;your-bugzilla-directory&gt; ; ./whine.pl</programlisting>

Nit: */15 would achieve the same effect, I believe.

>+
>+      <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 a person's
>+          personality and overall, this can either be a very Good Thing or a 
>+          very Bad Thing.
>+        </para>
>+      </note>

"personality and overall," seems an abrupt stop.

>+      <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>
>+

>Index: using.xml
>===================================================================
>RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/xml/using.xml,v
>retrieving revision 1.30
>diff -u -r1.30 using.xml
>--- using.xml	20 Jun 2005 19:16:28 -0000	1.30
>+++ using.xml	23 Jun 2005 03:41:31 -0000
>@@ -1160,6 +1160,205 @@
>     </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.

Missing </para>

With those fixed it generates, but I'm not enough of an expert on the whining
system to say that the documentation is correct... over to erik for that.

Comment 8

[A. Karl Kornel]

Comment on attachment 187097 [details] [diff] [review]
Whining docs, draft 1

Attachment 187097 [details] [diff] is being replaced, so I'm moving the request for review of
its contents to draft 2.

Comment 9

[A. Karl Kornel]

Attachment: Whining docs, draft 2

Modification of attachment 187097 [details] [diff] [review], taking into account comment 7:

> Missing / on the xref tag.
Missing / added.
> Nit: */15 would achieve the same effect, I believe.
* looks much better than 0-59.	Modified.
> "personality and overall," seems an abrupt stop.
True.  Dropped phrase & modified wording a bit.
> Missing </para>
Missing tag added

Again, requesting review from [e-mail].  Colin (or whomever
reviews this for documentation):  Would it be possible to post the rendered
HTML for viewing?

Comment 10

[A. Karl Kornel]

Comment on attachment 187119 [details] [diff] [review]
Whining docs, draft 2

Moved request for review of accuracy of body from draft 1 to draft 2.

Comment 11

[Colin Ogilvie [:cso]]

Comment on attachment 187119 [details] [diff] [review]
Whining docs, draft 2

r+ pending someone that knows whining better than I reading it over...

Comment 12

[Colin Ogilvie [:cso]]

Attachment: HTML Output

Output from HTML

Comment 13

[A. Karl Kornel]

Comment on attachment 187119 [details] [diff] [review]
Whining docs, draft 2

It's been 7+ days since the review request.  Per instructions from IRC, asking
joel.

Comment 14

[Joel Peshkin]

Comment on attachment 187119 [details] [diff] [review]
Whining docs, draft 2

Heck yes...  whining needs docs.

Comment 15

[A. Karl Kornel]

joel: From your review+ on draft 2, can I take that to mean that the details are correct, and that nothing 
important is missing?  If so, could you (or someone with appropriate privs.) request approval?  Thanks!

Comment 16

[Joel Peshkin]

Actually, there is always something left out.  However, we start by going from
no docs to some doc, then we improve further.

Comment 17

[Jacob Steenhagen]

Checking in installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <-- 
installation.xml
new revision: 1.96; previous revision: 1.95
done
Checking in using.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/using.xml,v  <--  using.xml
new revision: 1.31; previous revision: 1.30
done

(Yes, I do still exist :)

Comment 18

[Colin Ogilvie [:cso]]

Checking in using.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/using.xml,v  <--  using.xml
new revision: 1.32; previous revision: 1.31
done
Checking in installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <-- 
installation.xml
new revision: 1.97; previous revision: 1.96
done

Backing bug out as it turned the tinderbox red, pending investigation (and a
couple of spelling fixes...)

jade:../xml/using.xml:1350:9:E: document type does not allow element "para"
here; missing one of "glossary", "bibliography", "index" start-tag
jade:../xml/using.xml:1356:9:E: document type does not allow element "para"
here; missing one of "glossary", "bibliography", "index" start-tag

Oddly, this will build perfectly with xmlto, but will not build with jade on
landfill.

Comment 19

[A. Karl Kornel]

Attachment: Whining docs, draft 3

Quoting from 'Description' in
<http://www.oreilly.com/catalog/docbook/chapter/book/section.html>:

"None of the sectioning elements is allowed to "float" in a component. You can
place paragraphs and other block elements before a section, but you cannot
place anything after it."

The 2 <para>s that were causing the error weren't in a <section>, and they came
immediately after a </section>.  I created a new <section> to hold the last 2
paragraphs.  Also corrected two instances of 'wining', and changed an
<important> to a <warning>.

Comment 20

[Colin Ogilvie [:cso]]

Comment on attachment 187961 [details] [diff] [review]
Whining docs, draft 3

Works in jade now too...

Comment 21

[Colin Ogilvie [:cso]]

Let's try again....

Checking in installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <-- 
installation.xml
new revision: 1.98; previous revision: 1.97
done
Checking in using.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/using.xml,v  <--  using.xml
new revision: 1.33; previous revision: 1.32
done