==== NAME ====
Perlbug - PerlBug DataBase specification
==== DESCRIPTION ====
Bug tracking system, written in perl, using Mysql, probably running on
Linux with Apache.
For installation instructions see the INSTALL file.
==== SYNOPSIS ====
New bugs are created by mailing perlbug@perl.org or perlbug@perl.com
Said bug is entered in the database, and given a new bugid, the mail is
then forwarded to perl5-porters with the bugid in the subject line..
perl5-porters is continously tracked for relevant mails to attach to
said bug.
help@bugs.perl.org), command line(bugdb) and Tk (bugtk) frontends to
query and administrate the bugs.
Regular overviews are emailed to p5p, and outstanding bugs are mailed to
active admins for their attention.
All modules have perldocs embedded, to browse at your leisure.
perl -e "print Perlbug::Interface::Cmd->new()->object('bug')->read('19870502.007')->format('A')"
==== COMPATIBILITY ====
web
Netscape is the standard benchmark, w3m is used to ensure frame/noframe
compatibility, which should cover the worst cases. I don't have MSIE to
check against, but feedback on this is welcome if there are problems.
database
Currently only Mysql is supported on UNIX(linux), though Oracle looms
continously, and will be implemented when I get round to it.
==== FEATURES ====
Written in perl
Robust, with test suites:
All tests successful.
Files=28, Tests=162, 148 wallclock secs (59.27 cusr + 2.61 csys = 61.88 CPU)
Under RCS
Documented (in perldoc -> do what I say _and_ what I do :-)
Freely available sourcecode and data.
Integrated with perlbug
It has a simple (single config file) installation.
Site configurable email newbug recognition and forwarding.
Site configurable scanning of email bodies -> categorisation of reports.
Standard installation*: perl Makefile.PL; make; make test; make install.
Multiple interfaces (take your pick):
Web -> search, browse and destroy interface
Tron -> target and mailing list slurper/forwarder
Email 1 -> subject: oriented search, report and admin
Email 2 -> to: oriented report and admin
Command line -> for local db (similar to email)
Tk -> search, browse the db
More than 5 different formatting types for all discrete objects are supported
across all outputs for both public and administrative, (which will become
configurable), interfaces for:
bugs, messages, patches, notes, tests, users, groups, etc.
Differential user/admin help for all formats.
Several utility scripts (see below)
Accepts target mail addresses (and thereby sets category etc.) and forwards to
appropriate mailing list/s.
Watches various mailing list for replies to existing bugs to slurp,
checking subject and reply-to, message-ids, etc.
Defense mechanisms against loops, spam, and other entertaining factors.
Ignores previously seen message-ids, non-relevant (spam) mail.
Test targets to email interfaces (dumps header -> originator)
Email interface handles any of the following To lines (and more):
close_<bugid>_@bugs.perl.org -> bug admin
busy_win32_install_fatal_<bugid>@bugs.perl.org -> admin
propose_close_<bugid>_@bugs.perl.org -> bug admin proposal
note_<bugid>_@bugs.perl.org -> assign note
patch_<version>_<bugid>_<changeid>@bugs.perl.org -> assign a patch
register_me@bugs.perl.org -> admin registration request
admins@bugs.perl.org -> admin mail forward
help@bugs.perl.org -> :-)
And the following (not very cryptic) Subject lines:
-h
-b <bugid>+
-s subject_search
-H -d2 -l -A close <bugid>+ lib -g patch -e some\@one.net
-g pa cl wi -m77 812 1 21 -b <bugid>+ -B <bugid>+ -o -l -d2 -a clo inst <bugid>+ -fA
etc... (see the email help docs for more info)
Auto database dump, email of overview and bugid->admin assignation
Patches can be emailed in -> auto close of bug
Notes can be assigned from any interface to any bug
Tests can be assigned to any bug
Non-admin emails -> converted to proposals -> mailed to active admins
Cc: list (and admins) are optionally auto-notified of any status changes to bugs
Relationships between bugs (parent-child) are assignable.
Retrieval of database via email.
Logging of all activities, admin history tracking.
Graphical display of overview (admins, categories, severity, osname, status).
==== SCRIPTS ====
The perlbugtron contains the following scripts:
bugcgi
The web interface
bugcron
The regular cron job interface to backups, weekly notifications etc.
bugdb
The command line interface
bugfix
A command line utility to fix duff data in the bug database
bughist
A parser of directories of archived mail (treated as per tron.pl).
bugmail
A query and administrative email front end, examining both Subject:
and To: line for instructions. Accepts mail for bugdb@perl.org and
*@bugs.perl.org.
bugtk
The Tk interface
bugtron
Tracks mailing lists, relying on header information to identify new
bugs and replies to existing ones. Accepts mail for perlbug@perl.org
and perlbug@perl.com and relevant target mailing lists.
==== CLASSES ====
For those that are interested the Perlbug application module hierarchy
goes something like this:
(ISA) Config Do TM (HASA) Log Format
| | |
------------- --- ------
|
(ISA) Base
Interface
|
---------------------------------- -
| | |
Cmd | |
----------- | |
| | | |
| Email Web Tk
----------------------- ---------- --- ---
| | | | | | | |
bugcron bugdb bughist bugfix bugtron bugmail bugcgi bugtk
While the Perlbug Objects themselves hierarchy looks a bit like this:
(ISA) Object (CAN) Format and may have (HASA) Relation(s)
------ ------ --------
|
Address Bug Group Message Note Patch Test User Status ...
------- --- ----- ------- ---- ----- ---- ---- ------
Since moving ``status'', ``osname'', etc. over to being objects in their
own right, and dedicated tables thereof, which may relate to each other
in most any combination, you may notice we have a 'riesen menge' (a lot)
of objects, some of which at first glimpse may seem overkill. On this
point, I can only agree. However my defense/argument for this
implementation is that I have tried to keep it as ``clean'' as possible,
and that meant being somewhat (ob|sub)jectively pedantic now and then -
so there you have it :-)
Anyone actually looking into this code will find the Objects are fairly
clean (I hope), where the Interfaces are not. That's on the TODO list,
now that the background is firm.
==== DEVELOPMENT ====
Anyone considering contributing (and some already have), code to this
project would do well to (of course :-) RTFM. I've tried to keep the
docs as up to date as possible.
A developer of any part of this system, who wishes to use the existing
code base, is encouraged to approach it in the following manner:
Initially get a ``Perlbug::Base'' object which holds all the
configuration data for the application, and from here all other
``Perlbug::Object::*'''s are accessible via the ``object()'' call: see
the Perlbug::Base::object manpage.
Alternatively start with a ``Perlbug::Interface::*'' which ``ISA''
``Perlbug::Base'' in any case.
Once the appropriate object has been retrieved, it may be used via a
``class'' method, or as a particular instance, where the object has been
initialised.
For example using Perlbug::Base or
Perlbug::Interface::(Cmd|Email|Web)->new...
my $o_base = Perlbug::Base->new(); # get an interface
my $o_bug = $o_base->object('bug'); # the appropriate object
print "All bugids: ".join(', ', $o_bug->ids(); # class method
$o_bug->read('19870502.007'); # instantiate
print "Bug data: \n".$o_bug->format('A'); # instance method
The object knows what relationships it has, so ask it:
print "Relations: ".join(', ', $o_bug->relations); # address, note, user...
And so on:
print map { $_->key.' ids: '.$o_bug->rel_ids } $o_bug->relations;
There should be no need to directly query the db with hard-wired SQL,
everything should be do-able through the supplied object interfaces, (if
this is not the case, speak - I/we should fix it :-).
Note that in the entire application there is only a single place where
it has proved necessary to refer directly to a database tablename and
this is in the configuration filename. All other data is extrapolated
from the objects themselves in a more or less predictable manner.
The output is largely controlled via formats supplied as default in the
Perlbug::Format manpage, or where this is not sufficient, in each object
class itself. See ``Perlbug::Format::FORMAT_[ahlxi]'' etc. Note the
trailing letter defining the type of format required. It would be
simple, for example, to add an XML format using the supplied placeholder
in the Perlbug::Format_x manpage
The format system will at some point shortly migrate into a table of
templates that will then be applicable to any object by any registered
user in any context... Which will hopefully satisfy _most_ people _most_
of the time ;-)
If something is missing, tell me, or write the code to do it and
contribute.
==== COMMANDS ====
A couple of useful commands:
Send mail into the db:
cat some_mail | ~/scripts/bugtron
Slurp up to 33 archived mails, recursively, with feedback:
~/scripts/bughist -v -i /path/to/email/archives -m 33 -r
Send a query to the db via the email interface:
cat my_admin_email | ~/scripts/bugmail
Or interact with it via the command line:
~/scripts/bugdb
Send active admins unclosed bugs and an overview to master_list(p5p),
dump current database for reference/backup:
crontab -e 3 5 * * 1 ~/scripts/bugcron
A couple of useful(?) command-lines:
perl -MPerlbug::Bug -e 'print map { "$_\n" } Perlbug::Bug->new->ids("subject=\"bug\"")'
perl -MPerlbug::Group -e 'print Perlbug::Group->new->_read("configure")->format("h")'
==== BUGS ====
What bugs ?-)
You have a few choices, (with the output of 'make test TEST_VERBOSE=1'):
1. Mail perlbug@perl.org which will assign a bugid.
2. Mail the author (richard@perl.org or perlbug@rfi.net) directly.
3. Mail admins@bugs.perl.org which will Cc: to all active admins.
4. Subscribe to bugmongers@perl.org (a mailing list for those interested in perl bugs).
5. Or try perl5-porters@perl.org (p5p) for a more generic solution.
==== TODO ====
Oracle support
Comprehensive test suite (though 138+ isn't that bad for a start?)
==== AUTHOR ====
Richard Foley richard@perl.org perlbug@rfi.net (c) 1999 2000 2001
==== CONTRIBUTORS ====
The system was given a kick start by Christopher Masto, NetMonger
Communications <chris@netmonger.net>.
It's development has been overseen originally by Chip Salzenburg
<chip@perlsupport.com> and later by Nathan Torkington <gnat@frii.com>
(who was also responsible for the original perl bug tracking system).
Bjoern Hansen <ask@valueclick.com>.
There have been numerous suggestions, feedback and even patches from
various people, in particular (in purely alphabetical order):
Merijn Brand <h.m.brand@hccnet.nl> (Tk support)
Alan Burlison <Alan.Burlison@uk.sun.com>
Mike Guy <mjtg@cam.ac.uk>
Jarkko Hietaniemi <jhi@iki.fi>
Andreas Koenig <andreas.koenig@anima.de>
Richard Soderberg <rs@oregonnet.com>
Hugo van der Sanden <hv@crypt0.demon.co.uk>
Robert Spier <rspier@pobox.com> (adminfaq)
and many others
Special thanks to Tom Phoenix <rootbeer@redcat.com>.
==== COPYRIGHT ====
Copyright (c) 1999 2000 2001 Richard Foley richard@rfi.net. All rights
reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.