Chapter 20. Issue Tracking

Bug Reporting

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.

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:

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

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.

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:

            :do view {async}
            tmpfile = `tempfname()`
            :print >$tmpfile   use this information in the bug report:
            :print >>$tmpfile  program version: $VERSION
            :print >>$tmpfile  system type: ``
            :do view {remove} $tmpfile

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.

Bug Fixing

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.

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

            :do view {async}$USER

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.