## page was renamed from BugHelper/doc/WritingClueFiles
||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents(2)>>||

= Writing clue files =

As described in the [[BugHelper/doc|introductory documentation]] you can create simple cluefiles with {{{bugxml -a}}}. For more complex search criteria you need to edit the XML files as described here.

The basic clue file created with {{{bugxml}}} has this header:

{{{
<?xml version="1.0"?>
<clues version="0.1">
}}}

and contains a single clue on the form:

{{{
  <clue>
    <contains>
      <op>crash</op>
    </contains>
    <info>A CRASHER BUG</info>
  </clue>
}}}

and finally closes with:

{{{
</clues>
}}}

You can add a long list of clues with the {{{<clues> </clues>}}} tag, each with a list of search strings within {{{<op> </op>}}} tags. Each clue also requires an {{{<info>}}} tag to hold a brief description of the bug type. If the clue describes a duplicate then this description would typically be the title of the original bug.

== Optional elements ==

'''Declaring duplicates:''' If you create a clue that searches for duplicates of bug #X you can note that specifically in the clue file. Bughelper will then refrain from listing this bug in these searches. 

{{{
  <dontlist>
    <bug>48355</bug>
  </dontlist>
}}}

'''Inheritance:''' Clues can be inherited from other clue files. ''totem'' can for example inherit clues from ''gnome'' and ''gstreamer'':
{{{
    <inherits>
        <inherit>gnome</inherit>
        <inherit>gstreamer</inherit>
    </inherits>
}}}

'''Logical operators:''' You can also combine the logical opperators AND, OR and NOT to create detailed bug searches. Example:

{{{
  <clue>
    <contains>
      <and>
        <op>apples</op>
          <or>
            <op>oranges</op>
            <op>pears</op>
          </or>
          <bin=not op>bananas</op>
      </and>
    </contains>
    <info>Bug description must contain 'apples' AND either 'oranges' OR 'pears'. It may not contain 'bananas'.</info>
  </clue>
}}}

== Examples ==

Real-life examples from {{{packages/ubiquity.info}}}:

{{{
<clues>
    <clue>
        <dontlist>
            <bug>48355</bug>
        </dontlist>
        <contains>
           <and>
                <op>IOError: [Errno 28] No space left on device</op>
                <op>copy_all</op>
                <op bin="not">stepPartAdvanced</op>
	       </and>
        </contains>
        <info>This is a dupe of 48355 if the system partitions are big enough</info>
    </clue>
    <clue>
        <dontlist>
            <bug>48856</bug>
        </dontlist>
        <contains>
	     <and>
                <op>AttributeError: 'NoneType' object has no attribute 'stdin'</op>
                <op>print >>self.gparted_subp.stdin, "apply"</op>
             </and>
        </contains>
        <info>This is a duplicate of 48856, which was fixed in 1.0.13 and 1.1.1</info>
    </clue>
</clues>
}}}

= Sharing clue files =

The real benefits of bughelper become apparent when bug triagers and developers share their knowledge of the through common clue files.

=== Preliminaries ===

 1. Get a Launchpad Account at https://launchpad.net/
 1. Add your SSH keys to https://launchpad.net/people/+me/+editsshkeys
 1. Install `bzr`, it's a nice and handy tool. We use it for developing BugHelper: {{{
sudo apt-get install bzr}}} (if you installed bughelper on feisty, bzr will already be installed.
 1. edit `~/.bazaar/bazaar.conf` and add something along the lines of:{{{
[DEFAULT]
email=Daniel Holbach <daniel.holbach@ubuntu.com>}}} so that your commit will be identified.
 1. Create a directory for your local {{{bzr}}} branches{{{
mkdir ~/bzr; cd ~/bzr}}}

=== Get the latest copy of bughelper-data ===

 1. To start sharing clue files you must first check out the latest a copy of the shared repository as a local {{{bzr}}} branch:{{{
bzr checkout lp:~bugsquad/bughelper-data/main bughelper-data}}}
  This is actually the same repository that {{{bughelper}}} updates its clue files from normally, but with this format you can make changes and upload them again with bzr.
 1. Generate default bughelper config:{{{
bughelper --gen-config}}}
 1. Edit `~/.bughelper/config` to contain the path to bughelper-data (you just checked out) in the `Local-Packages-Dir:` line.

=== Editing and uploading ===

Add a new clue with {{{bugxml -a}}} or simply edit the {{{.info}}} for a given package. From the {{{bughelper-data}}} directory, run 

{{{
 bzr unknowns
}}} 

to see if your clue file is listed as a new file. If so, you first have to add it with

{{{
 bzr add <filename>
}}}

If you have simply edited an existing file you can go directly to the commit step:

{{{
 bzr commit -m "added a totem clue"
}}}

Optionally, you can edit the `Local-Packages-Dir:` line of `~/.bughelper/config` to contain the path to the bughelper-data {{{bzr}}} directory. The directory you created with the {{{bzr}}} then becomes you local working directory. Make changes there as you experiment with new clues and commit the ones that work well.

----
Go back to '''[[BugHelper/doc]]'''.<<BR>>
CategoryBugSquad<<BR>>
CategoryBugHelper