                                  Bugz
                                  ====                                
Version 1.15 (28 Apr 2002)

Introduction
------------
Bugz is an application to aid in reporting bugs to us. The idea is that
developers and testers don't contact us with bug reports, or comments,
because it is difficult to do so. Bugz makes this job easier, in principle,
as well as providing a bug-tracking framework from our end.

Note that the first time you run Bugz, you will have to enter some details
about yourself such that you can be contacted.


How to use Bugz
---------------
Bugz supports three modes of operation :

  * Reporting bugs from supplied description files
    Description files will be supplied with beta applications to aid the
    debugging process.
    Dragging the description file to the iconbar icon will open a bug report
    window.

  * Reporting bugs with running modules
    From the iconbar menu, select the module you wish to report bugs in, or
    comment on. The bug report window will open.

  * Reporting bugs with running applications
    From the iconbar menu, select the application you wish to report bugs
    in, or comment on. The bug report window will open.

To see how Bugz works with modules, select one from the menu.
To see how Bugz works with description files, use the iconbar menu option
"Bugz bug!".
To see how Bugz works with applications, select one from the menu.

As well as this, it also provides a quick means of displaying your machine
details. This is not meant to be comprehensive, as these details will be
passed along in the report email, but should provide enough information
to narrow the problems.


Bug report window
-----------------
The bug report window has three sections, separated by dividing lines :

  * Information
    Contains information about the thing being reported on. There may be
    a 'More info' section containing further details about the component.

  * Bug reporting and comments
    This has the section name, followed by three buttons :
      Info - display information about this section
      Comment - submit a comment about this section
      Bug report - submit a bug report about this section
      Worked? - select the most appropriate state if you wish

  * Sending
    Allows you to send the email

In addition, you can save the details you have entered as a text file (for
your own records, or if you have problems with the automatic sending) from
the menu.

The editing method is through the use of external edits. These are not
supported by Edit. I very strongly recommend you get Zap or StrongEd (or any
other External Edit compatible editor) if this is a problem. When a section
has been filled in, its button will change colour. You can re-edit entries as
often as you wish.

The display windows are exportable from their menus, support selection and
clipboard models. There is no need to cite sections of these display windows
as they will automatically be included in report emails.


Possible problems
-----------------
It is possible that Bugz itself may contain bugs. This sort of thing
happens, unfortunately. I wish it wasn't so. Really I do. But then you'd not
have that smiling blue face on the iconbar because everything would be
perfect. But there you go. Anyhow, I digress...

