path: root/docs/sgml/patches.sgml

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

  <para>Are you looking for a way to put your Bugzilla into overdrive? Catch
  some of the niftiest tricks here in this section.</para>

  <section id="rewrite" xreflabel="Apache mod_rewrite magic">
    <title>Apache 
    <filename>mod_rewrite</filename>

    magic</title>

    <para>Apache's 
    <filename>mod_rewrite</filename>

    module lets you do some truly amazing things with URL rewriting. Here are
    a couple of examples of what you can do.</para>

    <orderedlist>
      <listitem>
        <para>Make it so if someone types 
        <computeroutput>http://www.foo.com/12345</computeroutput>

        , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try
        setting up your VirtualHost section for Bugzilla with a rule like
        this:</para>

        <programlisting>
<![CDATA[
<VirtualHost 12.34.56.78>
RewriteEngine On
RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
</VirtualHost>
]]>
        </programlisting>
      </listitem>

      <listitem>
        <para>There are many, many more things you can do with mod_rewrite.
        As time goes on, I will include many more in the Guide. For now,
        though, please refer to the mod_rewrite documentation at 
        <ulink url="http://www.apache.org">http://www.apache.org</ulink>
        </para>
      </listitem>
    </orderedlist>
  </section>

  <section id="setperl" xreflabel="The setperl.csh Utility">
    <title>The setperl.csh Utility</title>

    <para>You can use the "setperl.csh" utility to quickly and easily change
    the path to perl on all your Bugzilla files. This is a C-shell script; if
    you do not have "csh" or "tcsh" in the search path on your system, it
    will not work!</para>

    <procedure>
      <step>
        <para>Download the "setperl.csh" utility to your Bugzilla directory
        and make it executable.</para>

        <substeps>
          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>cd /your/path/to/bugzilla</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>wget -O setperl.csh
                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>chmod u+x setperl.csh</command>
              </computeroutput>
            </para>
          </step>
        </substeps>
      </step>

      <step>
        <para>Prepare (and fix) Bugzilla file permissions.</para>

        <substeps>
          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>chmod u+w *</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>chmod u+x duplicates.cgi</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>chmod a-x bug_status.html</command>
              </computeroutput>
            </para>
          </step>
        </substeps>
      </step>

      <step>
        <para>Run the script:</para>

        <para>
          <computeroutput>
            <prompt>bash#</prompt>

            <command>./setperl.csh /your/path/to/perl</command>
          </computeroutput>

          <example>
            <title>Using Setperl to set your perl path</title>

            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>./setperl.csh /usr/bin/perl</command>
              </computeroutput>
            </para>
          </example>
        </para>
      </step>
    </procedure>
  </section>

  <section id="cmdline">
    <title>Command-line Bugzilla Queries</title>

    <para>Users can query Bugzilla from the command line using this suite of
    utilities.</para>

    <para>The query.conf file contains the mapping from options to field
    names and comparison types. Quoted option names are "grepped" 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 "option"</para>

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

    <para>The columlist is taken from the COLUMNLIST environment variable.
    This is equivalent to the "Change Columns" option when you list bugs in
    buglist.cgi. If you have already used Bugzilla, use 
    <command>grep COLUMLIST ~/.netscape/cookies</command>

    to see your current COLUMNLIST setting.</para>

    <para>bugs is a simple shell script which calls buglist and extracts the
    bug numbers from the output. Adding the prefix
    "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" 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 says she has good results piping buglist output through 
    <command>w3m -T text/html -dump</command>
    </para>

    <procedure>
      <step>
        <para>Download three files:</para>

        <substeps>
          <step>
            <para>
              <computeroutput>
                <prompt>bash$</prompt>

                <command>wget -O query.conf
                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash$</prompt>

                <command>wget -O buglist
                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'</command>
              </computeroutput>
            </para>
          </step>

          <step>
            <para>
              <computeroutput>
                <prompt>bash#</prompt>

                <command>wget -O bugs
                'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command>
              </computeroutput>
            </para>
          </step>
        </substeps>
      </step>

      <step>
        <para>Make your utilities executable: 
        <computeroutput>
          <prompt>bash$</prompt>

          <command>chmod u+x buglist bugs</command>
        </computeroutput>
        </para>
      </step>
    </procedure>
  </section>

  <section id="quicksearch">
    <title>The Quicksearch Utility</title>

    <para>Quicksearch is a new, experimental feature of the 2.12 release. It
    consist of two Javascript files, "quicksearch.js" and "localconfig.js",
    and two documentation files, "quicksearch.html" and
    "quicksearchhack.html"</para>

    <para>The index.html page has been updated to include the QuickSearch
    text box.</para>

    <para>To take full advantage of the query power, the Bugzilla maintainer
    must edit "localconfig.js" according to the value sets used in the local
    installation.</para>

    <para>Currently, keywords must be hard-coded in localconfig.js. If they
    are not, keywords are not automatically recognized. This means, if
    localconfig.js is left unconfigured, that searching for a bug with the
    "foo" keyword will only find bugs with "foo" in the summary, status
    whiteboard, product or component name, but not those with the keyword
    "foo".</para>

    <para>Workarounds for Bugzilla users: 
    <simplelist>
      <member>search for '!foo' (this will find only bugs with the keyword
      "foo"</member>

      <member>search 'foo,!foo' (equivalent to 'foo OR keyword:foo')</member>
    </simplelist>
    </para>

    <para>When this tool is ported from client-side JavaScript to server-side
    Perl, the requirement for hard-coding keywords can be fixed. 
    <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=70907">This
    bug</ulink>

    has details.</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.sgml" "book" "chapter")
sgml-shorttag:t
sgml-tag-region-if-active:t
End:
-->