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 the section on "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 the section on "/subject" line approach, while
    the second uses the the section on "/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 the
        Perlbug::Format manpage, 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 the section on "/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')
        
    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')
    
    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:

            To: busy_win32_library_regex<bugid>@... 

            To: abandoned_aix_<bugid>@... 

	Etc.

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

    That is:

            To: patch_close<bugid>@... 

            	will create a new patch and close this bug

            To: close_patch_<bugid>@... 

            	will close the bug and will ignore the 'patch'

	With one exception (can't have everything :)

            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 (minimum 3 character) forms are still acceptable:

                To: clo_iri_<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

