# $Id: webhelp,v 1.4 2001/12/03 10:39:21 richardf Exp $

=head1 NAME 

Webhelp - help for the web interface


=head1 DESCRIPTION

Help for users of the web interface, searching, objects and their fields, etc.

=cut


=head1 SEARCH 

=over 4

=item mask 

The search mask/fields, have no pre-selected entries, click B<query> and an indiscriminate 
list of all the bugs in the database will be returned.  

Filterering is achieved by selecting options from the popup menus, or entering data in the text fields, as described below.

Once an item is returned for viewing, links to it's constituent parts may be followed.

The following describe fields not described under L</OBJECTS> below.

=item admin

List of active administrators who are registered against 1 or more bugs.

=item and_or

Boolean switch to decide whether or not to B<AND> or to B<OR> the query fields together, in the creation of the SQL search query.

=item asc_desc

Determine whether to return records found in B<ASCENDING> or B<DESCENDING> order.

=item dates

Restrict records created on or after the selected date.

Note that you can also construct a query to retrieve the bugs since this Christmas by using something of the form:

	http://bugs.perl.org/perlbug/perlbug.cgi?req=date&date=20001225

Usage of a valid B<8> figure date is recommended, otherwise you're on your own :-)


=item format

Determine the display format of the records found.  This for example, means you can still get an ascii list (for applying a script against, perhaps), even while using the web frontend which naturally has the default return format in B<HTML> form.

=item message_id

The contents of the actual Message-Id: field belonging to each bug or reply.

=item restrict

Restrict the number of found records to the given number.  Also divides the remainder up into similarly sized chunks for convenient browsing thereafter.

=item messages

Restrict returns to bugs which have this many messages/replies in the thread.

=item show_sql

Display the B<SQL> executed.  This may help to pinpoint problems where searches are not returning expected results.

=item wildcards

All text fields are searched using the SQL B<LIKE> operator. 
L</bugid>, L</noteid>, L</patchid>, L</testid>, L</version>, L</change> and B</fixed> fields are used as seen, 
that is, if a wildcard is not provided, one will not be used.

Conversly B<subject>, B<body> and B<source address> fields have C<%> pre-placed around the search query by default.

What this means is that entering C<20001122.>, in the bugid field, will probably not return much, but C<20001122.%>' might.
Of course a complete bugid could be entered on it's own eg: C<20001122.003>
Whereas entering only B<strict> in the subject field will still use C<%strict%> during the search.

The available SQL wildcards: B<any single character> C<_> and B<none or more characters> C<%> are allowed in all fields. 
Note also that for convenience(?), an asterisk(C<*>) will be simply mapped to the sql wildcard C<%>'.

N.B. It can be a good idea to use the L</show_sql> switch to display what's being searched for. 

=item retrieval

Bugs are initially returned in either B<list> or B<block> format, with an optional trimming mechanism which defaults to 25.
At the base of the page is a list of all the other bugs found during the query, sectioned into similarly managable portions.
The list format is designed for quickly moving around a list of bugs, while the block format is aimed at finding all information relating to said bug, without having to hop around.

L<DESCRIPTION>

=back

=cut


=head1 SUBMIT

=over 4

The submit buttons available are as follows:

=item Query

submit the query to the database interface

=item Reset

reset the form to the default values


=head2 administrative

For admins only:

=item Update

update the selected record/s shown

=item Nocc

same as update, but don't send any email notifications of the changes

=item Select

select all shown record/s

=item Unselect

deselect all shown record/s

=item Admin

switch from the B<noadmin> view to the B<admin> view

=item Noadmin

switch from the B<admin> view to the B<noadmin> view

=item Delete

delete the selected shown record/s

=back

=cut


=head1 OBJECTS

Certain fields are common to all objects:

=over 4

=item created

The date this record was created in the database.

=item modified

The date this record was in some way modified.

=item history 

The list of all modifications to each item, and who submitted them.

=back