There is the possibility that GMail may not be able to send emails out. Once
you've got Bugz installed, you might like to try submitting a report (using
'Bugz bug') to say that Bugz worked (or didn't, as the case may be!). When
you have submitted that, check your outgoing mail queue (in whatever mail
package you use). It should contain your message, from your email address,
to bugz@movspclr.co.uk. If this is NOT the case, then contact us manually,
providing the email that it would have sent and any details you can of the
internet suite you use and whatever other information might be pertinent.
I'm reasonably confident that GMail works 99% of the time.

Known problems:
  Voyager - There have been reports that GMail doesn't work with this. Let
            me know if this is what you use.
  InetSuite using IMAP - Apparently this doesn't send the queued messages
            (personally I think that's wrong, because it should at least
            check the queue, otherwise nobody else can queue messages).

Possible solutions:
  Select the 'Mail...' option and configure GMail to use a gateway for
  sending emails. If you have a direct internet connection, or a dedicated
  mail server this is probably the best solution.
  Alternatively, select 'append to file' and when you have completed a group
  of reports, email these to the intended recipient.
  Or, select 'Save' from the bugz report window menu and send the email it
  saves using your normal email application.


Privacy and confidentiality
---------------------------
Because your details and comments are being transmitted via email in an
unsecure fashion, you should not include any information within them which
might be considered private and non-disclosable. In particular, you may wish
to omit including your geographic address. Treat the information you submit
as you would any other email.


Security
--------
Bugz description files have the ability to include executable code. If you
are unsure about using description files with embedded code, do not use
them. The embedded code is visible and is written in BASIC. Contact the
supplier of the Bugz description file if you are unsure of the details.


Icon
----
The icon is a very hastily knocked up little bug. There's a much nicer icon
around and about, but licencing restrictions prevent its use. <sigh>


Contact & Copyright
-------------------
Bugz is  Justin Fletcher. Contact bugz@movspclr.co.uk for support (note the
z on the end). It is not an example of how to write robust, reliable code.
It is /very/ quickly thrown together from components that were lying about.


Distribution
------------
If you wish to use Bugz with your product for testing, then you should 
feel free to do so. Very few distribution restrictions are placed upon Bugz.
You may use it as you see fit. You may distribute it with any freely
available, or commercial package. The only restrictions are that you may not
modify the core Bugz application, that you may not sell Bugz on its own (!),
you may not increase the cost of a product based on it including the Bugz
application and you may not cite the inclusion of Bugz as a feature of any
product. Please remember to set the [*Mail] field, otherwise emails will be
sent to RISCOS Ltd, rather than to you.

I would prefer it if I were contacted about the use of Bugz with
applications such that I can give advice on new features, and/or provide
the latest version.


Warranty
--------
Bugz is supplied with NO warranty. Its suitability for the purpose for which
it was intended is not guarenteed. If it blows itself up then it's because
it's badly written. LET ME KNOW :-) I'll fix it as, after all, that's the
whole point of Bugz.


GMail
-----
The GMail absolute supplied is Justin Fletcher. It may be distributed
with the Bugz application and may not be separated from it. For further
details, please contact me.


Description file format
-----------------------
This section is mostly for my own use, but you may find it interesting. If
you happen to have no life <smile>.

Description files must start with :

  # This is a Bugz description file

They are sectioned, delimited by [<section name>] blocks. Section names
starting with a * are reserved for system use.

[*Title]
This section contains a single line describing the title of the description
file as appears in the window title and iconbar menu.

[*Info]
This section contains the entire informational section for the top of the
report window. Entries are of the form <name>: <value>. Any number of entries
may be given. Suggestions for things to include here: 
  Program: The program (application/module/package)
  Distribution: What distribution applies to it (Public, Developers, specific
    individuals)
  Version: Version of the program
  Release: What this release is actually for (eg 'menu reorganisation',
    'release candidate #', 'experimental x, y and z')
  Part: Part number in database

It is strongly recommended that the Bugz description be included in any
checked in version, such that it can be re-used for a later release.

[*Mail]
This section contains the report email address. Non-RISCOS Ltd Bugz users
should use this field to supply their email addresses. If you DON'T supply
this field, it will default to a RISCOS Ltd bug report address.

[*Cat]
This section contains information about the component as a whole. It may
contain history information, a summary of what has changed, who the
component is distributed to and other misc information.

[*Modules]
This section contains module names which you wish details to be included for
when exporting the data. This is most useful if you wish to track which module
versions are being used with a particular application.

[*Show]
This section contains system variable names in their standard wildcarded form
which will be included when exporting the data. This may be useful to monitor
the state of the users machine.

[*Task]
This section contains BASIC statements to provide information about the
system you are running under where necessary. The task will run in a
taskwindow and will have complete access to the entire machine. Be aware of
this when writing scripts. The output will be captured and appended to the
report. This might be used to read configuration files and provide the
information for the developer, or to extract other information from the
system.

[<entry>]
This section contains a description of the entry, as it will appear in the
Info window for each section. You should describe the changes that have taken
place in the area it describes, as well as things to watch out for and that
should be tested.


In addition, no line in the file should exceed 255 characters. It is
recommended that all lines be limited to 80 characters to aid readability.
By default, the display windows use the system font. You should be aware
that using a different font may be possible in future, and take care when
indenting text or drawing ASCII diagrams.


Module service names
--------------------
Module service names are decoded from the Resource.Services file. This aids
readability. Entries are of the form :

  <name><spaces><service number>

where <service number> can be any BASIC EVAL-able string. Don't go mad
though. <name> must not contain spaces.


Integrating with your own applications
--------------------------------------
Bugz would like to support as many applications as possible, to aid general
quality of bug reporting and to provide a 'standard' interface to the user
and/or programmer. Initially, it is expected that developers use Bugz to
help in their development of their products and to aid RISCOS Ltd in finding
problems in its. It's a joint effort thing, developers get Bugz and a
reasonable reporting system, and everyone gets back useful reports. That's
the plan anyhow. If you have any suggestions or problems with Bugz, please
let me know.

To facilitate this, Bugz includes a message protocol to allow it to
communicate with other applications.


Message Bugz_Query (&53B80)

+20     type of query
          0   Bugz file request
        other Reserved
+24...  reserved

This message is sent by Bugz, or other Bug reporting or interested application
to gain information about the application. It may be extended at some future
date to include email addresses, version strings or other application specific
debugging information. Applications should identify the type of the query and
only respond if it understands it.

Type 0: Bugz file request (aka 'Do you have a Bugz file ?')
        This message is sent to ask for the filename of a Bugz report for an
        application. Applications should reply with Bugz_BugzFile if they
        provide on, or ignore the message if not.


Message Bugz_BugzFile (&53B81)

+20...  Filename of file to open

This message is sent by a Bugz aware program to ask Bugz to open a report
window on the Bugz file named in the block. Bugz will acknowledge the message,
therefore if the message bounces you may wish to either notify the user or
run Bugz manually. Bugz is identified with <Bugz$Dir> being set to the
application directory. This message is the usual response to Bugz file requests (Bugz_Query type 0).


Contact
-------
Any comments, queries, donations or bug reports can be sent to Justin
Fletcher at :

E-Mail : Gerph@innocent.com
URL    : http://www.movspclr.co.uk/
Tel    : (07979) 606416
         (01842) 813979

Snail Mail :
    Justin Fletcher
    "Galadriel"
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


ChangeLog
=========

Changes are listed 'newest first' so that it's easy to find where things
have changed. This is further complicated by the fact that I've changed over
to using CVS to maintain the changes. Consequently, there are two 'styles'
of the ChangeLog - those I wrote manually, and those which are logged
directly from CVS.


Log file for Bugz
=================

------------------------------------------------------------------------
    Version 1.15 16:28:03 28/4/2002
------------------------------------------------------------------------
$Log: VersionLog,v $
Revision 1.7  2002/04/28 15:29:25  justin
Summary:
  Fix for podules failing to enumerate.
Detail:
  * The flag comparison I was doing was using two different variables and
    so gave inconsistent results with podules appearing and disappearing
    seemingly at random.
Admin:
  Fix found by Alex Macfarlane Smith, and tested by him.
Tag:
  Bugz-1_15

------------------------------------------------------------------------
    Version 1.14 16:08:44 28/4/2002
------------------------------------------------------------------------
Revision 1.6  2002/04/28 15:11:32  justin
Summary:
  Fix for DataSave moaning at Wimp$Scrap.
  Moved Close to a button, rather than window furniture.
  Corrected template use of Developer details.
Detail:
  * Where Wimp$Scrap was used, the DataSave would fail to notice that it
    was a full path and thus complain that it hadn't been specified
    properly. We now canonicalise the filename first.
  * The other icons are buttons, so we use a button for close too.
  * Developer details was still on the template, even though it wasn't on
    the output. We now say 'User details',
Admin:
  Tested by myself, Alex Macfarlane Smith and Chris Williams.
Tag:
  Bugz-1_14

------------------------------------------------------------------------
    Version 1.13 15:17:36 28/4/2002
------------------------------------------------------------------------
Revision 1.5  2002/04/28 14:21:16  justin
Summary:
  Added support for *Task.
  Changed 'Developer' field to 'User' in the output.
Detail:
  * We now support executable code in the Bugz application. This will be
    run when the file is mailed. It's scary, but it works.
    If the *Task section is not used, it doesn't actually affect the
    operation significantly.
  * The 'Developer details' was really a misnomer; it should say 'User
    details'. So it now does.
Admin:
  Tested locally and seems pretty reliable.
  Tested with Oregeno test script for extracting configuration
  information.
Tag:
  Bugz-1_13

------------------------------------------------------------------------
    Version 1.12 00:24:42 25/10/2001
------------------------------------------------------------------------
Revision 1.4  2001/10/24 23:33:49  justin
Summary:
  Added 'clear' button to report window.
  Fix for archive.
Detail:
  * As well as clearing entries when you send them (you don't want to
    report the same thing multiple times), you can also clear the entire
    text from a button.
  * Archiving to choices was completely ineffectual, 'cos the pointer
    was not set to the end of the file (thus overwriting the file every
    time). Now we do so and the archive actually works.
Admin:
  Tested locally and seems to work.
Tag:
  Bugz-1_12

------------------------------------------------------------------------
    Version 1.11 22:14:19 24/10/2001
------------------------------------------------------------------------
Revision 1.3  2001/10/24 21:15:18  justin
Summary:
  Corrected release details in the BugzBug file.
Detail:
  * The release details still said it was a developer only release, not a
    public release.
Admin:
  No code change; just a fix to the report form.
Tag:
  Bugz-1_11

------------------------------------------------------------------------
    Version 1.10 21:45:56 24/10/2001
------------------------------------------------------------------------
Revision 1.2  2001/10/24 20:49:21  justin
Summary:
  Initial import of the Bugz reporting application.
Detail:
  * Bugz provides a means for users to report bugs in a manner that is
    structured, provides information on the system in use, and is
    reasonably simple to use.
  * This version has no reference to ROL, except that it was done for
    them; it will be on public release.
Admin:
  Tested locally and seems to work rather nicely.
  Still no support for importing files to attach.
  Could use taskwindow to control output from a test application for
  more complex information on a particular product; this will need
  thinking about.
Tag:
  Bugz-1_10

------------------------------------------------------------------------
    Version 1.09 21:09:26 24/10/2001
------------------------------------------------------------------------
Revision 1.1  2001/10/24 20:09:26  justin
Created VersionNum file

=============================================================================
Switch to CVS for logging history of changes
=============================================================================

Version 1.09 : 09 Sep 2001
               Fix for broken drag handler which would end up selecting text
               forever under certain circumstances (Ian Jeffray)

Version 1.08 : 29 Oct 2000
               Added messages to allow people to write their Bugz responsive 
               applications. Updated documentation to reflect this.

Version 1.07 : 04 May 2000
               Corrected order of min and max parameters.

Version 1.06 : 22 Mar 2000
               Mails now sent through taskwindows.
               Consequently, added mail debugging system.
               And as a bonus, we get direct email sending (-a direct to
                 GMail) and store to file.
               Corrected bug which meant that reports were never being
                 sent (Tom Hughes, many thanks!)

Version 1.05 : 20 Mar 2000
               Added keyboard handler for details window.
               Corrected Machine support library to not enumerate modules
               due to possible fault in podule loader which causes lock ups
               on return [q.v. Matthew's machine]
               Released to developers via website.

Version 1.04 :19 Mar 2000
               Applications added.
               Added Machine information section.
               Reorganised internals of display handling to cope with more
               generic writing.
               *Mail configuration
               Additional configuration file

Version 1.03 : 19 Mar 2000
               Added Modules and Show sections.
               'Worked?' entry added.
               Window width now updates, along with informational icons.
               Services handler added.

Version 1.02 :18 Mar 2000
               Added modules support
               Window tidied up; dividers added
               Icon created for application
               !Help file written, with documentation of description file
               format.

Version 1.01 : 17 Mar 2000
               Window positioning corrected
               Added details window
               Added launching of GMail

Version 1.00 : 16 Mar 2000
               First version written
               File reading and window creation
               Saving of file as text
