NAME

Mailhelp - help for the mail interface to the Bug Database


DESCRIPTION

Help for users of the mail interfaces, searching, commands, etc.

There are two mail programs, this document describes the bugmail interface.

bugmail

The user/admin interface to the db, this program is described here.

bugtron

The mailing list and email target slurper script

See Perlbug for more details on how this little fellow operates.


BUGMAIL

target

Typically, to interact with the db, an email is sent to one of the following addresses:

        To: bugdb@perl.org 
        
or 
        
        To: bugdb@bugs.per.org

This is configurable by the bug system administrator.

commands

Are sent on the Subject: (or To see below) line of the email, for example, to retrieve the help pages;

        Subject: -h
note

All switches and arguments to the email interface are expected to be separated by a space

        Subject: -s define -e copy@me.too 


USAGE

A couple of examples which are equivalent. The first form uses the /subject line approach, while the second uses the /To header line:

subject

        To: bugdb@perl.org

        Subject: -a close patch <bugid1> <bugid2>
        
to

        To: close_patch_<bugid1>_<bugid2>@bugs.perl.org

        Subject: irrelevant subject line


SUBJECT

The subject line may be used to interact with the database, in which case the To line is used merely to target this interface.


SEARCH

There are several different ways of searching the db, by object id or, in the case of bugs, by group/category/flag/etc.

search

Return these bugs:

        Subject: -b <bugid> [<bugid>]*

Return bugs in this group/category, additional are 'and'ed together:

        Subject: -g patch [install]*

Note that a unique shortened form is acceptable (equivalent):

        Subject: -g pat [ins]*

Upper case letters usually expand upon or reverse the effect of the lowercase command in some way. So a B will return the messages with the particular bug, help (h) may be increased (this file) with H) and so on.

Return the database structure for inspection:

        Subject: -q

SQL query (must start with SELECT). Note this is the only command which looks in the body for it's content:

        Subject: -g pat [ins]*
        Body:   
                SELECT * FROM pb_group WHERE name LIKE 'pa%'

Format the results like this, where the argument is described in Perlbug::Format, common options are:

        a(ascii - default), A(ascii-extended), l(ascii-list), h(html), H (more data in your HTML)

        Subject: -f h


ADMINISTRATION

Administration commands are a and A where the latter also returns the admistrated object for your information (just wraps a call to b <bugid>)

Note the specific order of these commands are not relevant, the string is instead scanned for appropriate values. This means you should be careful when specifying shortened versions of say 'status=closed and group=cludge', where you should not use '-a cl', rather use '-a clo' or as appropriate.

To become an administrator see /register below.

example Subject: -a close build 19990606.002 19990606.003

which translates (more or less) to:

        UPDATE db_bug
        SET status = 'closed' 
                AND group = 'build' 
        WHERE bugid IN ('19990606.002', '19990606.003')
        
=item shortcuts

are still acceptable

    Subject: -A onh pa hi aix 19990606.002 19990606.003

which translates (more or less) to:

        UPDATE db_bug
        SET status = 'onhold' 
                AND group = 'patch' 
                AND severity = 'high' 
                AND osname = AIX
        WHERE bugid IN ('19990606.002', '19990606.003')
    
=item to

You may also use the (To\|Cc): addresses (described below) to similar effect:

        To: clo_19990606.002_install@bugs.perl.org
more

Below is an example email which retrieves bugs: '19990606.002', having first closed it and assigned various other flags, and then returns the shorter help message, along with all open bugs and those which are still open and under the patch group, then returns the results with a copy to the extra email address:

    To: bugdb@bugs.perl.org

    Subject: -h -A close 19990606.003 -j op pa -e me@too.net


TO

The To line may also be used to interact with the database, in which case the Subject line is completely ignored.

There are user and administrator functions:


USER

The administration interface is only available to registered administrators of the database, to become an administrator:

register

by sending an email, where ME is your preferred userid:

        To: register_ME@bugs.perl.org
propose

a change in a bug status without becoming an administrator with:

        To: propose_close_<bugid>_macos@bugs.perl.org
admins

which are active can be mailed with this:

        To: admins@bugs.perl.org
        Subject: hello from me...
help

may be retrieved by:

        To: help@bugs.perl.org
spec

The system specification may be retrieved by:

        To: spec@bugs.perl.org
overview

The overview

        To: overview@bugs.perl.org


ADMINISTRATOR

The following administration functions are also supported:

Note that in the cases where a (note|patch|test) is being assigned, this keyword should be at the beginning of the To: line, otherwise the formatting is largely irrelevant.

That is (in a slightly contrived example);

        To: close_patch_<bugid>@... 

                will close the bug and assign the bug to the patch group

        To: patch_close_<bugid>@...' 
        
        will instead take this email as a patch and assign it to this bug
flags

may be assigned to a bug like this:

        To: close_irix_<bugid1>_<bugid2>_configure@bugs.perl.org

short forms are still acceptable:

        To: clo_ir_<bugid1>_<bugid2>_con@bugs.perl.org
notes

may be assigned to a bug:

        To: note_<bugid>@bugs.perl.org
patches

may be assigned to a bug:

        To: patch_<bugid>@bugs.perl.org
tests

may be assigned to a bug:

        To: patch_<bugid>@bugs.perl.org

Patches may be assigned to one or more bugs, and should have a changeID assigned. The bug/s (if given) will be marked as closed and the patch entered into the database, with the changeid and version number if parseable:

        To: patch_<bugid>_<changeid>_<versionno>@bugs.perl.org

Formatting of IDs in this case IS relevant:

        Bugid      =~ /\d{8}\.\d{3}/   -> 19990321.007, 20130313.013 
        Changeid   =~ /\d+/            -> 3821, 21, 9182732
        Versionno  =~ /\d+\.[\d+\.]+/  -> 5.6.0, 5.6.0.32
nocc

if you don't want to Cc: everyone else, add 'nocc' to your commands:

        To: patch_<bugid>_nocc@bugs.perl.org

        To: busy_<bugid>_nocc_hpux@bugs.perl.org


AUTHOR

Richard Foley <richard@rfi.net> 2000 2001