Apport bug patterns for Ubuntu
==============================

Purpose
-------

Sometimes a high-visibility crash bug or package installation failure causes a
tremendous amount of duplicate bugs filed through apport, because
Launchpad is not insistant enough to guide people to already existing
similar bugs.

Thus Apport supports patterns which can be matched against a crash
report, and directly guide the user to the existing bug instead of
filing a new one first.

Most useful fields are certainly Stacktrace, Package/Dependencies (for
checking particular versions), and ProcCmdline, but in general you can
match any field that seems useful.

To avoid inventing a new file format and to be able to extend the
functionality in the future (e. g. other operators than just regexp
matching) the bug patterns are stored as XML files, named after the
binary package, currently on [1].

Syntax
------
The general syntax is:

    root element := <patterns>
    patterns := <pattern url="http://bug.url"> *
    pattern := <re key="report_key">regular expression*</re> +

For example:

    <?xml version="1.0"?>
    <patterns>
        <pattern url="https://launchpad.net/bugs/1">
            <re key="Foo">ba.*r</re>
        </pattern>
        <pattern url="https://launchpad.net/bugs/2">
            <re key="Foo">write_(hello|goodbye)</re>
            <re key="Package">^\S* 1-2$</re> <!-- test for a particular version -->
        </pattern>
    </patterns>

The existing bug patterns should provide sufficient examples to
understand real-world applications.

Files
-----
In order to avoid downloading all bug pattern files to the user, the
pattern files are named after package names. Apport determines the affected
binary package name, and looks for a file packagename.xml. If that
does not exists, it falls back to sourcepackagename.xml. Other pattern
files are *not* considered.

Testing
-------
To test that apport is seeing your modified or new bug pattern, you can run
"./test-local" on a .crash file or a Launchpad bug number. This will match the
report against all local bug patterns and give the result. Once this is
working, commit and push them.

Rollout
-------
Commits to the Launchpad branch are rolled out to
http://people.canonical.com/~pitti/bugpatterns (where apport will look
for them) every 15 minutes.

Please double and triple check new patterns here. Badly written
patterns can easily lead to unifying *all* possible crashes to one
existing bug!