# $Id: webhelp,v 1.7 2002/01/11 13:51:06 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 form
The search form has no pre-selected entries, click B<query> and an indiscriminate
list of all the bugs in the database will be returned.
Filtering 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>
=item admin
List of active administrators who are registered against 1 or more bugs.
=item boolean
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 'LIKE' operator. The
B<LIKE> operator allows the symbol B<%> to match any sequence of
characters, like '.*' in Perl regexes, and the symbol '_' to
match any single character, like '.' in Perl regexes. Perlbug
also maps '*' to '%', so '*' will also match any sequence of
characters. All other characters in text boxes are taken literally.
The B<Subject>, B<Body> and B<Source address> fields perform
substring searches. That is they are surrounded by B<%> internally.
For example, entering I<filehandle> in the B<Subject> box searches for
any subject that contains the string I<filehandle>.
The B<Bug ID>, B<Version>, B<Fixed in>, B<Message-ID>, B<Note ID>,
B<Patch ID>, and B<Test ID>, fields are used exactly as entered.
Entering '20001122' in the B<Bug ID> field will not match
anything, because 20001122 is not the ID of any bug. To find all
the bugs that were submitted on date 20001122, use '20001122.%'.
Note also that for convenience(?), an asterisk(C<*>) will be simply mapped to the sql wildcard C<%>'.
It may be instructive to try a few searches with the B<Show SQL>
option enabled. This will display the SQL query that the engine
is using to search the database.
See also L<"object_search">
=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.
=head2 Searching for objects
=item object_search
Where searching for each object, (not using the prime bug search mechanism), individually, each field is treated as searchable using the B<wildcard> mechanism described above.
The following fields are treated specially:
=item created
Date field - use a format of B<YYYY-MM--DD> eg; 1987-05-02
=item modified
As per L<"created"> above
=item optional
The Optional field is used by administrators to enter a command line string for defining relationships, similar to a typical B<bugdb> subject or To|Cc line.
For example to assign B<group>, B<status>, B<admin> info etc. to a B<bug>:
C<aix linux win98 macos closed richardf docs>
Or a bugid, or two, to a patch:
C<19870502.007 19870502.091>
See B<mailhelp> for more info
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 (data updates are possible)
=item Noadmin
switch from the B<admin> view to the B<noadmin> view (less clutter)
=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.
=item transfer
Certain objects may be transferred from one type to another, for example where a plain L</message> should be reclassified as, for example, a L</patch> or a L</test>.
Additional data may always be entered in the L</optional> field
=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 group
The group (or 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/group, 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
Amendments by Mark-Jason Dominus <mjd@plover.com>
=cut