mne
OPF$MO0x\.g x1x
-
o Œ Pƌb` wVn}pB/&ZP^Pт^~N04x]콜QgO#
cOPY~QQqS( i[ /d, n OWI-Įk C#hzlQR1ф d.q 솰 r"-_oTqq&2x㮎1 F' ' 0.1*D l?B &,3m>,,w%QR QhJXÚN/.4N^C2xJ &2J'
u#l*0'CSqT0*Q60yquІ]N 4 'e2w2;s8rg425Ől32)P@Iy
8_53NIT#\Lu|G/N;sV372/&0v-0-)s`n&3oZ:U&/)Ў35,ˍ0MP p p
PDRS%P ) *O$Anl2T,=F GSQ RpT##]m{*0Yq˚ 4 I!
`Se* ЗδJk)Gwp9TKK O#Ŕ#4
JkLٰOtOJUP5&n6'tOӴTPM0R
(;p0'
J'՞*RqP5(ԫB/<+OqTD70T1@yӜ@QVKIqUYs![5KlTX iRWdL[Y4ZR\;A?<+64MTO*x^.Un DMWq^O,nJ LXv^S4BCuFElV=v.t$/Uma3`mR-}Y,HllVd7)b']Z_3VewUz1]F16a6JIVӦbV]ÖΫGQ1vQQ6QN ik0*>#:e'C#926n:\fOnnH4I5Auq$SUs0l&d_ hpwvls\wnwfR&6j+rUqnk!}VfL'i85m]+gARoڊYdŚjj.Q{-/3|]Dwv8&q
r44wm n<-7zL
3o&u%o7˼7w63;ӒP;7\I@At/ .-xRmpyⶄVv64Uwua` zu=7;7|}YqEUo9X4 7Y۳/nRᤰq
m5i?[X n ǥk5D'@5J`5GXhqt roundup-admin -
administrate roundup trackers roundup-admin
[options] <command>
<arguments> -i
instance home Specify the issue tracker
"home directory" to administer -u
user[:password] The user and password to use
for commands (partial implemention, see Security Notes
below). -h Print help text. -d Print full designators (e.g. issue1) not just id numbers
(1). -c When outputting lists of data, comma-separate them. Same
as -S ",". -S string When outputting lists of data,
separate items with given string. -s When outputting lists of data, space-separate them. Same
as -S " ". -P pragma=value Set a pragma on the command
line. Multiple -P options can be specified to set
multiple pragmas. -V Be verbose when importing data. -v Report Roundup and Python versions and quit. Only one of
-s, -c or -S can be specified. If no command
is provided on the command line, roundup-admin will enter an
interactive mode. More details about these commands are
available using the help command. A designator is
a classname and a nodeid concatenated, eg. bug1, user10,
.... Roundup-admin
takes a number of commands: help prints help (same as
-h) help
<subcommand> Print command-specific help help all Print available help for all
commands. commit Commit changes made to the database during an
interactive session. The changes
made during an interactive session are not automatically
written to the database - they must be committed using this
command. One-off
commands on the command-line are automatically committed if
they are successful. See also rollback. create classname
property=value ... This creates a new entry of the
given class using the property name=value arguments provided
on the command line after the "create"
command. display
designator[,designator]* This lists the properties and
their associated values for the given node. The pragma
display_header can be used to add a header between
designators that includes the active/retired status of the
item. export
[[-]class[,class]] export_dir Export the database to
colon-separated-value files. To exclude the files (e.g. for
the msg or file class), use the exporttables command. Optionally
limit the export to just the named classes or exclude the
named classes, if the 1st argument starts with
’-’. This action
exports the current data from the database into
colon-separated-value files that are placed in the nominated
destination directory. exporttables
[[-]class[,class]] export_dir Export the database to
colon-separated-value files, excluding the files below
$TRACKER_HOME/db/files/ (which can be archived separately).
To include the files, use the export command. filter classname
propname=value ... Find the nodes of the given
class with a given property value. Multiple values can be
specified by separating them with commas. If property is a
string, all values must match. I.E. it’s an matches.
I.E. an ’or’ operation. find classname
propname=value ... Find the nodes of the given
class with a given link property value. genconfig
<filename> Generate a new tracker config
file (ini style) with default values in
<filename>. Note that this does not preserve
any settings from the current tracker. Use updateconfig for
that. get property
designator[,designator]* Get the given property of one
or more designator(s). Retrieves the
property value of the nodes specified by the
designators. history designator
[skipquiet] [raw] Lists the journal entries
viewable by the user for the node identified by the
designator. If skipquiet is added, journal entries for quiet
properties are not shown. Without the raw option a more
human readable output format is used. import
import_dir Import a database from the
directory containing CSV files, two per class to import. The imported
nodes will have the same nodeid as defined in the import
file, thus replacing any existing content. The new nodes
are added to the existing database - if you want to create a
new database using the imported data, then create a new
database (or, tediously, retire all the old data). See also
export. importtables
import_dir Import a database from the
directory containing CSV files, two per class to import. The imported
nodes will have the same nodeid as defined in the import
file, thus replacing any existing content. This only
imports database tables. It does not import files/message
content. It is used to import data exported by exporttables.
See also exporttables. initialise
[adminpw] Initialise a new Roundup
tracker. The
administrator details will be set at this step. install [template
[backend [key=val[,key=val]]]] Install a new roundup
tracker. The command
will prompt for the tracker home directory (if not supplied
through TRACKER_HOME or the -i option). The template and
backend may be specified on the command-line as arguments,
in that order. Command line
arguments following the backend allows you to pass initial
values for config options. For example, passing
"web_http_auth=no,rdbms_user=dinsdale" will
override defaults for options http_auth in section [web] and
user in section [rdbms]. Please be careful to not use spaces
in this argument! (Enclose whole argument in quotes if you
need spaces in option value). The initialise
command must be called after this command in order to
initialise the tracker’s database. You may edit the
tracker’s initial database contents before running
that command by editing the tracker’s dbinit.py module
init() function. See also
initopts help. list classname
[property] Lists all instances of the
given class. If the property is not specified, the
"label" property is used. The label property is
tried in order: the key, "name", "title"
and then the first property, alphabetically. With -c,
-S or -s print a list of item id’s if no
property specified. If property specified, print list of
that property for every class instance. The pragma
show_retired can be used to print only retired items
or to print retired and active items. The default is to
print only active items. migrate Update a tracker’s
database to be compatible with the Roundup codebase. You should run
the "migrate" command for your tracker once
you’ve installed the latest codebase. Do this before
you use the web, command-line or mail interface and before
any users access the tracker. This command
will respond with either "Tracker updated" (if
you’ve not previously run it on an RDBMS backend) or
"No migration action required" (if you have run
it, or have used another interface to the tracker, or
possibly because you are using anydbm). It’s safe
to run this even if it’s not required, so just get
into the habit. pack period |
date Remove journal entries older
than a period of time specified or before a certain
date. perftest [mode]
[arguments]* Run performance test. For
example test the effect of changing password hashing
parameters. pragma
setting=value|list Set internal settings to a
value. E.G. pragma
verbose=True will turn on
verbose mode for roundup-admin. pragma list will show all
settings and their current values. If verbose is enabled
hidden settings and descriptions will be shown. reindex
[classname|classname:#-#|designator]* This will re-generate the search indexes
for a tracker. You can specify a specific item (or items)
(e.g. issue23), range(s) of items (e.g. issue:1-1000),
class(es) (e.g. issue) or reindex all items in the database
if no arguments are supplied. restore
designator[,designator]* Restore the retired node
specified by designator. The given nodes
will become available for users again. retire
designator[,designator]* This action indicates that a
particular node is not to be retrieved by the list or find
commands, and its key value may be re-used. See also
restore. rollback Undo all changes that are
pending commit to the database. The changes
made during an interactive session are not automatically
written to the database - they must be committed manually.
This command undoes all those changes, so a commit
immediately after would make no changes to the database. security [Role
name] Display the Permissions
available to one or all Roles. set items
property=value property=value ... Set the given properties of one
or more items(s). The items are
specified as a class or as a comma-separated list of item
designators (ie
"designator[,designator,...]"). This command
sets the properties to the values for all designators given.
If the value is missing (ie. "property=") then the
property is un-set. If the property is a multilink, you
specify the linked ids for the multilink as comma-separated
numbers (ie "1,2,3"). specification
classname Show the properties for a
classname. templates
[trace_search]] Lists the names, location and
description of all known templates. table classname
[property[,property]*] Lists all instances of the
given class. If the properties are not specified, all
properties are displayed. By default, the column widths are
the width of the largest value. The pragma
show_retired can be used to print only retired items
or to print retired and active items. The default is to
print only active items. updateconfig
<filename> This is used when updating
software. It merges the config.ini from the tracker
with new settings from the new software. The merged/updated
config file is written to <filename>. Commands may be
abbreviated as long as the abbreviation matches only one
command, e.g. l == li == lis == list. You can edit
the command line and interact with history in
roundup-admin’s interactive mode. On Linux like
systems, GNU Readline is required. On Mac’s libedit
can be used as well. On Windows pyreadline3 is required.
See: https://docs.python.org/3/library/readline.html for
details on readline. Roundup-admin
will save the history between roundup-admin sessions. The
commands are saved to the .roundup_admin_history file
in the user’s home directory. You can set the pragma
history_length on the roundup-admin command line to
change the amount of available and stored history for the
session. If you are
using GNU readline, you can persistently change the history
size by adding: set history-size 100 to the init file
.roundup_admin_rlrc located in the user’s home
directory. Mac users using
libedit should be able to persistently save history and set
the history size by adding history size 100. Users of
pyreadline3 can use: history_length(100). The -u
user setting does not currently operate like a user
logging in via the web. The user running roundup-admin must
have read access to the tracker home directory. As a result
the user has access to the files and the database info
contained in config.ini. Using -u
user sets the actor/user parameter in the journal.
Changes that are made are attributed to that user. The
password is ignored if provided. Any existing username has
full access to the data just like the admin user. This is an
area for further development so that roundup-admin could be
used with sudo to provide secure command line access to a
tracker. ROUNDUP_LOGIN Provides an alternate way to
set the user. roundup-admin
-h roundup-demo(1),
roundup-mailgw(1), roundup-server(1) This manpage
was written by Bastian Kleineidam <calvin@debian.org>
for the Debian distribution of roundup. The main author
of roundup is Richard Jones
<richard@users.sourceforge.net>. roundup-demo -
create a roundup "demo" tracker and launch its web
interface roundup_demo
[-h] [-b BIND_ADDRESS] [-b
{anydbm,mysql,sqlite,postgresql}]
[-t {minimal,jinja2,classic,responsive,devel}] [-p
PORT] [-P URLPORT] [-V]
[directory] [backend]
[nuke] directory The home
directory for the new demo tracker. (*) backend Choose backend
database. Depricated, use -b. nuke Create a fresh demo tracker (deleting the existing one
if any). E.G. roundup-demo -b sqlite -t
classic ./mytracker nuke -h, --help Show the help
message and exit -B BIND_ADDRESS,
--bind_address BIND_ADDRESS Choose address
for server to listen at. Use 0.0.0.0 to bind to all
addreses. Default: 127.0.0.1. -b
{anydbm,mysql,sqlite,postgresql},
--backend_db Choose backend
database. Default: sqlite. Available backends are subject to
availability on your system. -t
{minimal,jinja2,classic,responsive,devel},
--template Use specified
template when building tracker. (*) -h HOSTNAME,
--hostname HOSTNAME Set the
hostname used in the URL. This does not make the server
listen at the hostname. Use the hostname with -B to
listen on that IP address. -p PORT,
--port PORT Listen at this
port. Default: search for open port starting at 8917. -P URLPORT,
--urlport URLPORT When using
docker this option passes the docker external port to the
demo instance. If using docker ... -p 9090:8917 ...
this should be set to -P 9090. Default: as selected
by --port. -V, --version Show
program’s version number and exit If items marked
with (*) are missing, they will be asked for interactively
when setting up the tracker. This command
creates a fresh demo tracker for you to experiment with. The
email features of Roundup will be turned off (so the nosy
feature won’t send email). It does this by removing
the nosyreaction.py module from the demo
tracker’s detectors directory. If you wish to
send email to promote the tracker to production, you will
need to copy nosyreaction.py from the default tracker
templates directory. The templates command from
roundup-admin(1) can help you locate a replacement. If you wish,
you may modify the demo tracker by editing its configuration
files and HTML templates. See the customisation
manual for information about how to do that. Once
you’ve fiddled with the demo tracker, you may use it
as a template for creating your real, live tracker. Simply
run the roundup-admin command to install the tracker
from inside the demo tracker home directory, and it will be
listed as an available template for installation. No data
will be copied over. roundup-admin(1),
roundup-mailgw(1), roundup-server(1) This manpage
was written by Richard Jones and extensively modified by
John Rouillard <rouilj@users.sourceforge.net>. roundup-mailgw
- mail gateway for roundup roundup-mailgw
[-h|--help] [-v] [--version] [-c|--default-class
default_class] [-S|--set-value [class.]field=value]
[-O|--oauth-directory directory] [-T|--oauth-token-endpoint
endpoint-url] [instance_home] [mail source
[specification]] -v
--version Print version and exit. -c --default-class
hyperdb class specify the default tracker
class - one of issue (the default), msg, file, user etc.
Overrides the tracker’s mailgw default_class
setting. -S --set-value
[class.]property=value[;property=value] specify the values to set on
the class specified as prefix using the same format as the
Subject line property manipulations. If the class prefix is
left out it defaults to msg. Can also be specified
with --set-value (and abbreviated to
--set). -O --oauth-directory
directory Only with OAuth authentication
specify the directory containing additional OAuth
credentials. -T
--oauth-token-endpoint url Token endpoint URL of your
cloud provider, only used with OAuth. The roundup
mail gateway may be called in one of four ways: • without arguments which will use the env var
ROUNDUP_INSTANCE, • with an instance_home as the only argument, • with both an instance_home and a mail spool file,
or • with both an instance home and a mail source type and
its specification. PIPE
UNIX
mailbox In all of the
following mail source types, the username and password can
be stored in a ~/.netrc file. If done so, only the server
name needs to be specified on the command-line. The username
and/or password will be prompted for if not supplied on the
command-line or in ~/.netrc. POP POPS
APOP
IMAP
IMAPS
IMAPS_CRAM
IMAPS_OAUTH
ROUNDUP_INSTANCE
If your msg
class has a messsagetype property you can set up aliases to
receive the different types of messages. Setting up an alias
in your MTA Using: tracker:
|/tools/roundup/bin/roundup-mailgw (the lines are
split for readability. In the alias file they will be on the
same line). Replace /tools/roundup/bin/roundup-mailgw by
your path to the roundup-mailgw. This creates the email
alias "tracker". All messages sent to it have
their messagetype property set to "reply - to
all". The roundup tracker instance is located at
/var/roundup/sysadmin. A comment alias
would receive emails at tracker_comment with: tracker_comment:
|/tools/roundup/bin/roundup-mailgw which would be
a technical message. These messages can trigger different
workflows based on the messagetype. Both examples
use the default class specified in the tracker’s
config.ini (usually the issue class). You can also
set properties directly on the issue class. If your
tracker’s issue has a "private" property
that limits who can view an issue and its messages: security:
|/tools/roundup/bin/roundup-mailgw would set the
private property on a issue to restrict visiblity and mark
the issue as a security topic using a keyword. Both examples
use the default class specified in the tracker’s
config.ini (usually the issue class). roundup-admin(1),
roundup-demo(1), roundup-server(1) This manpage
was written by Bastian Kleineidam <calvin@debian.org>
for the Debian distribution of roundup. The main author
of roundup is Richard Jones
<richard@users.sourceforge.net>. Updates by John
Rouillard <rouilj@users.sourceforge.net> and Ralf
Schlatterbeck <rsc@runtux.com>. roundup-server
- start roundup web server roundup-server
[options] [name=tracker home]* -C
file or --config file Use options read from the
configuration file (see below). -n hostname Sets the host name or IP
address to listen on. Default is localhost (127.0.0.1). Use
0.0.0.0 to listen on all interfaces on the system. -p port Sets the port to listen on
(default: 8080). -d PIDfile Run the server in the
background and write the server’s PID to the file
indicated by PIDfile. The -l (or -L) option must be
specified if -d is used. -D Run the server in the foreground even if -d is used. -t
fork|thread|debug|none Control multi-process mode.
debug and none are always available. If an
invalid mode is specified the server starts in none
(also called single) mode. Default fork. -m
max_children Set the maximum number of child
processes (servers). This value may need to be increased on
a heavily loaded site. Default 40. -l file Sets a filename to log to
(instead of stdout). This is required if the -d option is
used. -P If a reverse proxy is used in front of the
roundup-server, the server will log the ip address of the
proxy, not the client browser. Using -P logs the left most
entry in the X-Forwarded-For http header as the IP address
of the client. This address will be logged or resolved to a
hostname (with -N) and a ’+’ character
will be appended. -P should only be used when the
roundup server is accessible only from trusted proxy hosts.
See:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
for details and warnings about using the X-Forwarded-For
header. -L Have the server log using the Python logger with key
roundup.http. -i file Sets a filename to use as a
template for generating the tracker index page. The variable
"trackers" is available to the template and is a
dict of all configured trackers. If you connect to the root
of the server (without a tracker name), the default index
page is shown. Using -i allows you to customize the
index page. -I
header1[,header2,...] Pass the header(s) and their
values to the backend. This allow-list of header variables
can be used by custom code in the tracker or with a
tracker’s http_auth_header configuration option
to allows a front end server to authenticate a user and pass
the user identity to roundup. -s Enables use of SSL. In most cases, you will want to run
a real web server (Apache, Nginx) as a proxy to
roundup-server running without SSL. The real web server can
filter/rate limit/firewall requests to roundup-server. -e file Sets a filename containing the
PEM file to use for SSL. The PEM file must include both the
private key and certificate with appropriate header/trailer
markers: -----BEGIN
PRIVATE KEY----- and -----BEGIN
CERTIFICATE----- If no file is
specified, a temporary self-signed certificate will be
used. -N Log client machine names instead of IP addresses (much
slower). -V HTTPVER By default roundup-server uses
HTTP/1.1 to enable keepalives for faster response. HTTPVER
can be set to HTTP/1.0 to disable keepalives. -u UID Runs the Roundup web server as this UID. -g GID Runs the Roundup web server as this GID. -v or
--version Print version and exit. -h or --help Print help and exit. --save-config Create configuration file and
exit. The old config.ini will be saved to config.bak. Note
that this command doesn’t attempt to load or verify an
existing config.ini. Running this in a tracker home
directory will move the existing config.ini to config.bak
and replace it with the roundup-server’s config.ini.
This will make the tracker in the directory fail to start
until the original config.ini is restored. name=tracker
home Sets the tracker home(s) to
use. The name variable is how the tracker is
identified in the URL (it’s the first part of the URL
path). The tracker home variable is the directory
that was identified when you did "roundup-admin
init". You may specify any number of these name=home
pairs on the command-line. For convenience, you may edit the
TRACKER_HOMES variable in the roundup-server file instead.
Make sure the name part doesn’t include any url-unsafe
characters like spaces, as these confuse the cookie handling
in browsers like IE. If you connect
to the root directory (I.E. you do not include the
name component in the URL, the server will display an
index page of trackers served by roundup-server if more than
one tracker is defined. If only one tracker is defined it
will redirect to the tracker. roundup-server
-p 9000 bugs=/var/tracker reqs=/home/roundup/group1 Start the server on port
9000 serving two trackers; one under /bugs and
one under /reqs. If you connect
to the server at the root level (http://host:9000/) it will
display a list of the available trackers. See the
"admin_guide" in the Roundup "doc"
directory. roundup-admin(1),
roundup-demo(1), roundup-mailgw(1) This manpage
was written by Bastian Kleineidam <calvin@debian.org>
for the Debian distribution of roundup. The main author
of roundup is Richard Jones
<richard@users.sourceforge.net>.
We propose an issue-tracking system called
Roundup, which will manage a number of issues
(with properties such as "description", "priority", and so on)
and provide the ability to
(a) submit new issues,
(b) find and edit existing issues,
and
(c) discuss issues with other participants.
The system will facilitate communication
among the participants by managing discussions and
notifying interested parties when issues are edited.
This design draws on experience from
an existing
implementation which we will refer to
as "the Roundup prototype".
The graphical interface we have in mind will resemble
the main display of the prototype.
A typical software project requires the management of
many tasks, usually distributed among several collaborators.
In fact, any project team
could use a tool for sorting out and discussing all the
relevant issues. A common approach is to set up some kind
of "to-do" list that people can share.
However, to address the overall problem we need much more
than just a shared to-do list; we need to
manage a growing body of knowledge and experience to help a
team collaborate effectively on a project. The issue-tracking
tool becomes a nexus for communication: the Grand Central
Station of the group intelligence.
The primary focus of this design is to help
developers work together well, not to provide a customer
service interface to the developers. This is not to say that
the design is to be made unsuitable for customers to use.
Rather, it is assumed that many of the same qualities
that are good for supporting development (see below)
are also good for non-developers using the system.
Additional niceties
for providing a safe or simplified interface to clients are
intentionally deferred for later consideration.
A good issue-tracking system should have at least the
following properties:
With a nod to the time-honoured computer science tradition
of "filling in the fourth quadrant", we note that
there are really four kinds of information flow
going on here. The three mentioned qualities
really address the first three quadrants of this 2-by-2 matrix,
respectively:
Simplicity. It is a strong requirement
that the tool be accessible and understandable. It should
be fairly obvious what different parts of the interface do,
and the inner mechanisms should operate in ways that most
users can easily predict.
Efficiency.
We aim to optimize for minimum effort to do the most common
operations, and best use of resources like screen real estate
to maximize the amount of information that we summarize and present.
Generality. We try to avoid making
unnecessary assumptions that would restrict the applicability
of the tool. For example, there is no reason why one might
not also want to use this tool to manage a design process,
non-software projects, or organizational decisions.
Persistence. We
prefer hiding or reclassifying information to deleting it.
This helps support the collection of statistics later.
If records are never destroyed, there is little danger
in providing access to a larger community, and logging yields
accountability, which may encourage better behaviour.
Roundup stores a number of items, each of
which can have several properties and an associated discussion.
The properties can be used to classify or search for items.
The discussion is a sequence of e-mail messages.
Each item is identified by a unique number, and has
an activity log which
records the time and content of edits made on its properties.
The log stays fairly small since the design intentionally
provides only small data types as item properties, and
encourages anything large to be attached to
e-mail where it becomes part of the discussion.
The next section explains how items are organized.
Some systems try to alleviate this problem by
allowing nodes to appear at multiple locations
in a tree, as with "aliases" or "symbolic links" in
a filesystem, for example. This does help somewhat,
but we want to be even more flexible
by allowing the
organization of nodes into sets that may freely
intersect. Rather than putting each node at exactly
one place in an overall "grand scheme", a node can
belong to as many sets as are appropriate.
If we choose to represent the sets themselves as nodes
and set membership as a link between nodes,
we're now ready to present the definition of a
hyperdatabase.
There are several reasons for building our
own kind of database for Roundup rather than using an existing one.
Requiring the installation of a full-blown third-party
SQL database system would probably deter many potential
users from attempting to set up Roundup;
yet a real relational database would be too
complicated to implement on our own.
On the other hand, a hyperdatabase can be implemented fairly easily
using one of the Python DBM modules, so we can
take the "batteries-included" approach and provide it
as part of the system. It's easier to build and understand
than a true relational database (in accordance with our guiding
principle of simplicity), but provides
most of the query functionality we want.
A hyperdatabase is well suited for finding the intersection
of a number of sets in which items belong. We expect that
most of the queries people want to do will be of this
form, rather than complicated SQL queries. For example, a
typical request might be
"show me all critical items related to security".
The ability to store arbitrary key-value pairs and links
on nodes gives it more flexibility than an RDBMS.
Users are not going to be making thousands of queries
per second, so it makes sense to optimize for simplicity
and flexibility rather than performance.
~%#gH3>ֆmSQ_ b-Q7uL ȷ}MT'(>@yCDVvbcWqxf|>MmNil_Zn h eP6^H ns i]m|Qj+($5T{oy{B_OvMtL_> qOoww>i4GZVcn_\EL (_z8"/>_mT۳M[c['$G{yW{&9ywE>F?x0xgv'sޮϺ4'>4hz c_ ^×& '>{ +%$Ap>>}7%-DtG{b{ق{LvH q>;%cgJ> `S_|4>Ɩ|!mL]tBg>HBbH_dWJ6nnOq Uf E!Ĉ YShQrȐ"G,iRd jLɐPAL3kd)&z-j趤I *]Qn;$LFkO[jJV ذi[a.ҭȘ1Qz7& |jE(o3n?A$QQ2f#om~؈" i *QT u[[8 {vmHp{3pnѮ%kR=SGDu3sÉN9zR|r7ǵk /b}5,l}z ӧj"FJ$/ROUNDUP-ADMIN
NAME
SYNOPSIS
OPTIONS
COMMANDS
READLINE SUPPORT
SECURITY NOTES
ENVIRONMENT VARIABLES
FURTHER HELP
SEE ALSO
AUTHOR
NAME
SYNOPSIS
OPTIONS
COMMANDS
pragma verbose=yes
pragma verbose=on
pragma verbose=1READLINE SUPPORT
SECURITY NOTES
ENVIRONMENT VARIABLES
FURTHER HELP
roundup-admin help -- this help
roundup-admin help <command> -- command-specific help
roundup-admin help all -- all available helpSEE ALSO
AUTHOR
code-9c3ec0a5c7fc/doc/html_extra/man_pages/roundup-demo.1.html 0000644 0000000 0000000 00000014360 15165601534 022416 0 ustar 0000000 0000000
ROUNDUP-DEMO
NAME
SYNOPSIS
OPTIONS
DESCRIPTION
SEE ALSO
AUTHOR
NAME
SYNOPSIS
OPTIONS
will remove an existing tracker (if present) from the
directory ./mytracker. Then it will create and serve
a new empty classic tracker using the sqlite backend.
{anydbm,mysql,sqlite,postgresql}
{minimal,jinja2,classic,responsive,devel}DESCRIPTION
SEE ALSO
AUTHOR
code-9c3ec0a5c7fc/doc/html_extra/man_pages/roundup-mailgw.1.html 0000644 0000000 0000000 00000025127 15165601534 022755 0 ustar 0000000 0000000
ROUNDUP-MAILGW
NAME
SYNOPSIS
OPTIONS
DESCRIPTION
ENVIRONMENT VARIABLES
EXAMPLE
SEE ALSO
AUTHOR
NAME
SYNOPSIS
OPTIONS
DESCRIPTION
If there is no mail source specified, the mail gateway reads
a single message from the standard input and submits the
message to the roundup.mailgw module.
In this case, the gateway reads all messages from the UNIX
mail spool file and submits each in turn to the
roundup.mailgw module. The file is emptied once all messages
have been successfully handled. The file is specified as:
mailbox /path/to/mailbox
For the mail source "pop", the gateway reads all
messages from the POP server specified and submits each in
turn to the roundup.mailgw module. The server is specified
as:
pop
username:password@server
The username and password may be omitted:
pop username@server
pop server
are both valid.
Connect to the POP server over ssl/tls. This supports the
same notation as POP.
Same as POP, but using Authenticated POP:
apop
username:password@server
Connect to an IMAP server. This supports the same notation
as that of POP mail.
imap
username:password@server
It also allows you to specify a specific mailbox other than
INBOX using this format:
imap
username:password@server
mailbox
Connect to an IMAP server over ssl/tls. This supports the
same notation as IMAP.
imaps
username:password@server
[mailbox]
Connect to an IMAP server over ssl/tls using CRAM-MD5
authentication. This supports the same notation as IMAP.
imaps_cram
username:password@server
[mailbox]
Connect to an IMAP server over ssl/tls using OAUTH
authentication. Note that this does not support a password
in imaps URLs. Instead it uses only the user and server and
a command-line option for the directory with the files
access_token, refresh_token,
client_secret, and client_id. By default this
directory is oauth in your tracker home directory.
The access token is tried first and, if expired, the refresh
token together with the client secret is used to retrieve a
new access token. Note that both token files need to be
writeable, the access token is continuously replaced
and some cloud providers may also renew the refresh token
from time to time:
imaps_oauth username@server
[mailbox]
The refresh and access tokens (the latter can be left
empty), the client id and the client secret need to be
retrieved via cloud provider specific protocols or
websites.ENVIRONMENT VARIABLES
This can be used to set the instance directory. If it is
set, the instance_home argument is optional.EXAMPLE
-S "msg.messagetype=reply - to all"
/var/roundup/sysadmin
-S "msg.messagetype=to tech"
/var/roundup/sysadmin
-S "issue.private=true" -S
"issue.keyword+=security"
/var/roundup/sysadminSEE ALSO
AUTHOR
code-9c3ec0a5c7fc/doc/html_extra/man_pages/roundup-server.1.html 0000644 0000000 0000000 00000024125 15165601534 023000 0 ustar 0000000 0000000
ROUNDUP-SERVER
NAME
SYNOPSIS
OPTIONS
EXAMPLES
CONFIGURATION FILE
SEE ALSO
AUTHOR
NAME
SYNOPSIS
OPTIONS
-----END PRIVATE KEY-----
-----END CERTIFICATE-----
EXAMPLES
CONFIGURATION FILE
SEE ALSO
AUTHOR
code-9c3ec0a5c7fc/doc/html_extra/original_overview.html 0000644 0000000 0000000 00000115402 15165601534 021440 0 ustar 0000000 0000000
![[Software Carpentry logo]](images/logo-software-carpentry-standard.png){kind=logo}
![[ACL Logo]](images/logo-acl-medium.png){kind=logo}
![[CodeSourcery Logo]](images/logo-codesourcery-medium.png){kind=logo}
Copyright (c) 2000 Ka-Ping Yee. This material may
be distributed only subject to the terms and conditions set forth in
the Software Carpentry Open Publication License, which is available at:
Roundup
An Issue-Tracking System for Knowledge Workers
Ka-Ping Yee
lfw discorporated
ping@lfw.org
Contents
Overview
Background
An example of the fourth kind of flow is voting.
Voting isn't described in this design,
but it should be noted as a potential enhancement.
Guiding Principles
Okay, enough ranting. Let's get down to business.
Data Model
The Hyperdatabase
Often when classifying information we are
asked to select exactly one of a number of categories
or to fit it into a rigid hierarchy. Yet things
only sometimes fall into one category; often,
a piece of information may be related to several concepts.
For example, forcing each item into a single topic
category is not just suboptimal but counterproductive:
seekers of that
item may expect to find it in a different category
and conclude that the item is not present in the
database -- which has them worse off
than if the items were not categorized at all.
In my opinion, forcing
items into fixed categories is one of the most
serious problems with the Roundup prototype.
The hyperdatabase is an experimental attempt to
address the problem of information organization,
whose scope goes beyond just Roundup.
A hyperdatabase is a collection of nodes
that may be hyperlinked to
each other (hence the name "hyperdatabase").
Each node carries a collection of key-value pairs,
where some of the values may be links to other nodes.
Any node may have an arbitrary number of outgoing and
incoming links. Hyperdatabases are able to efficiently
answer queries such as "what nodes link to this node?"
and "what nodes does this node link to?"
Perhaps it's too pretentious a name?
You could say this is just like an object database.
The hyperdatabase is hardly much of an invention; the
intent is merely to emphasize querying on links
rather than properties.
(I haven't heard of this being done with
object databases before, but plead ignorance if
there's already a good name for this idea.)
Rationale
Roundup's Hyperdatabase
For our application, we store each item as a node in a hyperdatabase. The item's properties are stored as key-value pairs on its node. Four types of properties are allowed: string, date, choice, and reference.
The string type is for short, free-form strings. String properties are not intended to contain large amounts of text, and it is recommended that they be presented as one-line fields to encourage brevity.
The date type is for calendar dates and times.
The choice type denotes a single selection from a number of options. A choice property entails a link from the node possessing the property to the node representing the chosen option.
The reference type is for a list of links to any number of other nodes in the in the database. A reference property, for example, can be used to refer to related items or topic categories relevant to an item.
For Roundup, all items have five properties that are not customizable:
- a string property named description
- a reference property named superseder
- a reference property named nosy
- a date property named creation
- a date property named activity
The description property is a short one-line description of the item. The detailed description can go in the first e-mail message of the item's discussion spool.
The superseder property is used to support the splitting, joining, or replacing of items. When several items need to be joined into a single item, all the old items link to the new item in their superseder property. When an item needs to be split apart, the item references all the new items in its superseder propety. We can easily list all active items just by checking for an empty superseder property, and trace the path of an item's origins by querying the hyperdatabase for links.
The nosy property contains a list of the people who are interested in an item. This mechanism is explained in the section on Nosy Lists.
The creation property records the item's creation time. The activity property records the last time that the item was edited or a mail message was added to its discussion spool. These two properties are managed by Roundup and are not available to be edited like other properties.
Users of the system are also represented by nodes in the hyperdatabase, containing properties like the user's e-mail address, login name, and password.
The Default Schema
|
It is hoped that the hyperdatabase together with the specializations mentioned above for Roundup will be applicable in a variety of situations (in accordance with our guiding principle of generality).
To address the problem at hand, we need
a specific schema for items applied particularly to software development.
Again, we are trying to keep the schema simple: too many
options make it tougher for someone to make a good choice.
The schema is written here in the same form that it would
appear in a configuration file.
fixer = Reference() # people who will fix the problem
topic = Reference() # relevant topic keywords
priority = Choice("critical", # panic: work is stopped!
"urgent", # important, but not deadly
"bug", # lost work or incorrect results
"feature", # want missing functionality
"wish") # avoidable bugs, missing conveniences
status = Choice("unread", # submitted but no action yet
"deferred", # intentionally set aside
"chatting", # under review or seeking clarification
"need-eg", # need a reproducible example of a bug
"in-progress", # understood; development in progress
"testing", # we think it's done; others, please test
"done-cbb", # okay for now, but could be better
"resolved") # fix has been released
The fixer property assigns responsibility for an item to a person or a list of people. The topic property places the item in an arbitrary number of relevant topic sets (see the section on Browsing and Searching).
As previously mentioned, each item gets an activity log. Whenever a property on an item is changed, the log records the time of the change, the user making the change, and the old and new values of the property. This permits the later gathering of statistics (for example, the average time from submission to resolution).
We do not specify or enforce a state transition graph, since making the system rigid in that fashion is probably more trouble than it's worth. Experience has shown that there are probably two convenient automatic state transitions:
- from unread to chatting when e-mail is written about an item
- from testing to resolved when a new release of the software is made
User Interface
Roundup provides its services through two main interfaces: e-mail and the Web. This division is chosen to optimize the most common tasks.
E-mail is best suited for the submission of new items since most people are most comfortable with composing long messages in their own favourite e-mail client. E-mail also permits them to mention URLs or attach files relevant to their submission. Indeed, in many cases people are already used to making requests by sending e-mail to a mailing list of people; they can do exactly the same thing to use Roundup without even thinking about it. Similarly, people are already familiar with holding discussions in e-mail, and plenty of valuable usage conventions and software tools already exist for that medium.
The Web, on the other hand, is best suited for summarizing and seeking information, because it can present an interactive overview of items. Since the Web has forms, it's also the best place to edit items.
Submission and Discussion
|
The system needs an address for receiving mail and an address that forwards mail to all participants. Each item has its own list of interested parties, known as its nosy list. Here's how nosy lists work:
- New items are always submitted by sending an e-mail message to Roundup. The "Subject:" field becomes the description of the new item. The message is saved in the mail spool of the new item, and copied to the list of all participants so everyone knows that a new item has been added. The new item's nosy list initially contains the submitter.
- All e-mail messages sent by Roundup have their "Reply-To:" field set to Roundup's address, and have the item's number in the "Subject:" field. Thus, any replies to the initial announcement and subsequent threads are all received by Roundup. Roundup notes the item number in the "Subject:" field of each incoming message and appends the message to the appropriate spool.
- Any incoming e-mail tagged with an item number is copied to all the people on the item's nosy list, and any users found in the "From:", "To:", or "Cc:" fields are automatically added to the nosy list. Whenever a user edits an item's properties in the Web interface, they are also added to the nosy list.
The effect is like each item having its own little mailing list, except that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is Cc: a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important.
Each nosy list is like an asynchronous chat room, lasting only a short time (typically five or ten messages) and involving a small group of people. However, that group is the right group of people: only those who express interest in an item in some way ever end up on the list, so no one gets spammed with mail they don't care about, and no one who wants to see mail about a particular item needs to be left out, for they can easily join in, and just as easily look at the mail spool on an item to catch up on any messages they might have missed.
We can take this a step further and permit users to monitor particular topics or classifications of items by allowing other kinds of nodes to also have their own nosy lists. For example, a manager could be on the nosy list of the priority value node for "critical", or a developer could be on the nosy list of the topic value node for "security". The recipients are then determined by the union of the nosy lists on the item and all the nodes it links to.
Using many small, specific mailing lists results in much more effective communication than one big list. Taking away the effort of subscribing and unsubscribing gives these lists the "feel" of being cheap and disposable. The transparent capture of the mail spool attached to each issue also yields a nice knowledge repository over time.
Editing
Since Roundup is intended to support arbitrary user-defined
schema for item properties, the editing interface must be
automatically generated from the schema. The configuration for
Roundup will include a template describing how to lay out the
properties to present a UI for inspecting and editing items.
For example:
<table width="100%">
<tr><td align=right>Description:</td>
<td><?property description size=70></td></tr>
<tr><td align=right>Status:</td>
<td><?property status></td></tr>
</table>
To display the editing form for an item, Roundup substitutes an HTML form widget for each <?property ...> tag, and transfers attributes (such as size=70 in the above example) from the processing tag to the form widget's tag. Each type has its own appropriate editing widget:
- string properties appear as text fields
- date properties appear as text fields
- choice properties appear as selection lists
- reference properties appear as multiple-selection lists with a text field for adding a new option
We foresee the use of custom date fields for things like deadlines, so input fields for date properties should support some simple way of specifying relative dates (such as "three weeks from now").
The superseder property is a special case: although it is more efficient to store a superseder property in the superseded item, it makes more sense to provide a "supersedes" edit field on the superseding item. So we need a special widget on items for this purpose (perhaps something as simple as a text field containing a comma-separated list of item numbers will do). Links in the superseder property should appear on both the superseding and superseded items to facilitate navigating an item's pedigree.
After the editing widgets, the item inspection page shows a "note" text box and then a display of the messages in the discussion spool, like the Roundup prototype. This field lets you enter a note explaining your change when you edit the item, and the note is included in the notification message that goes out to tell the interested parties on the nosy list of your edits.
Browsing and Searching
The ideal we would like to achieve is to make searching as much like browsing as possible: the user simply clicks about on things that seem interesting, and the information narrows down comfortably until the goal is in sight. This is preferable to trying to digest a screen filled with widgets and buttons or entering a search expression in some arcane algebraic syntax.
|
The browsing interface presents filtering functionality for each of the properties in the schema. As with editing, the interface is generated from a template describing how to lay out the properties. Each type of property has its own appropriate filtering widget:
- string properties appear as text fields supporting case-insensitive substring match
- date properties appear as a text field with an option to choose dates after or before the specified date
- choice properties appear as a group of selectable options (the filter selects the union of the sets of items associated with the active options)
- reference properties appear as a group of selectable options (the filter selects the intersection of the sets of items associated with the active options)
For a reference property like topic, one possibility is to show, as hyperlinks, the keywords whose sets have non-empty intersections with the currently displayed set of items. Sorting the keywords by popularity seems reasonable. Clicking on a keyword then narrows both the list of items and the list of keywords. This gives some of the feel of walking around a directory tree -- but without the restriction of having to select keywords in a particular hierarchical order, and without the need to travel all the way to the leaves of the tree before any items are visible.
Below the filtering form is a listing of items, with their properties displayed in a table. Rows in the table can also be generated from a template, as with the editing interface. This listing is the central overview of the system, and it should aim to maximize the density of useful information in accordance with our guiding principle of efficiency. For example, Bugzilla initially displays seven or eight items of the index, but only after the user has waded through three bewildering screens of form widgets. Jitterbug can't even fit any items at all in the first screenful, as it's taken up by artwork and adminstrative debris. In contrast, in the Roundup prototype, 25 high-priority issues are immediately visible, with most of the screen space devoted to their descriptions. Colour indicates the status of each item to help the eye sift through the index quickly.
In both Jitterbug and Bugzilla, items are sorted by default by ID, a meaningless field. Sorting by ID puts the issues in order by ascending submission date, which banishes recent issues far away at the bottom of the list. The Roundup prototype sorts items in sections by priority, and then within sections by the date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list.
The page produced by a given set of browsing options constitutes a view. The options should all be part of the query parameters in the URL so that views may be bookmarked. A view specifies:
- search strings for string properties
- date ranges for date properties
- acceptable values for choice properties
- required values for reference properties
- one or more sort keys
- a list of properties for which to display filtering widgets
On each sort key there is the option to use sections -- that is, instead of making the property's value a column of the table, each possible value for the property is displayed at the top of a section and all the items having that value for that property are grouped underneath. This avoids wasting screen space with redundant information.
We propose that our default view should be:
- all options on for priority and fixer
- all options on except "resolved" for status
- no options on for topic
- primary sort by priority in sections
- secondary sort by decreasing activity date
The starting URL for Roundup should immediately present the listing of items generated by this default view, with no preceding query screen.
Development Plan
The hyperdatabase is clearly a separable component which can be developed and tested independently to an API specification.
As soon as the API to the hyperdatabase is nailed down, the implementation of the Roundup database layer on top of the hyperdatabase can begin. (This refers to the data types and five fixed properties specific to Roundup.) This layer can also be tested separately.
When the interface to the Roundup hyperdatabase is ready, development can begin on the user interface. The mail handler and the Web interface can be developed in parallel and mostly independently of each other.
The mail handler can be set up for testing fairly easily: mail messages on its standard input can be synthesized; its output is outgoing mail, which can be captured by replacing the implementation of the "send mail" function; and its side effects appear in the hyperdatabase, which has a Python API.
The Web interface is not easily testable in its entirety, though the most important components of it can be unit tested, such as the component that translates a view specification into a list of items for display, and the component that performs replacements on templates to produce an editing or filtering interface.
Open Issues
The description of the hyperdatabase above avoids some issues regarding node typing that need to be better specified. It is conceivable that eventually Roundup could support multiple kinds of items with their own schemas.
To permit integration with external tools, it is probably a good idea to provide a command-line tool that exposes the hyperdatabase API. This tool will be left for a later phase of development and so isn't specified in detail here.
Generating the user interface from a template is like applying an XSL stylesheet to XML, and if there's a standard Python module for performing these transformations, we could use XML instead.
More thinking is needed to determine the best filtering interface for reference properties. The proposed interface works well for topic keywords, but it isn't clear what to do when there are too many keywords to display them all.
There has been a variety of reactions to the hyperdatabase from reviewers: some like it, some are neutral, and some would prefer a "standard" RDBMS solution. For those in the latter camp, note that it's still possible to build the Roundup database layer around an RDBMS if we really need to. The rest of the design, in particular the "nosy list" mechanism, remains intact.
The possibility of malice by registered users has been disregarded. The system is intended to be used by a co-operative group.
This design tries to address as many as possible of the suggested requirements mentioned on the contest page:
- configuring states: Edit the schema.
- setting state transition rules: We don't enforce any rules.
- assigning responsibility: Set the fixer property.
- splitting and joining: Use the superseder property.
- hiding information: Add a property and a pre-defined view that filters on it.
- secure protocols: Naturally HTTPS would be nice, though it's largely a webserver configuration issue; secure e-mail is not addressed.
- archiving old issues: Tag them with a property.
- identifying repeated issues: Use the superseder property.
- connecting state changes to external operations: We provide an API to the database and the notification mechanism so it can be scripted.
- non-Latin alphabets: Unicode in Python 1.6 will handle this for string properties, and we can leverage existing standards for internationalizing e-mail messages.
- images and other binaries: Attach them to e-mail messages.
- inspecting item state: Use the editing interface.
- translation between system-dependent formats: This is not addressed.
- performing searches: Use the browsing and filtering interface.
- collecting statistics: Information is gathered in the activity log, though tools to summarize it are not described here.
Summary
Roundup is an issue-tracking system that also functions as a communications center and a knowledge repository. It combines the strengths of e-mail and the Web to try to provide the best possible user interaction.
- The submission and discussion of items by e-mail, permitting participants to use an easy and familiar tool, achieves our goal of low barrier to participation.
- The generic link-based structuring of data and use of incremental filtering rather than one-shot querying makes for straightforward navigation.
- The use of nosy lists (a powerful replacement for e-mail discussion lists) to manage communication on a fine-grained level provides controlled information flow.
The use of a "hyperdatabase" as the core model for the knowledge repository gives us the flexibility to extend Roundup and apply it to a variety of domains by providing new item schemas and user-interface templates.
Roundup is self-contained and easy to set up, requiring only a webserver and a mailbox. No one needs to be root to configure the webserver or to install database software.
This design is based on an existing deployed prototype which has proven its strengths and revealed its weaknesses in heavy day-to-day use by a real development team.
Acknowledgements
My thanks are due to Christina Heyl, Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for reviewing this paper and contributing their suggestions.
| [Home] | [FAQ] | [License] | [Rules] | [Resources] | [Archives] |
| Roundup Short Paper | ![[LFW]](/images/lfwblue.gif){kind=small} |
Roundup: A Simple and Effective Issue Tracker in Python
Ka-Ping Yee (original site: http://www.lfw.org/ping/roundup.html)Please note that there is a new, active Roundup project led by Richard Jones. Please visit them at SourceForge.
The Roundup prototype is open source. You can download it here (roundup.tar.gz, 32 kb). Or play with the live prototype! When prompted for authentication, you can use one of the test accounts: "test", "spam", or "eggs" (password same as account name). Roundup's e-mail address is roundup---lfw.org. You can't create new accounts, but you can read the mail spools for test, spam, or eggs here to see what they're getting.
A detailed design proposal for a more advanced issue-tracking system based on Roundup has been submitted to Software Carpentry's open source software design competition. This first-round submission was selected as a finalist. A more detailed implementation guide was submitted to the second round of the competition.
You might also want to check out other Python-related stuff on this site.
This short talk will share some experiences from developing and using the issue tracking system used by my development group at ILM. It integrates two modes of access: e-mail for gathering information, and the Web for search and retrieval. We currently work with it daily and it does its job pretty well.
Fine-Grained Mailing Lists
The key strength of Roundup is that it generates a small virtual mailing list for each new issue. In a way, this is like implementing private conversation rooms in e-mail. Although the mechanism is very simple, the emergent properties are quite effective. Here's how it works:
- New issues are always submitted by sending an e-mail message. This message is saved in a mail spool attached to the newly-created issue record, and copied to the relatively large user community of the application so everyone knows the issue has been raised.
- All e-mail messages sent by Roundup have their "Reply-To" field set to send mail back to Roundup, and have the issue's ID number in the Subject field. So, any replies to the initial announcement and subsequent threads are all received by Roundup and appended to the spool.
- Each issue has a "nosy list" of people interested in the issue. Any mail tagged with the issue's ID number is copied to this list of people, and any users found in the From:, To:, or Cc: fields of e-mail about the issue are automatically added to the nosy list. Whenever a user edits an item in the Web interface, they are also added to the list.
The result is that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is Cc: a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important. The transparent capture of the mail spool attached to each issue also yields a nice searchable knowledge repository over time.
User Interface Decisions
The web interface to Roundup aims to maximize the density of useful information. Although this principle is important to all information presentation, it is especially vital in a web browser because of the limited window real estate. Hence Roundup avoids repetitive or unnecessary information and tries to fit as many items as possible on the first screen. For example, Bugzilla initially displays seven or eight items of the index; Jitterbug can't even manage to fit any items at all in the first screenful, as it's taken up by artwork and adminstrative debris. In contrast, Roundup shows you about 25 high-priority issues right away. Colour indicates the status of each item to help the eye sift through the index quickly.
In both Jitterbug and Bugzilla, items are sorted by default by ID, a meaningless field. Sorting by ID puts the issues in order by ascending submission date, which banishes recent issues as far away as possible at the bottom of the list. Roundup sorts items in sections by priority so the high-priority items are immediately visible; within sections, items are sorted by date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list without changing its priority.
(The following has been added for this web page and was not part of the short paper in the IPC8 proceedings.)
Screenshots of the Web Interface
Here is the Roundup index, the first thing presented to you when you go to Roundup. Note the use of colour coding and the attempt to dedicate maximum space to the description of each issue.
In comparison, here is the first screen you see when you use Jitterbug. No information is actually visible! You have to scroll down to the second screen before you get to see any bugs, and even then your view is limited to a paltry eight entries. The boldface on the item descriptions helps, but the visual effect of the table is still swamped by the powerful green header line -- which contains zero bits of new information.
As another example, Bugzilla presents somewhat more information than Jitterbug in its index view, but forces you to go through three bewildering screens replete with form widgets (one, two, three) before you even get to see anything. Examination of the index view shows that one-third to one-half of the screen area (depending how you count it) is wasted on trivialities or empty space, and the most important column, the description of each issue, is shoved off of the right side of the page.
| copyright © by Ka-Ping Yee updated Sun 2 Jul 2000 |
|
|
|
Roundup
An Issue-Tracking System for Knowledge Workers
Ka-Ping Yee
ping@lfw.org
Implementation Guide
Contents
- Introduction
- The Layer Cake
- Hyperdatabase
- Dates and Date Arithmetic
- Items and Classes
- Identifiers and Designators
- Property Names and Types
- Interface Specification
- Application Example
- Roundup Database
- Reserved Classes
- Users
- Messages
- Files
- Item Classes
- Interface Specification
- Default Schema
- Reserved Classes
- Detector Interface
- Interface Specification
- Detector Example
- Command Interface
- Interface Specification
- Usage Example
- E-mail User Interface
- Message Processing
- Nosy Lists
- Setting Properties
- Workflow Example
- Web User Interface
- Views and View Specifiers
- Displaying Properties
- Index Views
- Index View Specifiers
- Filter Section
- Index Section
- Sorting
- Item Views
- Item View Specifiers
- Editor Section
- Spool Section
- Deployment Scenarios
- Acknowledgements
1. Introduction
This document presents a description of the components of the Roundup system and specifies their interfaces and behaviour in sufficient detail to guide an implementation. For the philosophy and rationale behind the Roundup design, see the first-round Software Carpentry submission for Roundup. This document fleshes out that design as well as specifying interfaces so that the components can be developed separately.
2. The Layer Cake
Lots of software design documents come with a picture of a cake. Everybody seems to like them. I also like cakes (i think they are tasty). So i, too, shall include a picture of a cake here.
|
E-mail Client |
Web Browser |
Detector Scripts |
Shell |
|
E-mail User Interface |
Web User Interface |
Detector Interface |
Command Interface |
|
Roundup Database Layer |
|||
|
Hyperdatabase Layer |
|||
|
Storage Layer |
|||
The colourful parts of the cake are part of our system; the faint grey parts of the cake are external components.
I will now proceed to forgo all table manners and eat from the bottom of the cake to the top. You may want to stand back a bit so you don't get covered in crumbs.
3. Hyperdatabase
The lowest-level component to be implemented is the hyperdatabase. The hyperdatabase is intended to be a flexible data store that can hold configurable data in records which we call items.
The hyperdatabase is implemented on top of the storage layer, an external module for storing its data. The storage layer could be a third-party RDBMS; for a "batteries-included" distribution, implementing the hyperdatabase on the standard bsddb module is suggested.
3.1. Dates and Date Arithmetic
Before we get into the hyperdatabase itself, we need a way of handling dates. The hyperdatabase module provides Timestamp objects for representing date-and-time stamps and Interval objects for representing date-and-time intervals.
As strings, date-and-time stamps are specified with the date in international standard format (yyyy-mm-dd) joined to the time (hh:mm:ss) by a period ("."). Dates in this form can be easily compared and are fairly readable when printed. An example of a valid stamp is "2000-06-24.13:03:59". We'll call this the "full date format". When Timestamp objects are printed as strings, they appear in the full date format with the time always given in GMT. The full date format is always exactly 19 characters long.
For user input, some partial forms are also permitted: the whole time or just the seconds may be omitted; and the whole date may be omitted or just the year may be omitted. If the time is given, the time is interpreted in the user's local time zone. The Date constructor takes care of these conversions. In the following examples, suppose that yyyy is the current year, mm is the current month, and dd is the current day of the month; and suppose that the user is on Eastern Standard Time.
- "2000-04-17" means <Date 2000-04-17.00:00:00>
- "01-25" means <Date yyyy-01-25.00:00:00>
- "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
- "08-13.22:13" means <Date yyyy-08-14.03:13:00>
- "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
- "14:25" means <Date yyyy-mm-dd.19:25:00>
- "8:47:11" means <Date yyyy-mm-dd.13:47:11>
- the special date "." means "right now"
Date intervals are specified using the suffixes "y", "m", and "d". The suffix "w" (for "week") means 7 days. Time intervals are specified in hh:mm:ss format (the seconds may be omitted, but the hours and minutes may not).
- "3y" means three years
- "2y 1m" means two years and one month
- "1m 25d" means one month and 25 days
- "2w 3d" means two weeks and three days
- "1d 2:50" means one day, two hours, and 50 minutes
- "14:00" means 14 hours
- "0:04:33" means four minutes and 33 seconds
The Date class should understand simple date expressions of the form stamp + interval and stamp - interval. When adding or subtracting intervals involving months or years, the components are handled separately. For example, when evaluating "2000-06-25 + 1m 10d", we first add one month to get 2000-07-25, then add 10 days to get 2000-08-04 (rather than trying to decide whether 1m 10d means 38 or 40 or 41 days).
Here is an outline of the Date and Interval classes.
class Date:
def __init__(self, spec, offset):
"""Construct a date given a specification and a time zone offset.
'spec' is a full date or a partial form, with an optional
added or subtracted interval. 'offset' is the local time
zone offset from GMT in hours.
"""
def __add__(self, interval):
"""Add an interval to this date to produce another date."""
def __sub__(self, interval):
"""Subtract an interval from this date to produce another date."""
def __cmp__(self, other):
"""Compare this date to another date."""
def __str__(self):
"""Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
def local(self, offset):
"""Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
class Interval:
def __init__(self, spec):
"""Construct an interval given a specification."""
def __cmp__(self, other):
"""Compare this interval to another interval."""
def __str__(self):
"""Return this interval as a string."""
Here are some examples of how these classes would behave in practice. For the following examples, assume that we are on Eastern Standard Time and the current local time is 19:34:02 on 25 June 2000.
>>> Date(".") <Date 2000-06-26.00:34:02> >>> _.local(-5) "2000-06-25.19:34:02" >>> Date(". + 2d") <Date 2000-06-28.00:34:02> >>> Date("1997-04-17", -5) <Date 1997-04-17.00:00:00> >>> Date("01-25", -5) <Date 2000-01-25.00:00:00> >>> Date("08-13.22:13", -5) <Date 2000-08-14.03:13:00> >>> Date("14:25", -5) <Date 2000-06-25.19:25:00> >>> Interval(" 3w 1 d 2:00") <Interval 22d 2:00> >>> Date(". + 2d") - Interval("3w") <Date 2000-06-07.00:34:02>
3.2. Items and Classes
Items contain data in properties. To Python, these properties are presented as the key-value pairs of a dictionary. Each item belongs to a class which defines the names and types of its properties. The database permits the creation and modification of classes as well as items.
3.3. Identifiers and Designators
Each item has a numeric identifier which is unique among items in its class. The items are numbered sequentially within each class in order of creation, starting from 1. The designator for an item is a way to identify an item in the database, and consists of the name of the item's class concatenated with the item's numeric identifier.
For example, if "spam" and "eggs" are classes, the first item created in class "spam" has id 1 and designator "spam1". The first item created in class "eggs" also has id 1 but has the distinct designator "eggs1". Item designators are conventionally enclosed in square brackets when mentioned in plain text. This permits a casual mention of, say, "[patch37]" in an e-mail message to be turned into an active hyperlink.
3.4. Property Names and Types
Property names must begin with a letter.
A property may be one of five basic types:
- String properties are for storing arbitrary-length strings.
- Date properties store date-and-time stamps. Their values are Timestamp objects.
- A Link property refers to a single other item selected from a specified class. The class is part of the property; the value is an integer, the id of the chosen item.
- A Multilink property refers to possibly many items in a specified class. The value is a list of integers.
None is also a permitted value for any of these property types. An attempt to store None into a String property stores the empty string; an attempt to store None into a Multilink property stores an empty list.
3.5. Interface Specification
The hyperdb module provides property objects to designate the different kinds of properties. These objects are used when specifying what properties belong in classes.
class String:
def __init__(self):
"""An object designating a String property."""
class Date:
def __init__(self):
"""An object designating a Date property."""
class Link:
def __init__(self, classname):
"""An object designating a Link property that links to
items in a specified class."""
class Multilink:
def __init__(self, classname):
"""An object designating a Multilink property that links
to items in a specified class."""
Here is the interface provided by the hyperdatabase.
class Database:
"""A database for storing records containing flexible data types."""
def __init__(self, storagelocator, journaltag):
"""Open a hyperdatabase given a specifier to some storage.
The meaning of 'storagelocator' depends on the particular
implementation of the hyperdatabase. It could be a file name,
a directory path, a socket descriptor for a connection to a
database over the network, etc.
The 'journaltag' is a token that will be attached to the journal
entries for any edits done on the database. If 'journaltag' is
None, the database is opened in read-only mode: the Class.create(),
Class.set(), and Class.retire() methods are disabled.
"""
def __getattr__(self, classname):
"""A convenient way of calling self.getclass(classname)."""
def getclasses(self):
"""Return a list of the names of all existing classes."""
def getclass(self, classname):
"""Get the Class object representing a particular class.
If 'classname' is not a valid class name, a KeyError is raised.
"""
class Class:
"""The handle to a particular class of items in a hyperdatabase."""
def __init__(self, db, classname, **properties):
"""Create a new class with a given name and property specification.
'classname' must not collide with the name of an existing class,
or a ValueError is raised. The keyword arguments in 'properties'
must map names to property objects, or a TypeError is raised.
"""
# Editing items:
def create(self, **propvalues):
"""Create a new item of this class and return its id.
The keyword arguments in 'propvalues' map property names to values.
The values of arguments must be acceptable for the types of their
corresponding properties or a TypeError is raised. If this class
has a key property, it must be present and its value must not
collide with other key strings or a ValueError is raised. Any other
properties on this class that are missing from the 'propvalues'
dictionary are set to None. If an id in a link or multilink
property does not refer to a valid item, an IndexError is raised.
"""
def get(self, itemid, propname):
"""Get the value of a property on an existing item of this class.
'itemid' must be the id of an existing item of this class or an
IndexError is raised. 'propname' must be the name of a property
of this class or a KeyError is raised.
"""
def set(self, itemid, **propvalues):
"""Modify a property on an existing item of this class.
'itemid' must be the id of an existing item of this class or an
IndexError is raised. Each key in 'propvalues' must be the name
of a property of this class or a KeyError is raised. All values
in 'propvalues' must be acceptable types for their corresponding
properties or a TypeError is raised. If the value of the key
property is set, it must not collide with other key strings or a
ValueError is raised. If the value of a Link or Multilink
property contains an invalid item id, a ValueError is raised.
"""
def retire(self, itemid):
"""Retire an item.
The properties on the item remain available from the get() method,
and the item's id is never reused. Retired items are not returned
by the find(), list(), or lookup() methods, and other items may
reuse the values of their key properties.
"""
def history(self, itemid):
"""Retrieve the journal of edits on a particular item.
'itemid' must be the id of an existing item of this class or an
IndexError is raised.
The returned list contains tuples of the form
(date, tag, action, params)
'date' is a Timestamp object specifying the time of the change and
'tag' is the journaltag specified when the database was opened.
'action' may be:
'create' or 'set' -- 'params' is a dictionary of property values
'link' or 'unlink' -- 'params' is (classname, itemid, propname)
'retire' -- 'params' is None
"""
# Locating items:
def setkey(self, propname):
"""Select a String property of this class to be the key property.
'propname' must be the name of a String property of this class or
None, or a TypeError is raised. The values of the key property on
all existing items must be unique or a ValueError is raised.
"""
def getkey(self):
"""Return the name of the key property for this class or None."""
def lookup(self, keyvalue):
"""Locate a particular item by its key property and return its id.
If this class has no key property, a TypeError is raised. If the
'keyvalue' matches one of the values for the key property among
the items in this class, the matching item's id is returned;
otherwise a KeyError is raised.
"""
def find(self, propname, itemid):
"""Get the ids of items in this class which link to a given item.
'propname' must be the name of a property in this class, or a
KeyError is raised. That property must be a Link or Multilink
property, or a TypeError is raised. 'itemid' must be the id of
an existing item in the class linked to by the given property,
or an IndexError is raised.
"""
def list(self):
"""Return a list of the ids of the active items in this class."""
def count(self):
"""Get the number of items in this class.
If the returned integer is 'numitems', the ids of all the items
in this class run from 1 to numitems, and numitems+1 will be the
id of the next item to be created in this class.
"""
# Manipulating properties:
def getprops(self):
"""Return a dictionary mapping property names to property objects."""
def addprop(self, **properties):
"""Add properties to this class.
The keyword arguments in 'properties' must map names to property
objects, or a TypeError is raised. None of the keys in 'properties'
may collide with the names of existing properties, or a ValueError
is raised before any properties have been added.
"""3.6. Application Example
Here is an example of how the hyperdatabase module would work in practice.
>>> import hyperdb >>> db = hyperdb.Database("foo.db", "ping") >>> db <hyperdb.Database "foo.db" opened by "ping"> >>> hyperdb.Class(db, "status", name=hyperdb.String()) <hyperdb.Class "status"> >>> _.setkey("name") >>> db.status.create(name="unread") 1 >>> db.status.create(name="in-progress") 2 >>> db.status.create(name="testing") 3 >>> db.status.create(name="resolved") 4 >>> db.status.count() 4 >>> db.status.list() [1, 2, 3, 4] >>> db.status.lookup("in-progress") 2 >>> db.status.retire(3) >>> db.status.list() [1, 2, 4] >>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status")) <hyperdb.Class "issue"> >>> db.issue.create(title="spam", status=1) 1 >>> db.issue.create(title="eggs", status=2) 2 >>> db.issue.create(title="ham", status=4) 3 >>> db.issue.create(title="arguments", status=2) 4 >>> db.issue.create(title="abuse", status=1) 5 >>> hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String()) <hyperdb.Class "user"> >>> db.issue.addprop(fixer=hyperdb.Link("user")) >>> db.issue.getprops() {"title": <hyperdb.String>, "status": <hyperdb.Link to "status">, "user": <hyperdb.Link to "user">} >>> db.issue.set(5, status=2) >>> db.issue.get(5, "status") 2 >>> db.status.get(2, "name") "in-progress" >>> db.issue.get(5, "title") "abuse" >>> db.issue.find("status", db.status.lookup("in-progress")) [2, 4, 5] >>> db.issue.history(5) [(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse", "status": 1}), (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})] >>> db.status.history(1) [(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")), (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))] >>> db.status.history(2) [(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]
For the purposes of journalling, when a Multilink property is set to a new list of items, the hyperdatabase compares the old list to the new list. The journal records "unlink" events for all the items that appear in the old list but not the new list, and "link" events for all the items that appear in the new list but not in the old list.
4. Roundup Database
The Roundup database layer is implemented on top of the hyperdatabase and mediates calls to the database. Some of the classes in the Roundup database are considered item classes. The Roundup database layer adds detectors and user items, and on items it provides mail spools, nosy lists, and superseders.
4.1. Reserved Classes
Internal to this layer we reserve three special classes of items that are not items.
4.1.1. Users
Users are stored in the hyperdatabase as items of class "user". The "user" class has the definition:
hyperdb.Class(db, "user", username=hyperdb.String(),
password=hyperdb.String(),
address=hyperdb.String())
db.user.setkey("username")4.1.2. Messages
E-mail messages are represented by hyperdatabase items of class "msg". The actual text content of the messages is stored in separate files. (There's no advantage to be gained by stuffing them into the hyperdatabase, and if messages are stored in ordinary text files, they can be grepped from the command line.) The text of a message is saved in a file named after the message item designator (e.g. "msg23") for the sake of the command interface (see below). Attachments are stored separately and associated with "file" items. The "msg" class has the definition:
hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
recipients=hyperdb.Multilink("user"),
date=hyperdb.Date(),
summary=hyperdb.String(),
files=hyperdb.Multilink("file"))The "author" property indicates the author of the message (a "user" item must exist in the hyperdatabase for any messages that are stored in the system). The "summary" property contains a summary of the message for display in a message index.
4.1.3. Files
Submitted files are represented by hyperdatabase items of class "file". Like e-mail messages, the file content is stored in files outside the database, named after the file item designator (e.g. "file17"). The "file" class has the definition:
hyperdb.Class(db, "file", user=hyperdb.Link("user"),
name=hyperdb.String(),
type=hyperdb.String())The "user" property indicates the user who submitted the file, the "name" property holds the original name of the file, and the "type" property holds the MIME type of the file as received.
4.2. Item Classes
All items have the following standard properties:
title=hyperdb.String()
messages=hyperdb.Multilink("msg")
files=hyperdb.Multilink("file")
nosy=hyperdb.Multilink("user")
superseder=hyperdb.Multilink("item")Also, two Date properties named "creation" and "activity" are fabricated by the Roundup database layer. By "fabricated" we mean that no such properties are actually stored in the hyperdatabase, but when properties on items are requested, the "creation" and "activity" properties are made available. The value of the "creation" property is the date when an item was created, and the value of the "activity" property is the date when any property on the item was last edited (equivalently, these are the dates on the first and last records in the item's journal).
4.3. Interface Specification
The interface to a Roundup database delegates most method calls to the hyperdatabase, except for the following changes and additional methods.
class Database:
# Overridden methods:
def __init__(self, storagelocator, journaltag):
"""When the Roundup database is opened by a particular user,
the 'journaltag' is the id of the user's "user" item."""
def getclass(self, classname):
"""This method now returns an instance of either Class or
ItemClass depending on whether an item class is specified."""
# New methods:
def getuid(self):
"""Return the id of the "user" item associated with the user
that owns this connection to the hyperdatabase."""
class Class:
# Overridden methods:
def create(self, **propvalues):
def set(self, **propvalues):
def retire(self, itemid):
"""These operations trigger detectors and can be vetoed. Attempts
to modify the "creation" or "activity" properties cause a KeyError.
"""
# New methods:
def audit(self, event, detector):
def react(self, event, detector):
"""Register a detector (see below for more details)."""
class ItemClass(Class):
# Overridden methods:
def __init__(self, db, classname, **properties):
"""The newly-created class automatically includes the "messages",
"files", "nosy", and "superseder" properties. If the 'properties'
dictionary attempts to specify any of these properties or a
"creation" or "activity" property, a ValueError is raised."""
def get(self, itemid, propname):
def getprops(self):
"""In addition to the actual properties on the item, these
methods provide the "creation" and "activity" properties."""
# New methods:
def addmessage(self, itemid, summary, text):
"""Add a message to an item's mail spool.
A new "msg" item is constructed using the current date, the
user that owns the database connection as the author, and
the specified summary text. The "files" and "recipients"
fields are left empty. The given text is saved as the body
of the message and the item is appended to the "messages"
field of the specified item.
"""
def nosymessage(self, itemid, msgid):
"""Send a message to the members of an item's nosy list.
The message is sent only to users on the nosy list who are not
already on the "recipients" list for the message. These users
are then added to the message's "recipients" list.
"""
4.4. Default Schema
The default schema included with Roundup turns it into a typical software bug tracker. The database is set up like this:
pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
pri.setkey("name")
pri.create(name="critical", order="1")
pri.create(name="urgent", order="2")
pri.create(name="bug", order="3")
pri.create(name="feature", order="4")
pri.create(name="wish", order="5")
stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
stat.setkey("name")
stat.create(name="unread", order="1")
stat.create(name="deferred", order="2")
stat.create(name="chatting", order="3")
stat.create(name="need-eg", order="4")
stat.create(name="in-progress", order="5")
stat.create(name="testing", order="6")
stat.create(name="done-cbb", order="7")
stat.create(name="resolved", order="8")
Class(db, "keyword", name=hyperdb.String())
Class(db, "issue", fixer=hyperdb.Multilink("user"),
topic=hyperdb.Multilink("keyword"),
priority=hyperdb.Link("priority"),
status=hyperdb.Link("status"))
(The "order" property hasn't been explained yet. It gets used by the Web user interface for sorting.)
The above isn't as pretty-looking as the schema specification in the first-stage submission, but it could be made just as easy with the addition of a convenience function like Choice for setting up the "priority" and "status" classes:
def Choice(name, *options):
cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
for i in range(len(options)):
cl.create(name=option[i], order=i)
return hyperdb.Link(name)
5. Detector Interface
Detectors are Python functions that are triggered on certain kinds of events. The definitions of the functions live in Python modules placed in a directory set aside for this purpose. Importing the Roundup database module also imports all the modules in this directory, and the init() function of each module is called when a database is opened to provide it a chance to register its detectors.
There are two kinds of detectors:
- an auditor is triggered just before modifying an item
- a reactor is triggered just after an item has been modified
When the Roundup database is about to perform a create(), set(), or retire() operation, it first calls any auditors that have been registered for that operation on that class. Any auditor may raise a Reject exception to abort the operation.
If none of the auditors raises an exception, the database proceeds to carry out the operation. After it's done, it then calls all of the reactors that have been registered for the operation.
5.1. Interface Specification
The audit() and react() methods register detectors on a given class of items.
class Class:
def audit(self, event, detector):
"""Register an auditor on this class.
'event' should be one of "create", "set", or "retire".
'detector' should be a function accepting four arguments.
"""
def react(self, event, detector):
"""Register a reactor on this class.
'event' should be one of "create", "set", or "retire".
'detector' should be a function accepting four arguments.
"""
Auditors are called with the arguments:
where db is the database, cl is an instance of Class or ItemClass within the database, and newdata is a dictionary mapping property names to values. For a create() operation, the itemid argument is None and newdata contains all of the initial property values with which the item is about to be created. For a set() operation, newdata contains only the names and values of properties that are about to be changed. For a retire() operation, newdata is None.audit(db, cl, itemid, newdata)
Reactors are called with the arguments:
where db is the database, cl is an instance of Class or ItemClass within the database, and olddata is a dictionary mapping property names to values. For a create() operation, the itemid argument is the id of the newly-created item and olddata is None. For a set() operation, olddata contains the names and previous values of properties that were changed. For a retire() operation, itemid is the id of the retired item and olddata is None.react(db, cl, itemid, olddata)
5.2. Detector Example
Here is an example of detectors written for a hypothetical project-management application, where users can signal approval of a project by adding themselves to an "approvals" list, and a project proceeds when it has three approvals.
# Permit users only to add themselves to the "approvals" list.
def check_approvals(db, cl, id, newdata):
if newdata.has_key("approvals"):
if cl.get(id, "status") == db.status.lookup("approved"):
raise Reject, "You can't modify the approvals list " \
"for a project that has already been approved."
old = cl.get(id, "approvals")
new = newdata["approvals"]
for uid in old:
if uid not in new and uid != db.getuid():
raise Reject, "You can't remove other users from the "
"approvals list; you can only remove yourself."
for uid in new:
if uid not in old and uid != db.getuid():
raise Reject, "You can't add other users to the approvals "
"list; you can only add yourself."
# When three people have approved a project, change its
# status from "pending" to "approved".
def approve_project(db, cl, id, olddata):
if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
if cl.get(id, "status") == db.status.lookup("pending"):
cl.set(id, status=db.status.lookup("approved"))
def init(db):
db.project.audit("set", check_approval)
db.project.react("set", approve_project)Here is another example of a detector that can allow or prevent the creation of new items. In this scenario, patches for a software project are submitted by sending in e-mail with an attached file, and we want to ensure that there are text/plain attachments on the message. The maintainer of the package can then apply the patch by setting its status to "applied".
# Only accept attempts to create new patches that come with patch files.
def check_new_patch(db, cl, id, newdata):
if not newdata["files"]:
raise Reject, "You can't submit a new patch without " \
"attaching a patch file."
for fileid in newdata["files"]:
if db.file.get(fileid, "type") != "text/plain":
raise Reject, "Submitted patch files must be text/plain."
# When the status is changed from "approved" to "applied", apply the patch.
def apply_patch(db, cl, id, olddata):
if cl.get(id, "status") == db.status.lookup("applied") and \
olddata["status"] == db.status.lookup("approved"):
# ...apply the patch...
def init(db):
db.patch.audit("create", check_new_patch)
db.patch.react("set", apply_patch)6. Command Interface
The command interface is a very simple and minimal interface, intended only for quick searches and checks from the shell prompt. (Anything more interesting can simply be written in Python using the Roundup database module.)
6.1. Interface Specification
A single command, roundup, provides basic access to the hyperdatabase from the command line.
- roundup get [-list] designator[,designator,...] propname
- roundup set designator[,designator,...] propname=value ...
- roundup find [-list] classname propname=value ...
Property values are represented as strings in command arguments and in the printed results:
- Strings are, well, strings.
- Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained above.
- Link values are printed as item designators. When given as an argument, item designators and key strings are both accepted.
- Multilink values are printed as lists of item designators joined by commas. When given as an argument, item designators and key strings are both accepted; an empty string, a single item, or a list of items joined by commas is accepted.
When multiple items are specified to the roundup get or roundup set commands, the specified properties are retrieved or set on all the listed items.
When multiple results are returned by the roundup get or roundup find commands, they are printed one per line (default) or joined by commas (with the -list) option.
6.2. Usage Example
To find all messages regarding in-progress issues that contain the word "spam", for example, you could execute the following command from the directory where the database dumps its files:
shell% for issue in `roundup find issue status=in-progress`; do > grep -l spam `roundup get $issue messages` > done msg23 msg49 msg50 msg61 shell%
Or, using the -list option, this can be written as a single command:
shell% grep -l spam `roundup get \ \`roundup find -list issue status=in-progress\` messages` msg23 msg49 msg50 msg61 shell%
7. E-mail User Interface
The Roundup system must be assigned an e-mail address at which to receive mail. Messages should be piped to the Roundup mail-handling script by the mail delivery system (e.g. using an alias beginning with "|" for sendmail).
7.1. Message Processing
Incoming messages are examined for multiple parts. In a multipart/mixed message or part, each subpart is extracted and examined. In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. The text/plain subparts are assembled to form the textual body of the message, to be stored in the file associated with a "msg" class item. Any parts of other types are each stored in separate files and given "file" class items that are linked to the "msg" item.
The "summary" property on message items is taken from the first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin with a ">" or "|" character are considered "quoting sections". The first line of the first non-quoting section becomes the summary of the message.
All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user items, and the corresponding users are placed in the "recipients" property on the new "msg" item. The address in the From: header similarly determines the "author" property of the new "msg" item. The default handling for addresses that don't have corresponding users is to create new users with no passwords and a username equal to the address. (The web interface does not permit logins for users with no passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the "user" class that prevents the creation of user items with no passwords.
The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
If an item designator (class name and id number) is found there, the newly created "msg" item is added to the "messages" property for that item, and any new "file" items are added to the "files" property for the item.
If just an item class name is found there, we attempt to create a new item of that class with its "messages" property initialized to contain the new "msg" item and its "files" property initialized to contain any new "file" items.
Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new item). If an auditor raises an exception, the original message is bounced back to the sender with the explanatory message given in the exception.
7.2. Nosy Lists
A standard detector is provided that watches for additions to the "messages" property. When a new message is added, the detector sends it to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom.
7.3. Setting Properties
The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command.
8. Web User Interface
The web interface is provided by a CGI script that can be run under any web server. A simple web server can easily be built on the standard CGIHTTPServer module, and should also be included in the distribution for quick out-of-the-box deployment.
The user interface is constructed from a number of template files containing mostly HTML. Among the HTML tags in templates are interspersed some nonstandard tags, which we use as placeholders to be replaced by properties and their values.
8.1. Views and View Specifiers
There are two main kinds of views: index views and item views. An index view displays a list of items of a particular class, optionally sorted and filtered as requested. An item view presents the properties of a particular item for editing and displays the message spool for the item.
A view specifier is a string that specifies all the options needed to construct a particular view. It goes after the URL to the Roundup CGI script or the web server to form the complete URL to a view. When the result of selecting a link or submitting a form takes the user to a new view, the Web browser should be redirected to a canonical location containing a complete view specifier so that the view can be bookmarked.
8.2. Displaying Properties
Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field.
The display of a property is handled by functions in a displayers module. Each function accepts at least three standard arguments -- the database, class name, and item id -- and returns a chunk of HTML.
Displayer functions are triggered by <display> tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of
<display call="plain('status', max=30)">
when displaying item 13 in the "issue" class. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized.plain(db, "issue", 13, "status", max=30)
Some of the standard displayer functions include:
- plain: display a String property directly; display a Date property in a specified time zone with an option to omit the time from the date stamp; for a Link or Multilink property, display the key strings of the linked items (or the ids if the linked class has no key property)
- field: display a property like the plain displayer above, but in a text field to be edited
- menu: for a Link property, display a menu of the available choices
- link: for a Link or Multilink property, display the names of the linked items, hyperlinked to the item views on those items
- count: for a Multilink property, display a count of the number of links in the list
- reldate: display a Date property in terms of an interval relative to the current date (e.g. "+ 3w", "- 2d").
- download: show a Link("file") or Multilink("file") property using links that allow you to download files
- checklist: for a Link or Multilink property, display checkboxes for the available choices to permit filtering
8.3. Index Views
An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items.
8.3.1. Index View Specifiers
An index view specifier looks like this (whitespace has been added for clarity):
/issue?status=unread,in-progress,resolved&
topic=security,ui&
:group=+priority&
:sort=-activity&
:filters=status,topic&
:columns=title,status,fixer
The index view is determined by two parts of the specifier: the layout part and the filter part. The layout part consists of the query parameters that begin with colons, and it determines the way that the properties of selected items are displayed. The filter part consists of all the other query parameters, and it determines the criteria by which items are selected for display.
The filter part is interactively manipulated with the form widgets displayed in the filter section. The layout part is interactively manipulated by clicking on the column headings in the table.
The filter part selects the union of the sets of items with values matching any specified Link properties and the intersection of the sets of items with values matching any specified Multilink properties.
The example specifies an index of "issue" items. Only items with a "status" of either "unread" or "in-progres" or "resolved" are displayed, and only items with "topic" values including both "security" and "ui" are displayed. The items are grouped by priority, arranged in ascending order; and within groups, sorted by activity, arranged in descending order. The filter section shows filters for the "status" and "topic" properties, and the table includes columns for the "title", "status", and "fixer" properties.
Associated with each item class is a default layout specifier. The layout specifier in the above example is the default layout to be provided with the default bug-tracker schema described above in section 4.4.
8.3.2. Filter Section
The template for a filter section provides the filtering widgets at the top of the index view. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a filter for a particular property.
Here's a simple example of a filter template.
<property name=status>
<display call="checklist('status')">
</property>
<br>
<property name=priority>
<display call="checklist('priority')">
</property>
<br>
<property name=fixer>
<display call="menu('fixer')">
</property>8.3.3. Index Section
The template for an index section describes one row of the index table. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a column for a particular property. The table cells should contain <display> tags to display the values of the item's properties.
Here's a simple example of an index template.
<tr>
<property name=title>
<td><display call="plain('title', max=50)"></td>
</property>
<property name=status>
<td><display call="plain('status')"></td>
</property>
<property name=fixer>
<td><display call="plain('fixer')"></td>
</property>
</tr>8.3.4. Sorting
String and Date values are sorted in the natural way. Link properties are sorted according to the value of the "order" property on the linked items if it is present; or otherwise on the key string of the linked items; or finally on the item ids. Multilink properties are sorted according to how many links are present.
8.4. Item Views
An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed.
8.4.1. Item View Specifiers
An item view specifier is simply the item's designator:
/patch23
8.4.2. Editor Section
The editor section is generated from a template containing <display> tags to insert the appropriate widgets for editing properties.
Here's an example of a basic editor template.
<table>
<tr>
<td colspan=2>
<display call="field('title', size=60)">
</td>
</tr>
<tr>
<td>
<display call="field('fixer', size=30)">
</td>
<td>
<display call="menu('status')>
</td>
</tr>
<tr>
<td>
<display call="field('nosy', size=30)">
</td>
<td>
<display call="menu('priority')>
</td>
</tr>
<tr>
<td colspan=2>
<display call="note()">
</td>
</tr>
</table>
As shown in the example, the editor template can also request the display of a "note" field, which is a text area for entering a note to go along with a change.
When a change is submitted, the system automatically generates a message describing the changed properties. The message displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this:
title: Polly Parrot is dead priority: critical status: unread -> in-progress fixer: (none) keywords: parrot,plumage,perch,nailed,dead
If a note is given in the "note" field, the note is appended to the description. The message is then added to the item's message spool (thus triggering the standard detector to react by sending out this message to the nosy list).
8.4.3. Spool Section
The spool section lists messages in the item's "messages" property. The index of messages displays the "date", "author", and "summary" properties on the message items, and selecting a message takes you to its content.
9. Deployment Scenarios
The design described above should be general enough to permit the use of Roundup for bug tracking, managing projects, managing patches, or holding discussions. By using items of multiple types, one could deploy a system that maintains requirement specifications, catalogs bugs, and manages submitted patches, where patches could be linked to the bugs and requirements they address.
10. Acknowledgements
My thanks are due to Christy Heyl for reviewing and contributing suggestions to this paper and motivating me to get it done, and to Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for their assistance with the first-round submission.
| [Home] | [FAQ] | [License] | [Rules] | [Configure] | [Build] | [Test] | [Track] | [Resources] | [Archives] |