Mercurial > p > roundup > code
diff doc/index.html @ 653:1dcbee29faa7
More work on the documentation - rolled in the work done by Jeff Blaine.
Use build_html.py *.stx to build the HTML. We'll move that into the setup
script when someone figures how to :)
| author | Richard Jones <richard@users.sourceforge.net> |
|---|---|
| date | Fri, 08 Mar 2002 23:41:46 +0000 |
| parents | f98f37697f4c |
| children |
line wrap: on
line diff
--- a/doc/index.html Wed Feb 27 07:33:34 2002 +0000 +++ b/doc/index.html Fri Mar 08 23:41:46 2002 +0000 @@ -1,1310 +1,42 @@ -<html><head> -<title>Roundup: an Issue-Tracking System for Knowledge Workers</title> -</head><body> - -<h1 align=center>Roundup (0.3.1)</h1> -<h3 align=center>An Issue-Tracking System for Knowledge Workers</h2> - -<h1>Contents</h1> - -<ul> - <li><a href="overview.html">Overview</a> (Initial submission to SC Track) -<li><a href="#installation">Installation</a> - <ul> - <li><a href="#requires">Prerequisites</a> - <li><a href="#getting">Getting Roundup</a> - <li><a href="#installing">Installing Roundup</a> - </ul> -<li><a href="#starting">Getting Started</a> - <ul> - <li><a href="#instance">The Instance</a> - <li><a href="#startcmd">Command Line Tool</a> - <li><a href="#startmail">E-Mail Interface</a> - <li><a href="#startweb">Web Interface</a> - <li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users) - <li><a href="#issues">Issues</a> - </ul> -<li><a href="#guide">User Guide</a> - <ul> - <li><a href="#cmd">Command Line Tool</a> - <li><a href="#web">Web Interface</a> - <li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions) - </ul> -<li><a href="#custom">Customising Roundup</a> - <ul> - <li><a href="#config">Instance Configuration</a> - <li><a href="#custinst">Instance Schema</a> (Creating a new information store) - <li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views) - </ul> -<li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide") -<li><a href="#ack">Acknowledgements</a> -</ul> - -<p><hr> -<h1><a name="installation">Installation</a></h1> - - -<h2><a name="requires">Prerequisites</a></h2> - -<p> -Python 2.1.1 is required for the correct operation of roundup. -</p> - -<p> -Download the latest version from -<a href="http://www.python.org/">http://www.python.org/</a>. -</p> - - - -<h2><a name="getting">Getting Roundup</a></h2> - -Download the latest version from -<a href="http://roundup.sf.net/">http://roundup.sf.net/</a>. - - -<h2><a name="installing">Installing Roundup</a></h2> - -<ol> - <li>Run: - <br><tt>python setup.py install</tt> - <li>If you would prefer the scripts installed in somewhere other than - <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=<dir>"</tt> - to the command: - <br><tt>python setup.py install --install-scripts=<dir></tt> - <li>The command: - <br><tt>python setup.py install --help</tt> - <br>gives all the options available for installation. -</ol> - - -<p><hr> -<h1><a name="starting">Getting Started</a></h1> - -The following instructions assume that you have installed roundup. If you -haven't, you may still proceed - just preface all commands with "./" -ie. "./roundup-admin init". - - -<h2><a name="instance">The Instance</a></h2> - -We'll be referring to the term <em>instance</em> a lot from now on. An -instance is -a directory in your filesystem that is where all the information about a -live issue tracker database is stored. The data that is entered as issues, -the users who access the database and the definition of the database itself -all reside there: -<ol> - <li><strong>Hyperdatabase</strong> - <br>This is the lowest component of Roundup and is where all the - issues, users, file attachments and messages are stored. - <li><strong>Database schema</strong> - <br>This describes the content of the hyperdatabase - what fields are - stored for issues, what user information, etc. Being stored in the - instance, this allows it to be customised for a particular application. - It also means that changes in the Roundup core code do not affect a - running instance. - <li><strong>Web Interface</strong> - <br>The web interface templates are defined in the instance too - and - the actual CGI interface class is defined (mostly using base classes in - the Roundup core code) so it, like the database, may be customised for - each instance in use. -</ol> - -Instances are created using the <tt>roundup-admin</tt> tool. - -<h2><a name="startcmd">Command Line Tool</a></h2> - -To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be -asked a series of questions: - -<ol> - <li>Instance home directory - <li>Schema to use - <li>Database back-end to use - <li>Administration user "admin" password. -</ol> - -You should also think about whether there is going to be controlled access -to the instance on the machine the instance is running on. That is, who can -actually make changes to the database using the roundup-admin tool. See -the section on <a href="#users">Users and Access Control</a> for -information on how to secure your instance from the start. - -<p> - -Roundup is configurable using an instance_config.py file in the instance home. -It should be edited before roundup is used, and may have the following -variable declarations: - -<ol> - <li>MAILHOST - <br>The SMTP mail host that roundup will use to send mail - <li>MAIL_DOMAIN - <br>The domain name used for email addresses - <li>ISSUE_TRACKER_WEB - <br>The web address of the issue tracker's web interface -</ol> - -<p> -The email addresses used by the system by default are: - -<ol> - <li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN - <br>submissions of issues - <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN - <br>roundup's internal use (problems, etc) -</ol> - -<h2><a name="startmail">E-Mail Interface</a></h2> - -<h3>Setup 1: As a mail alias pipe process</h3> -Set up a mail alias called "issue_tracker" as (include the quote marks): -<blockquote> - <tt>"|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>"</tt> -</blockquote> - -In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh -so sendmail will accept the pipe command. In that case, symlink -/etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the -command to: -<blockquote> - <tt>|roundup-mailgw <instance_home></tt> -</blockquote> - -To test the mail gateway on unix systems, try: - -<blockquote> - <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt> -</blockquote> - - -<h3>Setup 2: As a regular cron job using a mailbox source</h3> -Set the roundup-mailgw up to run every 10 minutes or so. For example: -<blockquote> - <tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file></tt> -</blockquote> -Where the mail_spool_file argument is the location of the roundup -submission user's mail spool. On most systems, the spool for a user -"issue_tracker" will be "/var/mail/issue_tracker". - -<h3>Setup 3: As a regular cron job using a POP source</h3> -To retrieve from a POP mailbox, use a similar cron entry to the mailbox -one: -<blockquote> - <tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec></tt> -</blockquote> -where pop_spec is "username:password@server" that specifies the roundup -submission user's POP account name, password and server. - -<h2><a name="startweb">Web Interface</a></h2> -This software will work through apache or stand-alone. -<p> -<strong>Stand-alone:</strong> -<ol> - <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know - about your instance. You may also specify the values for - ROUNDUP_INSTANCE_HOMES on the command-line using "name=home" pairs. - <li><tt>roundup-server [hostname port]</tt> (hostname may be "") - <li>Load up the page <tt>/<instance name>/index</tt> where - instance name is the - name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>. -</ol> - -<strong>Apache:</strong> -<ol> -<li>The CGI script is found in the cgi-bin directory of the roundup - distribution. -</li> -<li>Make sure roundup.cgi is executable. Edit it at the top - - ROUNDUP_INSTANCE_HOMES needs to know about your instance. -</li> -<li>Edit your /etc/httpd/conf/httpd.conf and make sure that the - /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI - script. -</li> -<li>Re-start your apache to re-load the config if necessary. -</li> -<li>Load up the page "/roundup/roundup.cgi/<instance name>/index" where - instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES. -</li> -<li>To use the CGI script unchanged, which allows much easier updates, - add these directives to your "httpd.conf": - <pre> - SetEnv ROUNDUP_LOG "/var/log/roundup.log" - SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default" - SetEnv ROUNDUP_DEBUG "0" -</pre> -</li> -<li>On Windows, write a batch file "roundup.bat" similar to the one below - and place it into your cgi-bin directory: - <pre> - @echo off - set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log - set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default; - set ROUNDUP_DEBUG=0 - c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi -</pre> -</li> -</ol> - - - - -<h2><a name="users">Users</a></h2> - -<h3>Users and permissions</h3> -By default, roundup automatically creates one user when the instance -database is initialised (using roundup-admin init). The user is "admin" and -the password is the one you supply at that time. -<p> -If users attempt to use roundup in any manner and are not identified to -roundup, they will be using the database in a read-only mode. That is, if -roundup doesn't know who they are, they can't change anything. This has the -following repurcussions: -<dl> -<dt><strong>Command-line interface</strong> -<dd>The data modification commands (create, init, retire, set) are -performed as the "admin" user. It is therefore important that the database -be protected by the filesystem if protection is required. On a Unix system, -the easiest and most flexible method of doing so is: -<ol> -<li>Add a new user and group to your system (e.g. "issue_tracker") -<li>When creating a new instance home, use the following commands -(substituting instance_home for the directory you want to use):<br> -<pre> -mkdir instance_home -chown issue_tracker:issue_tracker instance_home -chmod g+rwxs instance_home -roundup-admin -i instance_home init -</pre> -<li>Now, edit the /etc/group line for the issue_tracker group so it includes -the unix logins of all the users who are going to administer your roundup -instance. If you're running the web or mail gateways, then be sure to -include those users in the group too (on some Linux systems, these -users are "www" or "apache" and "mail".) -</ol> - -<dt><strong>E-Mail interface</strong> -<dd>Users are identified by e-mail address - a new user entry will be -created for any e-mail address that is not recognised, so users are -<em>always</em> identified by roundup. -<dt><strong>Web interface</strong> -<dd>Unidentified users have read-only access. If the users database has an -entry with the username "anonymous", then unidentified users are -automatically logged in as that user. This gives them write access. -</dl> -<p> -*** anonymous access and the ANONYMOUS_* configuratins. - -<h3>Adding users</h3> -To add users, use one of the following interfaces: - -<ol> - <li>On the web, access the URL <tt>.../<instance name>/newuser</tt> - to bring up a form which may be used to add a new user. - <li>On the command-line, use: - <br><tt>roundup-admin -i <instance home> create user - username=bozo password=bozo address=richard@clown.org</tt> - <br>Supply the admin username and password. roundup-admin will print the - id of the new user. - <li>Any e-mail sent to roundup from an address that doesn't match an - existing user in the database will result in a new user entry being - created for that user. -</ol> - - - -<h2><a name="issues">Issues</a></h2> -To add issues, use one of the following interfaces: - -<ol> - <li>On the web, access the URL <tt>.../<instance name>/newissue</tt> - to bring up a form which may be used to add a new issue. - <li>On the command-line, use: - <br><tt>roundup-admin -i <instance home> create issue - title="test issue"</tt> - <br>Supply the admin username and password. roundup-admin will print the - id of the new issue. - <li>Any e-mail sent to roundup with the subject line containing [issue] - will automatically created a new issue in the database using the - contents of the e-mail. -</ol> - -<p><hr> -<h1><a name="guide">User Guide</a></h1> -<h2><a name="cmd">Command Line Tool</a></h2> - -Usage: -<tt>roundup-admin [-i instance home] [-u login] [-c] <command> - <arguments></tt> - -<p> -<table><tr><th colspan=2>Options:</th></tr> - <tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer - </td></tr> - <tr><td>-u </td><td>the user[:password] to use for commands - </td></tr> - <tr><td>-c </td><td>when outputting lists of data, just comma-separate them - </td></tr> -</table> - -<p> -<table width=100% border=1 cellspacing=0> -<tr><th colspan=2>Command Help</th></tr> - - -<tr><td valign=top><strong>commit</strong></td> - <td><tt>Usage: commit</tt><p> -<pre> -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. - -</pre></td></tr> - - -<tr><td valign=top><strong>create</strong></td> - <td><tt>Usage: create classname property=value ...</tt><p> -<pre> -This creates a new entry of the given class using the property -name=value arguments provided on the command line after the "create" -command. - -</pre></td></tr> - - -<tr><td valign=top><strong>display</strong></td> - <td><tt>Usage: display designator</tt><p> -<pre> -This lists the properties and their associated values for the given -node. - -</pre></td></tr> - - -<tr><td valign=top><strong>export</strong></td> - <td><tt>Usage: export class[,class] destination_dir</tt><p> -<pre> -This action exports the current data from the database into -tab-separated-value files that are placed in the nominated destination -directory. The journals are not exported. - -</pre></td></tr> - - -<tr><td valign=top><strong>find</strong></td> - <td><tt>Usage: find classname propname=value ...</tt><p> -<pre> -Find the nodes of the given class with a given link property value. The -value may be either the nodeid of the linked node, or its key value. - -</pre></td></tr> - - -<tr><td valign=top><strong>get</strong></td> - <td><tt>Usage: get property designator[,designator]*</tt><p> -<pre> -Retrieves the property value of the nodes specified by the designators. - -</pre></td></tr> - - -<tr><td valign=top><strong>help</strong></td> - <td><tt>Usage: help topic</tt><p> -<pre> -commands -- list commands -<command> -- help specific to a command -initopts -- init command options -all -- all available help - -</pre></td></tr> - - -<tr><td valign=top><strong>history</strong></td> - <td><tt>Usage: history designator</tt><p> -<pre> -Lists the journal entries for the node identified by the designator. - -</pre></td></tr> - - -<tr><td valign=top><strong>import</strong></td> - <td><tt>Usage: import class file</tt><p> -<pre> -The file must define the same properties as the class (including having -a "header" line with those property names.) 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.) - -</pre></td></tr> - - -<tr><td valign=top><strong>initialise</strong></td> - <td><tt>Usage: initialise [template [backend [admin password]]]</tt><p> -<pre> -The command will prompt for the instance home directory (if not supplied -through INSTANCE_HOME or the -i option. The template, backend and admin -password may be specified on the command-line as arguments, in that -order. - -See also initopts help. - -</pre></td></tr> - - -<tr><td valign=top><strong>list</strong></td> - <td><tt>Usage: list classname [property]</tt><p> -<pre> -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. - -</pre></td></tr> - - -<tr><td valign=top><strong>retire</strong></td> - <td><tt>Usage: retire designator[,designator]*</tt><p> -<pre> -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. - -</pre></td></tr> - - -<tr><td valign=top><strong>rollback</strong></td> - <td><tt>Usage: rollback</tt><p> -<pre> -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. - -</pre></td></tr> - - -<tr><td valign=top><strong>set</strong></td> - <td><tt>Usage: set designator[,designator]* propname=value ...</tt><p> -<pre> -Sets the property to the value for all designators given. - -</pre></td></tr> - - -<tr><td valign=top><strong>specification</strong></td> - <td><tt>Usage: specification classname</tt><p> -<pre> -This lists the properties for a given class. - -</pre></td></tr> - - -<tr><td valign=top><strong>table</strong></td> - <td><tt>Usage: table classname [property[,property]*]</tt><p> -<pre> -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 property names. The width may be explicitly defined -by defining the property as "name:width". For example:: - roundup> table priority id,name:10 - Id Name - 1 fatal-bug - 2 bug - 3 usability - 4 feature - -</pre></td></tr> - -</table> - -<p> -All commands (except help) require an instance specifier. This is just the path -to the roundup instance you're working with. A roundup instance is where -roundup keeps the database and configuration file that defines an issue -tracker. It may be thought of as the issue tracker's "home directory". It may -be specified in the environment variable ROUNDUP_INSTANCE or on the command -line as "-i instance". - -<p> -A designator is a classname and a nodeid concatenated, eg. bug1, user10, ... - -<p> -Property values are represented as strings in command arguments and in the -printed results: -<ul> - <li>Strings are, well, strings. - <li>Password values will display as their encoded value. - <li>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 below. -<table> - <tr><th>Input of...</th><th>Means...</th></tr> - <tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr> - <tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr> - <tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr> - <tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr> - <tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr> - <tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr> - <tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr> - <tr><td>"."</td><td>"right now"</td></tr> -</table> - <li>Link values are printed as node designators. When given as an argument, - node designators and key strings are both accepted. - <li>Multilink values are printed as lists of node designators joined by commas. - When given as an argument, node designators and key strings are both - accepted; an empty string, a single node, or a list of nodes joined by - commas is accepted. -</ul> -When multiple nodes are specified to the roundup get or roundup set -commands, the specified properties are retrieved or set on all the listed -nodes. -<p> -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 -c) option. -<p> -Where the command changes data, a login name/password is required. The -login may be specified as either "name" or "name:password". -<ul> - <li>ROUNDUP_LOGIN environment variable - <li>the -u command-line option -</ul> -If either the name or password is not supplied, they are obtained from the -command-line. - -<h2><a name="web">Web Interface</a></h2> -Index views may be modified by the following arguments: -<pre> - :sort - sort by prop name, optionally preceeded with '-' - to give descending or nothing for ascending sorting. - :group - group by prop name, optionally preceeded with '-' or - to sort in descending or nothing for ascending order. - :filter - selects which props should be displayed in the filter - section. Default is all. - :columns - selects the columns that should be displayed. - Default is all. - propname - selects the values the node properties given by propname - must have (very basic search/filter). -</pre> - -<strong>Not sure what to put in here...</strong> - -<h2><a name="mail">E-Mail Gateway</a></h2> - -<h3>Performing Actions</h3> -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). -<p> -If an item designator (class name and id number) is found there, the newly -created "msg" node is added to the "messages" property for that item, and -any new "file" nodes are added to the "files" property for the item. -<p> -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" node and its "files" property initialized to contain any new "file" -nodes. - -<h3>Setting Properties</h3> -The e-mail interface also provides a simple way to set -properties on items. At the end of the subject line, -<em>propname</em><tt>=</tt><em>value</em> pairs can be -specified in square brackets, using the same conventions -as for the <tt>roundup set</tt> shell command. -explanatory message given in the exception. - -<h3>Message content</h3> -Incoming messages are examined for multiple parts: -<ul> -<li>In a multipart/mixed message or part, each subpart is extracted and - examined. 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 node. Any parts of other types are each stored in separate files - and given "file" class nodes that are linked to the "msg" node. -<li>In a multipart/alternative message or part, we look for a text/plain - subpart and ignore the other parts. -</ul> - -<h4>Message summary</h4> -The "summary" property on message nodes 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. - -<h3>Address handling</h3> -All of the addresses in the To: and Cc: headers of the incoming message are -looked up among the user nodes, and the corresponding users are placed in -the "recipients" property on the new "msg" node. The address in the From: -header similarly determines the "author" property of the new "msg" -node. 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 -nodes with no passwords. - -<h3>Triggers</h3> -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 node). If an auditor raises -an exception, the original message is bounced back to the sender with the - -<h4>Nosy Lists</h4> -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. - -<p><hr> -<h1><a name="custom">Customising Roundup</a></h1> - -Instances have the following structure: -<table> - <tr><td valign=top><strong>instance_config.py</strong></td> - <td>Holds the basic <a href="#config">instance configuration</a></td></tr> - <tr><td valign=top><strong>dbinit.py</strong></td> - <td>Holds the <a href="#custinst">instance schema</a></td></tr> - <tr><td valign=top><strong>interfaces.py</strong></td> - <td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr> - <tr><td valign=top><strong>select_db.py</strong></td> - <td>Selects the database back-end for the instance</td></tr> - <tr><td valign=top><strong>db/</strong></td> - <td>Holds the instance's database</td></tr> - <tr><td valign=top><strong>db/files/</strong></td> - <td>Holds the instance's upload files and messages</td></tr> - <tr><td valign=top><strong>detectors/</strong></td> - <td>Auditors and reactors for this instance</td></tr> - <tr><td valign=top><strong>html/</strong></td> - <td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr> -</table> - -<h2><a name="config">Instance Configuration</a></h2> -The <tt>instance_config.py</tt> located in your instance home contains the -basic configuration for the web and e-mail components of roundup's -interfaces. This file is a Python module. The default -<tt>instance_config.py</tt> is given below - as you can see, the -MAIL_DOMAIN must be edited before any interaction with the instance is -attempted. - -<p> -<pre> -MAIL_DOMAIN=MAILHOST=HTTP_HOST=None -HTTP_PORT=0 - -# roundup home is this package's directory -INSTANCE_HOME=os.path.split(__file__)[0] - -# The SMTP mail host that roundup will use to send mail -if not MAILHOST: - MAILHOST = 'localhost' - -# The domain name used for email addresses. -if not MAIL_DOMAIN: - MAIL_DOMAIN = 'fill.me.in.' - -# the next two are only used for the standalone HTTP server. -if not HTTP_HOST: - HTTP_HOST = '' -if not HTTP_PORT: - HTTP_PORT = 9080 - -# This is the directory that the database is going to be stored in -DATABASE = os.path.join(INSTANCE_HOME, 'db') - -# This is the directory that the HTML templates reside in -TEMPLATES = os.path.join(INSTANCE_HOME, 'html') - -# The email address that mail to roundup should go to -ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN - -# The web address that the instance is viewable at -ISSUE_TRACKER_WEB = 'http://some.useful.url/' - -# The email address that roundup will complain to if it runs into trouble -ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN - -# Somewhere for roundup to log stuff internally sent to stdout or stderr -LOG = os.path.join(INSTANCE_HOME, 'roundup.log') - -# Where to place the web filtering HTML on the index page -FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom' - -# Deny or allow anonymous access to the web interface -ANONYMOUS_ACCESS = 'deny' - -# Deny or allow anonymous users to register through the web interface -ANONYMOUS_REGISTER = 'deny' - -# Send nosy messages to the author of the message -MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no' -</pre> - -<h2><a name="custinst">Instance Schema</a></h2> -<b>Note:</b> if you modify the schema, you'll most likely need to -<a href="#schemarepurcussions"> -web interface to reflect your changes</a>. -<p> -An instance schema defines what data is stored in the instance's database. -The two schemas shipped with Roundup turn it into a typical software bug -tracker (the extended schema allowing for support issues as well as bugs). -Schemas are defined using Python code. The "classic" schema looks like -this: -<p> -<pre> - pri = Class(db, "priority", name=String(), order=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=String(), order=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") - - keyword = Class(db, "keyword", name=String()) - keyword.setkey("name") - - user = Class(db, "user", username=String(), password=String(), - address=String(), realname=String(), phone=String(), organisation=String()) - user.setkey("username") - user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL) - - msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"), - date=Date(), summary=String(), files=Multilink("file")) - - file = FileClass(db, "file", name=String(), type=String()) - - issue = IssueClass(db, "issue", assignedto=Link("user"), - topic=Multilink("keyword"), priority=Link("priority"), status=Link("status")) - issue.setkey('title') -</pre> - -<h3>Classes and Properties - creating a new information store</h3> -In the instance above, we've defined 7 <em>classes</em> of information: -<dl> - <dt><strong>priority</strong> - <dd>Defines the possible levels of urgency for issues. - <dt><strong>status</strong> - <dd>Defines the possible states of processing the issue may be in. - <dt><strong>keyword</strong> - <dd>Initially empty, will hold keywords useful for searching issues. - <dt><strong>user</strong> - <dd>Initially holding the "admin" user, will eventually have an entry - for all users using roundup. - <dt><strong>msg</strong> - <dd>Initially empty, will all e-mail messages sent to or generated by roundup. - <dt><strong>file</strong> - <dd>Initially empty, will all files attached to issues. - <dt><strong>issue</strong> - <dd>Initially emtyp, this is where the issue information is stored. -</dl> -<p> -We define the "priority" and "status" classes to allow two things: reduction -in the amount of information stored on the issue and more powerful, accurate -searching of issues by priority and status. By only requiring a link on -the issue (which is stored as a single number) we reduce the chance -that someone mis-types a priority or status - or simply makes a new one -up. - -<h4>Class and Nodes</h4> -A <em>Class</em> defines a particular class (or type) of data that will be -stored in the database. A class comprises one or more properties, which -given the information about the class nodes. -<p> -The actual data entered into the database, using <em>class</em>.create() -are called <em>nodes</em>. They have a special immutable property called -id. We sometimes refer to this as the <em>nodeid</em>. - - -<h4>Properties</h4> -A Class is comprised of one or more <em>properties</em> of the following types: - -<ul> -<li><em>String</em> properties are for storing arbitrary-length -strings. - -<li><em>Password</em> properties are for storing encoded arbitrary-length -strings. The default encoding is defined on the roundup.password.Password -class. - -<li><em>Date</em> properties store date-and-time stamps. -Their values are Timestamp objects. - -<li>A <em>Link</em> property refers to a single other node -selected from a specified class. The class is part of the property; -the value is an integer, the id of the chosen node. - -<li>A <em>Multilink</em> property refers to possibly many nodes -in a specified class. The value is a list of integers. -</ul> - -<h4>FileClass</h4> -FileClasses save their "content" attribute off in a separate file from the -rest of the database. This reduces the number of large entries in the -database, which generally makes databases more efficient, and also allows -us to use command-line tools to operate on the files. They are stored in -the files sub-directory of the db directory in your instance. - -<h4>IssueClass</h4> -IssueClasses automatically include the "messages", "files", "nosy", and -"superseder" properties. -<p> -The messages and files properties list the links to the messages and files -related to the issue. The nosy property is a list of links to users who -wish to be informed of changes to the issue - they get "CC'ed" e-mails when -messages are sent to or generated by the issue. The nosy reactor (in the -detectors directory) handles this action. The superceder link indicates an -issue which has superceded this one. -<p> -They also have the dynamically generated -"creation", "activity" and "creator" properties. -<p> -The value of the "creation" property is the date when a node was created, -and the value of the "activity" property is the date when any property on -the node was last edited (equivalently, these are the dates on the first -and last records in the node's journal). The "creator" property holds a -link to the user that created the issue. - -<h4>setkey(property)</h4> -Select a String property of the class to be the key property. The key -property muse be unique, and allows references to the nodes in the class by -the content of the key property. That is, we can refer to users by their -username, e.g. let's say that there's an issue in roundup, issue 23. There's -also a user, richard who happens to be user 2. To assign an issue to him, -we could do either of: -<p> -<blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote> -<p> -or -<p> -<blockquote><tt>roundup-admin set issue - assignedto=richard</tt></blockquote> -<p> -Note, the same thing can be done in the web and e-mail interfaces. - -<h4>create(information)</h4> -Create a node in the database. This is generally used to create nodes in -the "definitional" classes like "priority" and "status". - - -<h2><a name="custweb">Web Interface</a></h2> - -The web interface works behind the cgi-bin/roundup.cgi or roundup-server -scripts. In both cases, the scripts determine which instance is being -accessed (the first part of the URL path inside the scope of the CGI -handler) and pass control on to the instance interfaces.Client class which -handles the rest of the access through its main() method. This means that -you can do pretty much anything you want as a web interface to your -instance. -<p> -Most customisation of the web view can be done by modifying the templates -in the instance html directory. These are divided into index, item and -newitem views. The newitem view is optional - the item view will be used if -the newitem view doesn't exist. - -<h3><a name="schemarepurcussions">Repurcussions of changing the instance schema</a></h3> - -If you choose to <a href="custinst">change the instance schema</a> you will need to -ensure the web interface knows about it: -<ol> -<li>Index, item and filter pages for the relevant classes may need to have properties -added or removed, -<li>The default page header relies on the existence of, and some values of the -priority, status, assignedto and activity classes. If you change any of these (specifically -if you remove any of the classes or their default values) you will need to implement your -own pagehead() method in your instance's interfaces.py module. -</ol> - - -<h3>Displaying Properties</h3> - -<p> -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. - -<p> -The display of a property is handled by functions in -the htmltemplate module. - -<p> -Displayer functions are triggered by <tt><display></tt> -tags in templates. The <tt>call</tt> 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 - -<blockquote><pre><small -> <display call="plain('status')"> -</small></pre></blockquote> - -in a template triggers a call the "plain" function. 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. - -<p> -<table border=1 cellspacing=0> -<tr><th colspan=2>The displayer functions are</th></tr> - -<tr><td valign="top"><strong>plain</strong></td> -<td>Display a String property directly. -<p> -Display a Date property in a specified time zone with an option -to omit the time from the date stamp. -<p> -For a Link or Multilink -property, display the key strings of the linked nodes (or the -ids if the linked class has no key property). -<p> -<em>Options:</em><br> -escape (boolean) - HTML-escape the resulting text. -</td></tr> - -<tr><td valign="top"><strong>field</strong></td> -<td>Display a property like the -<strong>plain</strong> displayer above, but in a form field -to be edited. Strings, Dates and Intervals use TEXT fields, Links use -SELECT fields and Multilinks use SELECT MULTIPLE fields. -<p> -<em>Options:</em><br> -size (number) - width of TEXT fields.<br> -height (number) - number of nows in SELECT MULTIPLE tags.<br> -showid (boolean) - true includes the id of linked nodes in the SELECT -MULTIPLE fields. -</td></tr> - -<tr><td valign="top"><strong>menu</strong></td> -<td>For a Links and Multilinks, display the same field as would be -generated using <strong>field</strong>. -</td></tr> - -<tr><td valign="top"><strong>link</strong></td> -<td>For a Link or Multilink property, display the names of the linked -nodes, hyperlinked to the item views on those nodes. -<p> -For other properties, link to this node with the property as the text. -<p> -<em>Options:</em><br> -property (property name) - the property to use in the second case. -</td></tr> - -<tr><td valign="top"><strong>count</strong></td> -<td>For a Multilink property, display -a count of the number of links in the list. -<p> -<em>Arguments:</em><br> -property (property name) - the property to use. - -</td></tr> - -<tr><td valign="top"><strong>reldate</strong></td> -<td>Display a Date property in terms -of an interval relative to the current date (e.g. "+ 3w", "- 2d"). -<p> -<em>Arguments:</em><br> -property (property name) - the property to use. -<p> -<em>Options:</em><br> -pretty (boolean) - display the relative date in an English form. -</td></tr> - -<tr><td valign="top"><strong>download</strong></td> -<td>For a Link or Multilink property, display the names of the linked -nodes, hyperlinked to the item views on those nodes. -<p> -For other properties, link to this node with the property as the text. -<p> -In all cases, append the name (key property) of the item to the path so it -is the name of the file being downloaded. -<p> -<em>Arguments:</em><br> -property (property name) - the property to use. -</td></tr> - -<tr><td valign="top"><strong>checklist</strong></td> -<td>For a Link or Multilink property, -display checkboxes for the available choices to permit filtering. -<p> -<em>Arguments:</em><br> -property (property name) - the property to use. -</td></tr> - -<tr><td valign="top"><strong>note</strong></td> -<td>Display the special notes field, which is a text area for entering a -note to go along with a change. -</td></tr> - -<tr><td valign="top"><strong>list</strong></td> -<td>List the nodes specified by property using the standard index for -the class. -<p> -<em>Arguments:</em><br> -property (property name) - the property to use. -</td></tr> - -<tr><td valign="top"><strong>history</strong></td> -<td>List the history of the item. -</td></tr> - -<tr><td valign="top"><strong>submit</strong></td> -<td>Add a submit button for the item. -</td></tr> - -</table> - -<h3>Index Views</h3> - -<p>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. - -<h4>Index View Specifiers</h4> - -<p>An index view specifier (URL fragment) looks like this (whitespace -has been added for clarity): - -<blockquote><pre><small ->/issue?status=unread,in-progress,resolved& - topic=security,ui& - :group=+priority& - :sort=-activity& - :filters=status,topic& - :columns=title,status,fixer -</small></pre></blockquote> - -<p>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 nodes are displayed. -The filter part consists of all the other query parameters, -and it determines the criteria by which nodes -are selected for display. - -<p>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. - -<p>The filter part selects the <em>union</em> of the -sets of items with values matching any specified Link -properties and the <em>intersection</em> of the sets -of items with values matching any specified Multilink -properties. - -<p>The example specifies an index of "issue" nodes. -Only items with a "status" of <em>either</em> -"unread" or "in-progres" or "resolved" are displayed, -and only items with "topic" values including <em>both</em> -"security" <em>and</em> "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. - -<p>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. - -<h4>Filter Section</h4> - -<p>The template for a filter section provides the -filtering widgets at the top of the index view. -Fragments enclosed in <tt><property></tt>...<tt></property></tt> -tags are included or omitted depending on whether the -view specifier requests a filter for a particular property. - -<p>A property must appear in the filter template for it to be available -as a filter. - -<p>Here's a simple example of a filter template. - -<blockquote><pre><small><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></small></pre></blockquote> - -<p> -The standard index generation code appends a section to the index pages -which allows selection of the filters - from those which are defined in the -filter template. - -<h4>Index Section</h4> - -<p>The template for an index section describes one row of -the index table. -Fragments enclosed in <tt><property></tt>...<tt></property></tt> -tags are included or omitted depending on whether the -view specifier requests a column for a particular property. -The table cells should contain <tt><display></tt> tags -to display the values of the item's properties. - -<p>Here's a simple example of an index template. - -<blockquote><pre><small><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></small></pre></blockquote> - -<h4>Sorting</h4> - -<p>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 nodes if it is present; or -otherwise on the key string of the linked nodes; or -finally on the node ids. Multilink properties are -sorted according to how many links are present. - -<h3>Item Views</h3> - -<p>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. - - - -<h4>Editor Section</h4> - -<p>The editor section is generated from a template -containing <tt><display></tt> tags to insert -the appropriate widgets for editing properties. - -<p>Here's an example of a basic editor template. - -<blockquote><pre><small><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> -</small></pre></blockquote> - -<p>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. - -<p>When a change is submitted, the system automatically -generates a message describing the changed properties. - -<p>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). - -<p> -The message also displays all of the property values on the -item and indicates which ones have changed. -An example of such a message might be this: - -<blockquote><pre> -Polly's taken a turn for the worse - this is now really important! ------ -title: Polly Parrot is dead -priority: critical -status: unread -> in-progress -fixer: terry -keywords: parrot,plumage,perch,nailed,dead -</pre></blockquote> - -<h4>Spool Section</h4> - -<p>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 nodes, and selecting a -message takes you to its content. - -<p>The <property> tag used in the index may also be used here - -it checks to see if the nominated Multilink property has any entries. -This can be used to eliminate sections of the spool section if the -property has no entries. - -<blockquote><pre> -<property name="files"> - <tr class="strong-header"> - <td><b>Files</b></td> - </tr> - - <tr> - <td><display call="list('files')"></td> - </tr> -</property> -</pre></blockquote> - -<p><hr> -<h1><a name="ack">Acknowledgements</a></h1> - -Go Ping, you rock! Also, go Bizar Software for letting me implement this -system on their time. - -<p> </p> -<hr> -$Id: index.html,v 1.27 2002-01-23 05:10:27 richard Exp $ -<p> </p> - -</body></html> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<HTML LANG="en"> +<HEAD> +<LINK REL="StyleSheet" HREF="default.css" TYPE="text/css"></HEAD> +<BODY> +<DIV CLASS="document"> +<P><EM>Roundup: an Issue-Tracking System for Knowledge Workers</EM></P> +<DIV CLASS="section" ID="id1"> +<H1>Contents</H1> +<UL> +<LI> +<P><A CLASS="reference" HREF="overview.html">Overview</A></P> +</LI> +<LI> +<P><A CLASS="reference" HREF="installation.html">Installation</A></P> +</LI> +<LI> +<P><A CLASS="reference" HREF="getting_started.html">Getting Started</A></P> +</LI> +<LI> +<P><A CLASS="reference" HREF="user_guide.html">User Guide</A></P> +</LI> +<LI> +<P><A CLASS="reference" HREF="customizing.html">Customising Roundup</A></P> +</LI> +<LI> +<P><A CLASS="reference" HREF="spec.html">Roundup's Design Document</A></P> +</LI> +</UL> +</A></A></A></A></A></A></DIV> +<DIV CLASS="section" ID="id8"> +<H1>Acknowledgements</H1> +<P>Go Ping, you rock! Also, go Bizar Software and ekit.com for letting me +implement this system on their time.</P> +<P>Thanks also to the many people on the mailing list and in the sourceforge +project: Anthony Baxter, Juergen Hermann, Roch'e Compaan, Engelbert Gruber, +Titus Brown, Jeff Blaine and Patrick Ohly.</P> +</DIV> +</DIV> +</BODY> +</HTML>