<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
  <title>Contrib</title>

  <para>
    There are a number of unofficial Bugzilla add-ons in the 
    <filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
    directory. This section documents them.
  </para>

  <section id="cmdline">
    <title>Command-line Search Interface</title>

    <para>
      There are a suite of Unix utilities for searching Bugzilla from the 
      command line. They live in the 
      <filename class="directory">contrib/cmdline</filename> directory.
      There are three files - <filename>query.conf</filename>,
      <filename>buglist</filename> and <filename>bugs</filename>.
    </para>

    <warning>
      <para>
        These files pre-date the templatisation work done as part of the
        2.16 release, and have not been updated.
      </para>
    </warning>
    
    <para>
      <filename>query.conf</filename> contains the mapping from
      options to field names and comparison types. Quoted option names
      are <quote>grepped</quote> for, so it should be easy to edit this
      file. Comments (#) have no effect; you must make sure these lines
      do not contain any quoted <quote>option</quote>.
    </para>

    <para>
      <filename>buglist</filename> is a shell script that submits a
      Bugzilla query and writes the resulting HTML page to stdout.
      It supports both short options, (such as <quote>-Afoo</quote>
      or <quote>-Rbar</quote>) and long options (such
      as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>).
      If the first character of an option is not <quote>-</quote>, it is
      treated as if it were prefixed with <quote>--default=</quote>.
    </para>

    <para>
      The column list is taken from the COLUMNLIST environment variable.
      This is equivalent to the <quote>Change Columns</quote> option
      that is available when you list bugs in buglist.cgi. If you have
      already used Bugzilla, grep for COLUMNLIST in your cookies file
      to see your current COLUMNLIST setting.
    </para>

    <para>
      <filename>bugs</filename> is a simple shell script which calls
      <filename>buglist</filename> and extracts the
      bug numbers from the output. Adding the prefix
      <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote>
      turns the bug list into a working link if any bugs are found.
      Counting bugs is easy. Pipe the results through 
      <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command>
    </para>

    <para>
      Akkana Peck says she has good results piping 
      <filename>buglist</filename> output through 
      <command>w3m -T text/html -dump</command>
    </para>

  </section>

  <section id="cmdline-bugmail">
    <title>Command-line 'Send Unsent Bug-mail' tool</title>

    <para>
      Within the <filename class="directory">contrib</filename> directory
      exists a utility with the descriptive (if compact) name
      of <filename>sendunsentbugmail.pl</filename>. The purpose of this
      script is, simply, to send out any bug-related mail that should
      have been sent by now, but for one reason or another has not.
    </para>

    <para>
      To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses
      the same mechanism as the <filename>sanitycheck.cgi</filename> script;
      it scans through the entire database looking for bugs with changes that
      were made more than 30 minutes ago, but where there is no record of
      anyone related to that bug having been sent mail. Having compiled a list,
      it then uses the standard rules to determine who gets mail, and sends it
      out.
    </para>

    <para>
      As the script runs, it indicates the bug for which it is currently
      sending mail; when it has finished, it gives a numerical count of how
      many mails were sent and how many people were excluded. (Individual
      user names are not recorded or displayed.) If the script produces
      no output, that means no unsent mail was detected.
    </para>

    <para>
      <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script
      up into the main directory, ensure it has execute permission, and run it
      from the command line (or from a cron job) with no parameters.
    </para>
  </section>

</appendix>

<!-- 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:
-->