NAME

Webhelp - help for the web interface

DESCRIPTION

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

SEARCH

form

The search form has no pre-selected entries, click 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 "OBJECTS"

admin

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

boolean

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

asc_desc

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

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 8 figure date is recommended, otherwise you're on your own :-)

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 HTML form.

message_id

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

restrict

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

messages

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

show_sql

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

wildcards

All text fields are searched using the SQL 'LIKE' operator. The LIKE operator allows the symbol % 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 Subject, Body and Source address fields perform substring searches. That is they are surrounded by % internally. For example, entering filehandle in the Subject box searches for any subject that contains the string filehandle.

The Bug ID, Version, Fixed in, Message-ID, Note ID, Patch ID, and Test ID, fields are used exactly as entered. Entering '20001122' in the 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(*) will be simply mapped to the sql wildcard %'.

It may be instructive to try a few searches with the Show SQL option enabled. This will display the SQL query that the engine is using to search the database.

See also "object_search"

retrieval

Bugs are initially returned in either list or 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.

Searching for objects

object_search

Where searching for each object, (not using the prime bug search mechanism), individually, each field is treated as searchable using the wildcard mechanism described above.

The following fields are treated specially:

created

Date field - use a format of YYYY-MM--DD eg; 1987-05-02

modified

As per "created" above

optional

The Optional field is used by administrators to enter a command line string for defining relationships, similar to a typical bugdb subject or To|Cc line.

For example to assign group, status, admin info etc. to a bug:

aix linux win98 macos closed richardf docs

Or a bugid, or two, to a patch:

19870502.007 19870502.091

See mailhelp for more info

"DESCRIPTION"

SUBMIT

The submit buttons available are as follows:

Query

submit the query to the database interface

Reset

reset the form to the default values

administrative

For admins only:

Update

update the selected record/s shown

Nocc

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

Select

select all shown record/s

Unselect

deselect all shown record/s

Admin

switch from the noadmin view to the admin view (data updates are possible)

Noadmin

switch from the admin view to the noadmin view (less clutter)

Delete

delete the selected shown record/s

OBJECTS

Certain fields are common to all objects:

created

The date this record was created in the database.

modified

The date this record was in some way modified.

history

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

transfer

Certain objects may be transferred from one type to another, for example where a plain "message" should be reclassified as, for example, a "patch" or a "test".

Additional data may always be entered in the "optional" field

BUG

The main potato:

bugid

The internally generated bugid.

subject

The subject line of the original report.

source_addr

Usually the From: address of the original report.

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 "and_or" switch AND is selected whereby the search criteria is narrowed down.

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

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

severity

The severity of the bug has the following options, in descending order or 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

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.

        ...     
        

project

The Project, which currently uses the

        perl4           - once 

        perl5           - and [now]

        perl6           - future

        ...

VERSIONING

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

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

        ...

fixed

The version in which this bug was fixed, same format as "version" above.

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

        ...

history

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

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 Cc: list of any of the messages assigned to this bug.

messagids

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

Not to be confused with the externally supplied "message_id"'s of each email.

parent

The "bugid" of any other bug to which this bug may belong.

child

The "bugid" of any other bug which belongs to this bug.

DESCRIPTION

NOTE

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

note

The body of the note.

noteid

The internally generated noteid.

DESCRIPTION

PATCH

A bug may be fixed by a patch, this can be assigned along with a "changeid".

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

patch

The body of the patch.

patchid

The internally generated patchid.

DESCRIPTION

TEST

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

test

The body of the test.

testid

The internally generated testid.

DESCRIPTION

AUTHOR

Richard Foley <richard@rfi.net> 2001

Amendments by Mark-Jason Dominus <mjd@plover.com>

cpanm Perlbug

perl -MCPAN -e shell
install Perlbug