<!--  vim: set sw=2 sts=2 et ft=docbk:

  Part of the A-A-P recipe executive: Issue Tracking

  Copyright (C) 2002-2003 Stichting NLnet Labs
  Permission to copy and use this file is specified in the file COPYING.
  If this file is missing you can find it here: http://www.a-a-p.org/COPYING

-->

<bridgehead>Bug Reporting</bridgehead>

<para>
A recipe used to install an application should offer the "report" target.
This is the standard way for a user to report a problem.  The recipe should
then help the user with reporting a problem as much as possible.
</para>

<para>
An example is to send the developer an e-mail.  Commands in the recipe are
used to put useful information in the message, so that the user only has to
fill in his specific problem.  Example:
</para>

<programlisting>
        report:
            tmpfile = `tempfname()`
            :syseval foobar --version | :assign Version
            :print >$tmpfile  Using foobar version: $Version
            :print >>$tmpfile system type: `os.name`
            @if os.name == "posix":
                :print >>$tmpfile system details: `os.uname()`
            :print >>$tmpfile
            :print >>$tmpfile State your problem here
            :do email {subject = 'problem in FOOBAR'}
                            {to = bugs@foobar.org}
                            {edit}
                            {remove}
                            $tmpfile
</programlisting>

<para>
  The "foobar --version" command is used to obtain the actual version of the
  "foobar" program being used.
  Replace "foobar" with the actual name of your program.
</para>

<para>
When a web form is to be filled in, give the user hints about what information
to fill in certain fields and start a browser on the right location.  Example:
</para>

<programlisting>
        report:
            :do view {async} http://www.foo.org/bugreport/
            tmpfile = `tempfname()`
            :print >$tmpfile   use this information in the bug report:
            :print >>$tmpfile  program version: $VERSION
            :print >>$tmpfile  system type: `os.name`
            :do view {remove} $tmpfile
</programlisting>

<para>
  Obviously this is a bit primitive, the user has to copy text from the text
  viewer to the browser.
  Try using a better method, filling fields of the form directly if you can.
</para>


<bridgehead>Bug Fixing</bridgehead>

<para>
Once a bug has been fixed, the developer needs to update the related bug
report.  The "tracker" target is the standard way for a developer to get to
the place where the status of the bug report can be changed.
</para>

<para>
Since trackers work in many different ways the recipe has to specify the
commands.  Example:
</para>

<programlisting>
        tracker:
            :do view {async} http://www.foo.org/tracker?assigned_to=$USER
</programlisting>

<para>
This is very primitive.  The developer still has to locate the bug report and
change the status and add remarks.  The above example at least lists the bug
reports for the current user.
</para>
