Mercurial > p > roundup > code
view doc/index.html @ 255:d4ef19ef17bd
Bug fix for test_init on Windows.
More documenation!!
| author | Richard Jones <richard@users.sourceforge.net> |
|---|---|
| date | Sat, 29 Sep 2001 23:48:06 +0000 |
| parents | af6e10660e27 |
| children | 0fb85acfa9e4 |
line wrap: on
line source
<html><head> <title>Roundup: an Issue-Tracking System for Knowledge Workers</title> </head><body> <h1 align=center>Roundup</h1> <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3> <h2>Contents</h2> <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="#startweb">E-Mail Interface</a> <li><a href="#startweb">Web Interface</a> <li><a href="#users">Users</a> <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> </ul> <li><a href="#custom">Customising Roundup</a> <ul> <li><a href="#custinst">Instance Schema</a> <li><a href="#custweb">Web Interface</a> </ul> <li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide") <li><a href="#ack">Acknowledgements</a> </ul> <p><hr> <h2><a name="installation">Installation</a></h2> <h3><a name="requires">Prerequisites</a></h3> <dl> <dt>Either: <dd>Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc. <dt>or <dd>Python 2.1 or later </dl> Download the latest version from <a href="http://www.python.org/">http://www.python.org/</a>. <h3><a name="getting">Getting Roundup</a></h3> Download the latest version from <a href="http://roundup.sf.net/">http://roundup.sf.net/</a>. <h3><a name="installing">Installing Roundup</a></h3> <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> <h2><a name="starting">Getting Started</a></h2> 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". <h3><a name="instance">The Instance</a></h3> 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. <h3><a name="startcmd">Command Line Tool</a></h3> 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> Roundup is configurable using a localconfig.py file in the instance home. It 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 </ol> Any further configuration should be possible by editing the instance home's __init__.py directly. <p> The email addresses used by the system by default are: <ol> <li>issue_tracker@MAIL_DOMAIN <br>submissions of issues <li>roundup-admin@MAIL_DOMAIN <br>roundup's internal use (problems, etc) </ol> <em>Note:</em> We run the instance as group "issue_tracker" and add the mail and web user ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as any admin people. <h3><a name="startweb">E-Mail Interface</a></h3> Set up a mail alias called "issue_tracker" as: <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><a name="startweb">Web Interface</a></h3> 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. *** command-line option <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>. *** command-line option </ol> <strong>Apache:</strong> <ol> <li>Make sure roundup.cgi is executable. Edit it at the top - ROUNDUP_INSTANCE_HOMES needs to know about your instance. <li>Edit your <tt>/etc/httpd/conf/httpd.conf</tt> and make sure that the <tt>/home/httpd/html/roundup/roundup.cgi</tt> script will be treated as a CGI script. <li>Add the following to your <tt>/etc/httpd/conf/httpd.conf</tt>: <pre> ------8<------- snip here ------8<------- RewriteEngine on RewriteCond %{HTTP:Authorization} ^(.*) RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l] ------8<------- snip here ------8<------- </pre> note: the RewriteRule must be on one line - no breaks <li>Re-start your apache to re-load the config <li>Load up the page <tt>/roundup/roundup.cgi/<instance name>/index</tt> where instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES. </ol> <h3><a name="users">Users</a></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> <h3><a name="issues">Issues</a></h3> 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> <h2><a name="guide">User Guide</a></h2> <h3><a name="cmd">Command Line Tool</a></h3> 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 border=1 cellspacing=0> <tr><th colspan=2>Command Help</th></tr> <tr><td valign=top><strong>history</strong></td> <td><tt>history designator</tt><br> Lists the journal entries for the node identified by the designator. </td></tr> <tr><td valign=top><strong>find</strong></td> <td><tt>find classname propname=value ...</tt><br> Find the nodes of the given class with a given property value. The value may be either the nodeid of the linked node, or its key value. </td></tr> <tr><td valign=top><strong>list</strong></td> <td><tt>list classname [property]</tt><br> Lists all instances of the given class along. 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. </td></tr> <tr><td valign=top><strong>retire</strong></td> <td><tt>retire designator[,designator]*</tt><br> 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. </td></tr> <tr><td valign=top><strong>create</strong></td> <td><tt>create classname property=value ...</tt><br> This creates a new entry of the given class using the property name=value arguments provided on the command line after the "create" command. </td></tr> <tr><td valign=top><strong>get</strong></td> <td><tt>get property designator[,designator]*</tt><br> Retrieves the property value of the nodes specified by the designators. </td></tr> <tr><td valign=top><strong>spec</strong></td> <td><tt>spec classname</tt><br> This lists the properties for a given class. </td></tr> <tr><td valign=top><strong>set</strong></td> <td><tt>set designator[,designator]* propname=value ...</tt><br> Sets the property to the value for all designators given. </td></tr> <tr><td valign=top><strong>init</strong></td> <td><tt>init [template [backend [admin password]]]</tt><br> 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. </td></tr> <tr><td valign=top><strong>freshen</strong></td> <td><tt>freshen</tt><br> <strong>**DO NOT USE**</strong> <p> This currently kills databases!!!! <p> This action should generally not be used. It reads in an instance database and writes it again. In the future, is may also update instance code to account for changes in templates. It's probably wise not to use it anyway. Until we're sure it won't break things... </td></tr> <tr><td><strong>help</strong></td> <td><tt>help [command]</tt><br> Short help about roundup-admin or the specific command. </td></tr> <tr><td><strong>morehelp</strong></td> <td><tt>morehelp</tt><br> All available help from the roundup-admin tool. </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>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. <h3><a name="web">Web Interface</a></h3> T.B.D. <h3><a name="mail">E-Mail Gateway</a></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>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. <h4>Addresses</h4> 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. <h4>Actions</h4> 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" node is added to the "messages" property for that item, and any new "file" nodes 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" node and its "files" property initialized to contain any new "file" nodes. <h4>Triggers</h4> 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 explanatory message given in the exception. <p><hr> <h2><a name="custom">Customising Roundup</a></h2> Instances have the following structure: <table> <tr><td valign=top><strong>dbinit.py</strong></td> <td>Holds the instance schema</td></tr> <tr><td valign=top><strong>instance_config.py</strong></td> <td>Holds the basic instance configuration</td></tr> <tr><td valign=top><strong>interfaces.py</strong></td> <td>Defines the Web 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 templates, images and style sheets</td></tr> </table> <h3><a name="custinst">Instance Schema</a></h3> 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> <h4>Class, FileClass, IssueClass - creating a new information store</h4> A <em>Class</em> defines a particular class (or type) of data that will be stored in the database. In the instance above, we've defined 7 classes 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. <p> <strong>Class</strong> <br> Class is the basic store of information. <p> <strong>FileClass</strong> <br> 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. <p> <strong>IssueClass</strong> <br> 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 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). 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 items 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 an item in the database. This is generally used to create items in the "definitional" classes like "priority" and "status". <h3><a name="custweb">Web Interface</a></h3> <p><hr> <h2><a name="ack">Acknowledgements</a></h2> 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.4 2001-09-29 23:48:06 richard Exp $ <p> </p> </body></html>