=cut


L<DESCRIPTION>

=head1 BUG

The main potato:

=over 4

=item bugid

The internally generated bugid.

=item subject

The subject line of the original report.

=item source_addr

Usually the B<From:> address of the original report.

=item body

The body of the original message which generated the bug report.

During a web search, the bodies of all messages in the database will be inspected, unless the boolean L</and_or> switch B<AND> is selected whereby the search criteria is narrowed down.

=item status

The status of the bug, with the following options:

    abandoned   -	no longer worked on

    busy        -	currently being looked at by an administrator

    closed      -	considered fixed

    duplicate   -	a report erroneously filed a second time

    incapable	-	considered not doable

    ok          -	a 'build reported OK:' report, (not the same as closed)

    notok         -	opposite of B<ok>

    onhold      -	undecided as to whether this is a bug or not

    open        -	undealt with, needing attention



=item category

The category of the bug has the following options:


    bounce      -	report had invalid format, common with spam mail

    core        -	central functionality affected

    docs        -	not a code bug, a docs bug (or typo)

    install     -	bug in the installation procedure

    library     -	not a central routine, rather a library or module bug

    notabug     -	at all, could be misread instructions or even spam

    patch       -	this fixed another bug

    unknown     -	first port of call, bug usually assigned to another valid group	

    utilities   -	a utility function misbehaved


=item severity

The severity of the bug has the following options, in descending order or B<severity>:

    fatal       -	top priority!

    high        -	non-fatal, but has to be fixed quickly

    medium      -	should be fixed soon

    low         -	would be good to fix when time permits

    wishlist    -	would be nice to have someone look at this sometime

    none        -	a bit like 'wishlist' but more so


=item osname 

The name of the operating system this report was generated on:

Many differing values possible.

	
	aix, dec, hpux, irix, linux, macos, next, os2, solaris, vms, winnt, etc.

	...	
	

=item project

The Project, which currently uses the

	perl4		- once 

	perl5		- and [now]

	perl6		- future

	...


=item VERSIONING 

There are several field relating to versions, patches, changes which may at first be somewhat inter-related.


=item version

The version against which this report was first noticed/generated.

Typically has one of the following forms:

	5

	5.0053

	5.00.5.3

	5.6

	5.6.0

	5.7.1

	...


=item fixed

The version in which this bug was fixed, same format as L</version> above.


=item change

The changeID of the target source for the fix.  this is an external reference about which we know very little.

Typically has one of the following forms:
	
	5

	5810

	0053

	...


=item history

History of administrative operations against this bug, changes of status/category, etc..

=item cc

List of email addresses for this bug.  Will contain the source address, any adminitrator who has modified the bug record, and any people who have been on the B<Cc:> list of any of the messages assigned to this bug.

=item messagids

The internal-ids of messages belonging to this bug (replies).

Not to be confused with the externally supplied L</message_id>'s of each email.

=item parent

The L</bugid> of any other bug to which this bug may B<belong>.

=item child

The L</bugid> of any other bug which belongs to this bug.

=back

L<DESCRIPTION>

=cut


=head1 NOTE

An administrator can assign a note to a bug when he/she modifies it.

=over 4

=item note

The body of the note.

=item noteid

The internally generated noteid.

=back

L<DESCRIPTION>

=cut


=head1 PATCH

A bug may be fixed by a B<patch>, this can be assigned along with a L</changeid>.

Bear in mind the difference between the internally generated B</patchid> and the externally offered B</changeid>.

=over 4

=item patch

The body of the patch.

=item patchid

The internally generated patchid.

=back

L<DESCRIPTION>

=cut


=head1 TEST

A test may be assigned to a bug, if the test succeeds the bug may be regarded as fixed.

=over 4

=item test

The body of the test.

=item testid

The internally generated testid.

=back

L<DESCRIPTION>

=cut



=head1 AUTHOR

Richard Foley <richard@rfi.net> 2001

=cut


