doc/index.html

   1 <html><head>
   2 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
   3 </head><body>
   4
   5 <h1 align=center>Roundup (0.3.0)</h1>
   6 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h2>
   7
   8 <h1>Contents</h1>
   9
  10 <ul>
  11     <li><a href="overview.html">Overview</a> (Initial submission to SC Track)
  12 <li><a href="#installation">Installation</a>
  13     <ul>
  14         <li><a href="#requires">Prerequisites</a>
  15         <li><a href="#getting">Getting Roundup</a>
  16         <li><a href="#installing">Installing Roundup</a>
  17     </ul>
  18 <li><a href="#starting">Getting Started</a>
  19     <ul>
  20         <li><a href="#instance">The Instance</a>
  21         <li><a href="#startcmd">Command Line Tool</a>
  22         <li><a href="#startweb">E-Mail Interface</a>
  23         <li><a href="#startweb">Web Interface</a>
  24         <li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users)
  25         <li><a href="#issues">Issues</a>
  26     </ul>
  27 <li><a href="#guide">User Guide</a>
  28     <ul>
  29         <li><a href="#cmd">Command Line Tool</a>
  30         <li><a href="#web">Web Interface</a>
  31         <li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions)
  32     </ul>
  33 <li><a href="#custom">Customising Roundup</a>
  34     <ul>
  35         <li><a href="#config">Instance Configuration</a>
  36         <li><a href="#custinst">Instance Schema</a> (Creating a new information store)
  37         <li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views)
  38     </ul>
  39 <li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
  40 <li><a href="#ack">Acknowledgements</a>
  41 </ul>
  42
  43 <p><hr>
  44 <h1><a name="installation">Installation</a></h1>
  45
  46
  47 <h2><a name="requires">Prerequisites</a></h2>
  48
  49 <dl>
  50         <dd>Python 2.1.1 is required for the correct operation of roundup
  51 </dl>
  52
  53 Download the latest version from
  54 <a href="http://www.python.org/">http://www.python.org/</a>.
  55
  56
  57
  58 <h2><a name="getting">Getting Roundup</a></h2>
  59
  60 Download the latest version from
  61 <a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
  62
  63
  64 <h2><a name="installing">Installing Roundup</a></h2>
  65
  66 <ol>
  67     <li>Run:
  68     <br><tt>python setup.py install</tt>
  69     <li>If you would prefer the scripts installed in somewhere other than
  70     <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=&lt;dir&gt;"</tt>
  71     to the command:
  72     <br><tt>python setup.py install --install-scripts=&lt;dir&gt;</tt>
  73     <li>The command:
  74     <br><tt>python setup.py install --help</tt>
  75     <br>gives all the options available for installation.
  76 </ol>
  77
  78
  79 <p><hr>
  80 <h1><a name="starting">Getting Started</a></h1>
  81
  82 The following instructions assume that you have installed roundup. If you
  83 haven't, you may still proceed - just preface all commands with "./"
  84 ie. "./roundup-admin init".
  85
  86
  87 <h2><a name="instance">The Instance</a></h2>
  88
  89 We'll be referring to the term <em>instance</em> a lot from now on. An
  90 instance is
  91 a directory in your filesystem that is where all the information about a
  92 live issue tracker database is stored. The data that is entered as issues,
  93 the users who access the database and the definition of the database itself
  94 all reside there:
  95 <ol>
  96     <li><strong>Hyperdatabase</strong>
  97     <br>This is the lowest component of Roundup and is where all the
  98     issues, users, file attachments and messages are stored.
  99     <li><strong>Database schema</strong>
 100     <br>This describes the content of the hyperdatabase - what fields are
 101     stored for issues, what user information, etc. Being stored in the
 102     instance, this allows it to be customised for a particular application.
 103     It also means that changes in the Roundup core code do not affect a
 104     running instance.
 105     <li><strong>Web Interface</strong>
 106     <br>The web interface templates are defined in the instance too - and
 107     the actual CGI interface class is defined (mostly using base classes in
 108     the Roundup core code) so it, like the database, may be customised for
 109     each instance in use.
 110 </ol>
 111
 112 Instances are created using the <tt>roundup-admin</tt> tool.
 113
 114 <h2><a name="startcmd">Command Line Tool</a></h2>
 115
 116 To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
 117 asked a series of questions:
 118
 119 <ol>
 120     <li>Instance home directory
 121     <li>Schema to use
 122     <li>Database back-end to use
 123     <li>Administration user "admin" password.
 124 </ol>
 125
 126 You should also think about whether there is going to be controlled access
 127 to the instance on the machine the instance is running on. That is, who can
 128 actually make changes to the database using the roundup-admin tool. See
 129 the section on <a href="#users">Users and Access Control</a> for
 130 information on how to secure your instance from the start.
 131
 132 <p>
 133
 134 Roundup is configurable using an instance_config.py file in the instance home.
 135 It should be edited before roundup is used, and may have the following
 136 variable declarations:
 137
 138 <ol>
 139     <li>MAILHOST
 140     <br>The SMTP mail host that roundup will use to send mail
 141     <li>MAIL_DOMAIN
 142     <br>The domain name used for email addresses
 143     <li>ISSUE_TRACKER_WEB
 144     <br>The web address of the issue tracker's web interface
 145 </ol>
 146
 147 <p>
 148 The email addresses used by the system by default are:
 149
 150 <ol>
 151     <li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
 152     <br>submissions of issues
 153     <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
 154     <br>roundup's internal use (problems, etc)
 155 </ol>
 156
 157 <h2><a name="startweb">E-Mail Interface</a></h2>
 158
 159 <h3>Setup 1: As a mail alias pipe process</h3>
 160 Set up a mail alias called "issue_tracker" as (include the quote marks):
 161 <blockquote>
 162     <tt>"|/usr/bin/python /usr/local/bin/roundup-mailgw &lt;instance_home&gt;"</tt>
 163 </blockquote>
 164
 165 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
 166 so sendmail will accept the pipe command. In that case, symlink
 167 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
 168 command to:
 169 <blockquote>
 170     <tt>|roundup-mailgw &lt;instance_home&gt;</tt>
 171 </blockquote>
 172
 173 To test the mail gateway on unix systems, try:
 174
 175 <blockquote>
 176     <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
 177 </blockquote>
 178
 179
 180 <h3>Setup 2: As a regular cron job</h3>
 181
 182 Set the roundup-mailgw up to run every 10 minutes or so. For example:
 183 <blockquote>
 184  <tt>10 * * * * /usr/local/bin/roundup-mailgw &lt;instance_home&gt; &lt;mail_spool_file&gt;</tt>
 185 </blockquote>
 186
 187 Where the mail_spool_file argument is the location of the roundup
 188 submission user's mail spool. On most systems, the spool for a user
 189 "issue_tracker" will be "/var/mail/issue_tracker".
 190
 191
 192 <h2><a name="startweb">Web Interface</a></h2>
 193 This software will work through apache or stand-alone.
 194 <p>
 195 <strong>Stand-alone:</strong>
 196 <ol>
 197     <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
 198     about your instance. *** command-line option
 199     <li><tt>roundup-server [hostname port]</tt>   (hostname may be "")
 200     <li>Load up the page <tt>/&lt;instance name&gt;/index</tt> where
 201      instance name is the
 202      name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
 203 *** command-line option
 204 </ol>
 205
 206 <strong>Apache:</strong>
 207 <ol>
 208 <li>The CGI script is found in the cgi-bin directory of the roundup
 209     distribution.
 210 </li>
 211 <li>Make sure roundup.cgi is executable. Edit it at the top -
 212     ROUNDUP_INSTANCE_HOMES needs to know about your instance.
 213 </li>
 214 <li>Edit your /etc/httpd/conf/httpd.conf and make sure that the
 215     /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
 216     script.
 217 </li>
 218 <li>Re-start your apache to re-load the config if necessary.
 219 </li>
 220 <li>Load up the page "/roundup/roundup.cgi/<instance name>/index" where
 221     instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
 222 </li>
 223 <li>To use the CGI script unchanged, which allows much easier updates,
 224     add these directives to your "httpd.conf":
 225     <pre>
 226         SetEnv ROUNDUP_LOG "/var/log/roundup.log"
 227         SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
 228         SetEnv ROUNDUP_DEBUG "0"
 229 </pre>
 230 </li>
 231 <li>On Windows, write a batch file "roundup.bat" similar to the one below
 232     and place it into your cgi-bin directory:
 233     <pre>
 234         @echo off
 235         set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
 236         set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
 237         set ROUNDUP_DEBUG=0
 238         c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
 239 </pre>
 240 </li>
 241 </ol>
 242
 243
 244
 245
 246 <h2><a name="users">Users</a></h2>
 247
 248 <h3>Users and permissions</h3>
 249 By default, roundup automatically creates one user when the instance
 250 database is initialised (using roundup-admin init). The user is "admin" and
 251 the password is the one you supply at that time.
 252 <p>
 253 If users attempt to use roundup in any manner and are not identified to
 254 roundup, they will be using the database in a read-only mode. That is, if
 255 roundup doesn't know who they are, they can't change anything. This has the
 256 following repurcussions:
 257 <dl>
 258 <dt><strong>Command-line interface</strong>
 259 <dd>The data modification commands (create, init, retire, set) are
 260 performed as the "admin" user. It is therefore important that the database
 261 be protected by the filesystem if protection is required. On a Unix system,
 262 the easiest and most flexible method of doing so is:
 263 <ol>
 264 <li>Add a new user and group to your system (e.g. "issue_tracker")
 265 <li>When creating a new instance home, use the following commands
 266 (substituting instance_home for the directory you want to use):<br>
 267 <pre>
 268 mkdir instance_home
 269 chown issue_tracker:issue_tracker instance_home
 270 chmod g+rwxs instance_home
 271 roundup-admin -i instance_home init
 272 </pre>
 273 <li>Now, edit the /etc/group line for the issue_tracker group so it includes
 274 the unix logins of all the users who are going to administer your roundup
 275 instance. If you're running the web or mail gateways, then be sure to
 276 include those users in the group too (on some Linux systems, these
 277 users are "www" or "apache" and "mail".)
 278 </ol>
 279
 280 <dt><strong>E-Mail interface</strong>
 281 <dd>Users are identified by e-mail address - a new user entry will be
 282 created for any e-mail address that is not recognised, so users are
 283 <em>always</em> identified by roundup.
 284 <dt><strong>Web interface</strong>
 285 <dd>Unidentified users have read-only access. If the users database has an
 286 entry with the username "anonymous", then unidentified users are
 287 automatically logged in as that user. This gives them write access.
 288 </dl>
 289 <p>
 290 *** anonymous access and the ANONYMOUS_* configuratins.
 291
 292 <h3>Adding users</h3>
 293 To add users, use one of the following interfaces:
 294
 295 <ol>
 296     <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newuser</tt>
 297     to bring up a form which may be used to add a new user.
 298     <li>On the command-line, use:
 299     <br><tt>roundup-admin -i &lt;instance home&gt; create user
 300         username=bozo password=bozo address=richard@clown.org</tt>
 301     <br>Supply the admin username and password. roundup-admin will print the
 302     id of the new user.
 303     <li>Any e-mail sent to roundup from an address that doesn't match an
 304     existing user in the database will result in a new user entry being
 305     created for that user.
 306 </ol>
 307
 308
 309
 310 <h2><a name="issues">Issues</a></h2>
 311 To add issues, use one of the following interfaces:
 312
 313 <ol>
 314     <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newissue</tt>
 315     to bring up a form which may be used to add a new issue.
 316     <li>On the command-line, use:
 317     <br><tt>roundup-admin -i &lt;instance home&gt; create issue
 318         title="test issue"</tt>
 319     <br>Supply the admin username and password. roundup-admin will print the
 320     id of the new issue.
 321     <li>Any e-mail sent to roundup with the subject line containing [issue]
 322     will automatically created a new issue in the database using the
 323     contents of the e-mail.
 324 </ol>
 325
 326 <p><hr>
 327 <h1><a name="guide">User Guide</a></h1>
 328 <h2><a name="cmd">Command Line Tool</a></h2>
 329
 330 Usage:
 331 <tt>roundup-admin [-i instance home] [-u login] [-c] &lt;command&gt;
 332     &lt;arguments&gt;</tt>
 333
 334 <p>
 335 <table><tr><th colspan=2>Options:</th></tr>
 336    <tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer
 337    </td></tr>
 338    <tr><td>-u               </td><td>the user[:password] to use for commands
 339    </td></tr>
 340    <tr><td>-c               </td><td>when outputting lists of data, just comma-separate them
 341     </td></tr>
 342 </table>
 343
 344 <p>
 345 <table border=1 cellspacing=0>
 346 <tr><th colspan=2>Command Help</th></tr>
 347 <tr><td valign=top><strong>history</strong></td>
 348     <td><tt>history designator</tt><p>
 349     Lists the journal entries for the node identified by the designator.
 350 </td></tr>
 351
 352 <tr><td valign=top><strong>find</strong></td>
 353     <td><tt>find classname propname=value ...</tt><p>
 354     Find the nodes of the given class with a given property value. The
 355     value may be either the nodeid of the linked node, or its key value.
 356 </td></tr>
 357
 358 <tr><td valign=top><strong>list</strong></td>
 359     <td><tt>list classname [property]</tt><p>
 360     Lists all instances of the given class along. If the property is not
 361     specified, the  "label" property is used. The label property is tried
 362     in order: the key, "name", "title" and then the first property,
 363     alphabetically.
 364 </td></tr>
 365
 366 <tr><td valign=top><strong>retire</strong></td>
 367     <td><tt>retire designator[,designator]*</tt><p>
 368     This action indicates that a particular node is not to be retrieved by
 369     the list or find commands, and its key value may be re-used.
 370 </td></tr>
 371
 372 <tr><td valign=top><strong>create</strong></td>
 373     <td><tt>create classname property=value ...</tt><p>
 374     This creates a new entry of the given class using the property
 375     name=value arguments provided on the command line after the "create"
 376     command.
 377 </td></tr>
 378
 379 <tr><td valign=top><strong>get</strong></td>
 380     <td><tt>get property designator[,designator]*</tt><p>
 381     Retrieves the property value of the nodes specified by the designators.
 382 </td></tr>
 383
 384 <tr><td valign=top><strong>spec</strong></td>
 385     <td><tt>spec classname</tt><p>
 386     This lists the properties for a given class.
 387 </td></tr>
 388
 389 <tr><td valign=top><strong>set</strong></td>
 390     <td><tt>set designator[,designator]* propname=value ...</tt><p>
 391     Sets the property to the value for all designators given.
 392 </td></tr>
 393
 394 <tr><td valign=top><strong>init</strong></td>
 395     <td><tt>init [template [backend [admin password]]]</tt><p>
 396     The command will prompt for the instance home directory (if not supplied
 397     through INSTANCE_HOME or the -i option. The template, backend and admin
 398     password may be specified on the command-line as arguments, in that order.
 399 </td></tr>
 400
 401 <tr><td valign=top><strong>export</strong></td>
 402     <td><tt>export class[,class] destination_dir</tt><p>
 403     This action exports the current data from the database into
 404     comma-separated files that are placed in the nominated destination
 405     directory. The journals are not exported.
 406 </td></tr>
 407
 408 <tr><td valign=top><strong>import</strong></td>
 409     <td><tt>import class file</tt><p>
 410     The file must define the same properties as the class (including having
 411     a "header" line with those property names.)
 412 </td></tr>
 413
 414 <tr><td valign=top><strong>freshen</strong></td>
 415     <td><tt>freshen</tt><p>
 416         <strong>**DO NOT USE**</strong>
 417         <p>
 418     This currently kills databases!!!!
 419     <p>
 420     This action should generally not be used. It reads in an instance
 421     database and writes it again. In the future, is may also update
 422     instance code to account for changes in templates. It's probably wise
 423     not to use it anyway. Until we're sure it won't break things...
 424 </td></tr>
 425
 426 <tr><td><strong>help</strong></td>
 427     <td><tt>help [command]</tt><p>
 428     Short help about roundup-admin or the specific command.
 429     </td></tr>
 430
 431 <tr><td><strong>morehelp</strong></td>
 432     <td><tt>morehelp</tt><p>
 433     All available help from the roundup-admin tool.
 434     </td></tr>
 435 </table>
 436
 437 <p>
 438 All commands (except help) require an instance specifier. This is just the path
 439 to the roundup instance you're working with. A roundup instance is where
 440 roundup keeps the database and configuration file that defines an issue
 441 tracker. It may be thought of as the issue tracker's "home directory". It may
 442 be specified in the environment variable ROUNDUP_INSTANCE or on the command
 443 line as "-i instance".
 444
 445 <p>
 446 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
 447
 448 <p>
 449 Property values are represented as strings in command arguments and in the
 450 printed results:
 451 <ul>
 452     <li>Strings are, well, strings.
 453     <li>Password values will display as their encoded value.
 454     <li>Date values are printed in the full date format in the local time zone, and
 455    accepted in the full format or any of the partial formats explained below.
 456 <table>
 457     <tr><th>Input of...</th><th>Means...</th></tr>
 458     <tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr>
 459     <tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr>
 460     <tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr>
 461     <tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr>
 462     <tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr>
 463     <tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr>
 464     <tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr>
 465     <tr><td>"."</td><td>"right now"</td></tr>
 466 </table>
 467    <li>Link values are printed as node designators. When given as an argument,
 468    node designators and key strings are both accepted.
 469    <li>Multilink values are printed as lists of node designators joined by commas.
 470    When given as an argument, node designators and key strings are both
 471    accepted; an empty string, a single node, or a list of nodes joined by
 472    commas is accepted.
 473 </ul>
 474 When multiple nodes are specified to the roundup get or roundup set
 475 commands, the specified properties are retrieved or set on all the listed
 476 nodes.
 477 <p>
 478 When multiple results are returned by the roundup get or roundup find
 479 commands, they are printed one per line (default) or joined by commas (with
 480 the -c) option.
 481 <p>
 482 Where the command changes data, a login name/password is required. The
 483 login may be specified as either "name" or "name:password".
 484 <ul>
 485     <li>ROUNDUP_LOGIN environment variable
 486     <li>the -u command-line option
 487 </ul>
 488 If either the name or password is not supplied, they are obtained from the
 489 command-line.
 490
 491 <h2><a name="web">Web Interface</a></h2>
 492 Index views may be modified by the following arguments:
 493 <pre>
 494     :sort    - sort by prop name, optionally preceeded with '-'
 495              to give descending or nothing for ascending sorting.
 496     :group   - group by prop name, optionally preceeded with '-' or
 497              to sort in descending or nothing for ascending order.
 498     :filter  - selects which props should be displayed in the filter
 499              section. Default is all.
 500     :columns - selects the columns that should be displayed.
 501              Default is all.
 502     propname - selects the values the node properties given by propname
 503              must have (very basic search/filter).
 504 </pre>
 505
 506 <strong>Not sure what to put in here...</strong>
 507
 508 <h2><a name="mail">E-Mail Gateway</a></h2>
 509
 510 <h3>Performing Actions</h3>
 511 The subject line of the incoming message is examined to determine whether
 512 the message is an attempt to create a new item or to discuss an existing
 513 item. A designator enclosed in square brackets is sought as the first thing
 514 on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
 515 <p>
 516 If an item designator (class name and id number) is found there, the newly
 517 created "msg" node is added to the "messages" property for that item, and
 518 any new "file" nodes are added to the "files" property for the item.
 519 <p>
 520 If just an item class name is found there, we attempt to create a new item
 521 of that class with its "messages" property initialized to contain the new
 522 "msg" node and its "files" property initialized to contain any new "file"
 523 nodes.
 524
 525 <h3>Setting Properties</h3>
 526 The e-mail interface also provides a simple way to set
 527 properties on items.  At the end of the subject line,
 528 <em>propname</em><tt>=</tt><em>value</em> pairs can be
 529 specified in square brackets, using the same conventions
 530 as for the <tt>roundup&nbsp;set</tt> shell command.
 531 explanatory message given in the exception.
 532
 533 <h3>Message content</h3>
 534 Incoming messages are examined for multiple parts:
 535 <ul>
 536 <li>In a multipart/mixed message or part, each subpart is extracted and
 537    examined. The text/plain subparts are assembled to form the textual
 538    body of the message, to be stored in the file associated with a "msg"
 539    class node. Any parts of other types are each stored in separate files
 540    and given "file" class nodes that are linked to the "msg" node.
 541 <li>In a multipart/alternative message or part, we look for a text/plain
 542    subpart and ignore the other parts.
 543 </ul>
 544
 545 <h4>Message summary</h4>
 546 The "summary" property on message nodes is taken from the first non-quoting
 547 section in the message body. The message body is divided into sections by
 548 blank lines. Sections where the second and all subsequent lines begin with
 549 a "&gt;" or "|" character are considered "quoting sections". The first line of
 550 the first non-quoting section becomes the summary of the message.
 551
 552 <h3>Address handling</h3>
 553 All of the addresses in the To: and Cc: headers of the incoming message are
 554 looked up among the user nodes, and the corresponding users are placed in
 555 the "recipients" property on the new "msg" node. The address in the From:
 556 header similarly determines the "author" property of the new "msg"
 557 node. The default handling for addresses that don't have corresponding
 558 users is to create new users with no passwords and a username equal to the
 559 address. (The web interface does not permit logins for users with no
 560 passwords.) If we prefer to reject mail from outside sources, we can simply
 561 register an auditor on the "user" class that prevents the creation of user
 562 nodes with no passwords.
 563
 564 <h3>Triggers</h3>
 565 Both cases may trigger detectors (in the first case we are calling the
 566 set() method to add the message to the item's spool; in the second case we
 567 are calling the create() method to create a new node). If an auditor raises
 568 an exception, the original message is bounced back to the sender with the
 569
 570 <h4>Nosy Lists</h4>
 571 A standard detector is provided that watches for additions
 572 to the "messages" property.  When a new message is added, the
 573 detector sends it to all the users on the "nosy" list for the
 574 item that are not already on the "recipients" list of the
 575 message.  Those users are then appended to the "recipients"
 576 property on the message, so multiple copies of a message
 577 are never sent to the same user.  The journal recorded by
 578 the hyperdatabase on the "recipients" property then provides
 579 a log of when the message was sent to whom.
 580
 581 <p><hr>
 582 <h1><a name="custom">Customising Roundup</a></h1>
 583
 584 Instances have the following structure:
 585 <table>
 586     <tr><td valign=top><strong>instance_config.py</strong></td>
 587     <td>Holds the basic <a href="#config">instance configuration</a></td></tr>
 588     <tr><td valign=top><strong>dbinit.py</strong></td>
 589         <td>Holds the <a href="#custinst">instance schema</a></td></tr>
 590     <tr><td valign=top><strong>interfaces.py</strong></td>
 591     <td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr>
 592     <tr><td valign=top><strong>select_db.py</strong></td>
 593         <td>Selects the database back-end for the instance</td></tr>
 594     <tr><td valign=top><strong>db/</strong></td>
 595         <td>Holds the instance's database</td></tr>
 596     <tr><td valign=top><strong>db/files/</strong></td>
 597         <td>Holds the instance's upload files and messages</td></tr>
 598     <tr><td valign=top><strong>detectors/</strong></td>
 599         <td>Auditors and reactors for this instance</td></tr>
 600     <tr><td valign=top><strong>html/</strong></td>
 601     <td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr>
 602 </table>
 603
 604 <h2><a name="config">Instance Configuration</a></h2>
 605 The <tt>instance_config.py</tt> located in your instance home contains the
 606 basic configuration for the web and e-mail components of roundup's
 607 interfaces. This file is a Python module. The default
 608 <tt>instance_config.py</tt> is given below - as you can see, the
 609 MAIL_DOMAIN must be edited before any interaction with the instance is
 610 attempted.
 611
 612 <p>
 613 <pre>
 614 MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
 615 HTTP_PORT=0
 616
 617 # roundup home is this package's directory
 618 INSTANCE_HOME=os.path.split(__file__)[0]
 619
 620 # The SMTP mail host that roundup will use to send mail
 621 if not MAILHOST:
 622     MAILHOST = 'localhost'
 623
 624 # The domain name used for email addresses.
 625 if not MAIL_DOMAIN:
 626     MAIL_DOMAIN = 'fill.me.in.'
 627
 628 # the next two are only used for the standalone HTTP server.
 629 if not HTTP_HOST:
 630     HTTP_HOST = ''
 631 if not HTTP_PORT:
 632     HTTP_PORT = 9080
 633
 634 # This is the directory that the database is going to be stored in
 635 DATABASE = os.path.join(INSTANCE_HOME, 'db')
 636
 637 # This is the directory that the HTML templates reside in
 638 TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
 639
 640 # The email address that mail to roundup should go to
 641 ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
 642
 643 # The web address that the instance is viewable at
 644 ISSUE_TRACKER_WEB = 'http://some.useful.url/'
 645
 646 # The email address that roundup will complain to if it runs into trouble
 647 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
 648
 649 # Somewhere for roundup to log stuff internally sent to stdout or stderr
 650 LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
 651
 652 # Where to place the web filtering HTML on the index page
 653 FILTER_POSITION = 'bottom'      # one of 'top', 'bottom', 'top and bottom'
 654
 655 # Deny or allow anonymous access to the web interface
 656 ANONYMOUS_ACCESS = 'deny'
 657
 658 # Deny or allow anonymous users to register through the web interface
 659 ANONYMOUS_REGISTER = 'deny'
 660
 661 # Send nosy messages to the author of the message
 662 MESSAGES_TO_AUTHOR = 'no'       # either 'yes' or 'no'
 663 </pre>
 664
 665 <h2><a name="custinst">Instance Schema</a></h2>
 666 An instance schema defines what data is stored in the instance's database.
 667 The two schemas shipped with Roundup turn it into a typical software bug
 668 tracker (the extended schema allowing for support issues as well as bugs).
 669 Schemas are defined using Python code. The "classic" schema looks like
 670 this:
 671 <p>
 672 <pre>
 673     pri = Class(db, "priority", name=String(), order=String())
 674     pri.setkey("name")
 675     pri.create(name="critical", order="1")
 676     pri.create(name="urgent", order="2")
 677     pri.create(name="bug", order="3")
 678     pri.create(name="feature", order="4")
 679     pri.create(name="wish", order="5")
 680
 681     stat = Class(db, "status", name=String(), order=String())
 682     stat.setkey("name")
 683     stat.create(name="unread", order="1")
 684     stat.create(name="deferred", order="2")
 685     stat.create(name="chatting", order="3")
 686     stat.create(name="need-eg", order="4")
 687     stat.create(name="in-progress", order="5")
 688     stat.create(name="testing", order="6")
 689     stat.create(name="done-cbb", order="7")
 690     stat.create(name="resolved", order="8")
 691
 692     keyword = Class(db, "keyword", name=String())
 693     keyword.setkey("name")
 694
 695     user = Class(db, "user", username=String(), password=String(),
 696         address=String(), realname=String(), phone=String(), organisation=String())
 697     user.setkey("username")
 698     user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
 699
 700     msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"),
 701         date=Date(), summary=String(), files=Multilink("file"))
 702
 703     file = FileClass(db, "file", name=String(), type=String())
 704
 705     issue = IssueClass(db, "issue", assignedto=Link("user"),
 706         topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
 707     issue.setkey('title')
 708 </pre>
 709
 710 <h3>Classes and Properties - creating a new information store</h3>
 711 In the instance above, we've defined 7 <em>classes</em> of information:
 712 <dl>
 713     <dt><strong>priority</strong>
 714     <dd>Defines the possible levels of urgency for issues.
 715     <dt><strong>status</strong>
 716     <dd>Defines the possible states of processing the issue may be in.
 717     <dt><strong>keyword</strong>
 718     <dd>Initially empty, will hold keywords useful for searching issues.
 719     <dt><strong>user</strong>
 720     <dd>Initially holding the "admin" user, will eventually have an entry
 721     for all users using roundup.
 722     <dt><strong>msg</strong>
 723     <dd>Initially empty, will all e-mail messages sent to or generated by roundup.
 724     <dt><strong>file</strong>
 725     <dd>Initially empty, will all files attached to issues.
 726     <dt><strong>issue</strong>
 727     <dd>Initially emtyp, this is where the issue information is stored.
 728 </dl>
 729 <p>
 730 We define the "priority" and "status" classes to allow two things: reduction
 731 in the amount of information stored on the issue and more powerful, accurate
 732 searching of issues by priority and status. By only requiring a link on
 733 the issue (which is stored as a single number) we reduce the chance
 734 that someone mis-types a priority or status - or simply makes a new one
 735 up.
 736
 737 <h4>Class and Nodes</h4>
 738 A <em>Class</em> defines a particular class (or type) of data that will be
 739 stored in the database. A class comprises one or more properties, which
 740 given the information about the class nodes.
 741 <p>
 742 The actual data entered into the database, using <em>class</em>.create()
 743 are called <em>nodes</em>. They have a special immutable property called
 744 id. We sometimes refer to this as the <em>nodeid</em>.
 745
 746
 747 <h4>Properties</h4>
 748 A Class is comprised of one or more <em>properties</em> of the following types:
 749
 750 <ul>
 751 <li><em>String</em> properties are for storing arbitrary-length
 752 strings.
 753
 754 <li><em>Password</em> properties are for storing encoded arbitrary-length
 755 strings. The default encoding is defined on the roundup.password.Password
 756 class.
 757
 758 <li><em>Date</em> properties store date-and-time stamps.
 759 Their values are Timestamp objects.
 760
 761 <li>A <em>Link</em> property refers to a single other node
 762 selected from a specified class.  The class is part of the property;
 763 the value is an integer, the id of the chosen node.
 764
 765 <li>A <em>Multilink</em> property refers to possibly many nodes
 766 in a specified class.  The value is a list of integers.
 767 </ul>
 768
 769 <h4>FileClass</h4>
 770 FileClasses save their "content" attribute off in a separate file from the
 771 rest of the database. This reduces the number of large entries in the
 772 database, which generally makes databases more efficient, and also allows
 773 us to use command-line tools to operate on the files. They are stored in
 774 the files sub-directory of the db directory in your instance.
 775
 776 <h4>IssueClass</h4>
 777 IssueClasses automatically include the "messages", "files", "nosy", and
 778 "superseder" properties.
 779 <p>
 780 The messages and files properties list the links to the messages and files
 781 related to the issue. The nosy property is a list of links to users who
 782 wish to be informed of changes to the issue - they get "CC'ed" e-mails when
 783 messages are sent to or generated by the issue. The nosy reactor (in the
 784 detectors directory) handles this action. The superceder link indicates an
 785 issue which has superceded this one.
 786 <p>
 787 They also have the dynamically generated
 788 "creation", "activity" and "creator" properties.
 789 <p>
 790 The value of the "creation" property is the date when a node was created,
 791 and the value of the "activity" property is the date when any property on
 792 the node was last edited (equivalently, these are the dates on the first
 793 and last records in the node's journal). The "creator" property holds a
 794 link to the user that created the issue.
 795
 796 <h4>setkey(property)</h4>
 797 Select a String property of the class to be the key property. The key
 798 property muse be unique, and allows references to the nodes in the class by
 799 the content of the key property. That is, we can refer to users by their
 800 username, e.g. let's say that there's an issue in roundup, issue 23. There's
 801 also a user, richard who happens to be user 2. To assign an issue to him,
 802 we could do either of:
 803 <p>
 804 <blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote>
 805 <p>
 806 or
 807 <p>
 808 <blockquote><tt>roundup-admin set issue
 809         assignedto=richard</tt></blockquote>
 810 <p>
 811 Note, the same thing can be done in the web and e-mail interfaces.
 812
 813 <h4>create(information)</h4>
 814 Create a node in the database. This is generally used to create nodes in
 815 the "definitional" classes like "priority" and "status".
 816
 817
 818 <h2><a name="custweb">Web Interface</a></h2>
 819
 820 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
 821 scripts. In both cases, the scripts determine which instance is being
 822 accessed (the first part of the URL path inside the scope of the CGI
 823 handler) and pass control on to the instance interfaces.Client class which
 824 handles the rest of the access through its main() method. This means that
 825 you can do pretty much anything you want as a web interface to your
 826 instance.
 827 <p>
 828 Most customisation of the web view can be done by modifying the templates
 829 in the instance html directory. These are divided into index, item and
 830 newitem views. The newitem view is optional - the item view will be used if
 831 the newitem view doesn't exist.
 832
 833 <h3>Displaying Properties</h3>
 834
 835 <p>
 836 Properties appear in the user interface in three contexts:
 837 in indices, in editors, and as filters.  For each type of
 838 property, there are several display possibilities.  For example,
 839 in an index view, a string property may just be printed as
 840 a plain string, but in an editor view, that property should
 841 be displayed in an editable field.
 842
 843 <p>
 844 The display of a property is handled by functions in
 845 the htmltemplate module.
 846
 847 <p>
 848 Displayer functions are triggered by <tt>&lt;display&gt;</tt>
 849 tags in templates.  The <tt>call</tt> attribute of the tag
 850 provides a Python expression for calling the displayer
 851 function.  The three standard arguments are inserted in
 852 front of the arguments given.  For example, the occurrence of
 853
 854 <blockquote><pre><small
 855 >    &lt;display call="plain('status')"&gt;
 856 </small></pre></blockquote>
 857
 858 in a template triggers a call the "plain" function. The displayer
 859 functions can accept extra arguments to further specify
 860 details about the widgets that should be generated.  By defining new
 861 displayer functions, the user interface can be highly customized.
 862
 863 <p>
 864 <table border=1 cellspacing=0>
 865 <tr><th colspan=2>The displayer functions are</th></tr>
 866
 867 <tr><td valign="top"><strong>plain</strong></td>
 868 <td>Display a String property directly.
 869 <p>
 870 Display a Date property in a specified time zone with an option
 871 to omit the time from the date stamp.
 872 <p>
 873 For a Link or Multilink
 874 property, display the key strings of the linked nodes (or the
 875 ids if the linked class has no key property).
 876 <p>
 877 <em>Options:</em><br>
 878 escape (boolean) - HTML-escape the resulting text.
 879 </td></tr>
 880
 881 <tr><td valign="top"><strong>field</strong></td>
 882 <td>Display a property like the
 883 <strong>plain</strong> displayer above, but in a form field
 884 to be edited. Strings, Dates and Intervals use TEXT fields, Links use
 885 SELECT fields and Multilinks use SELECT MULTIPLE fields.
 886 <p>
 887 <em>Options:</em><br>
 888 size (number) - width of TEXT fields.<br>
 889 height (number) - number of nows in SELECT MULTIPLE tags.<br>
 890 showid (boolean) - true includes the id of linked nodes in the SELECT
 891 MULTIPLE fields.
 892 </td></tr>
 893
 894 <tr><td valign="top"><strong>menu</strong></td>
 895 <td>For a Links and Multilinks, display the same field as would be
 896 generated using <strong>field</strong>.
 897 </td></tr>
 898
 899 <tr><td valign="top"><strong>link</strong></td>
 900 <td>For a Link or Multilink property, display the names of the linked
 901 nodes, hyperlinked to the item views on those nodes.
 902 <p>
 903 For other properties, link to this node with the property as the text.
 904 <p>
 905 <em>Options:</em><br>
 906 property (property name) - the property to use in the second case.<br>
 907 is_download (boolean) - to be used for links te <em>file</em> class nodes -
 908 this indicates that the URL should have the specified property (usually
 909 <em>name</em>) appended so that the download has the correct name (instead
 910 of the node designator.)
 911 </td></tr>
 912
 913 <tr><td valign="top"><strong>count</strong></td>
 914 <td>For a Multilink property, display
 915 a count of the number of links in the list.
 916 <p>
 917 <em>Arguments:</em><br>
 918 property (property name) - the property to use.
 919
 920 </td></tr>
 921
 922 <tr><td valign="top"><strong>reldate</strong></td>
 923 <td>Display a Date property in terms
 924 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
 925 <p>
 926 <em>Arguments:</em><br>
 927 property (property name) - the property to use.
 928 <p>
 929 <em>Options:</em><br>
 930 pretty (boolean) - display the relative date in an English form.
 931 </td></tr>
 932
 933 <tr><td valign="top"><strong>download</strong></td>
 934 <td>Show a Link("file") or Multilink("file")
 935 property using links that allow you to download files.
 936 <p>
 937 <em>Arguments:</em><br>
 938 property (property name) - the property to use.
 939 </td></tr>
 940
 941 <tr><td valign="top"><strong>checklist</strong></td>
 942 <td>For a Link or Multilink property,
 943 display checkboxes for the available choices to permit filtering.
 944 <p>
 945 <em>Arguments:</em><br>
 946 property (property name) - the property to use.
 947 </td></tr>
 948
 949 <tr><td valign="top"><strong>note</strong></td>
 950 <td>Display the special notes field, which is a text area for entering a
 951 note to go along with a change.
 952 </td></tr>
 953
 954 <tr><td valign="top"><strong>list</strong></td>
 955 <td>List the nodes specified by property using the standard index for
 956 the class.
 957 <p>
 958 <em>Arguments:</em><br>
 959 property (property name) - the property to use.
 960 </td></tr>
 961
 962 <tr><td valign="top"><strong>history</strong></td>
 963 <td>List the history of the item.
 964 </td></tr>
 965
 966 <tr><td valign="top"><strong>submit</strong></td>
 967 <td>Add a submit button for the item.
 968 </td></tr>
 969
 970 </table>
 971
 972 <h3>Index Views</h3>
 973
 974 <p>An index view contains two sections: a filter section
 975 and an index section.
 976 The filter section provides some widgets for selecting
 977 which items appear in the index.  The index section is
 978 a table of items.
 979
 980 <h4>Index View Specifiers</h4>
 981
 982 <p>An index view specifier (URL fragment) looks like this (whitespace
 983 has been added for clarity):
 984
 985 <blockquote><pre><small
 986 >/issue?status=unread,in-progress,resolved&amp;
 987         topic=security,ui&amp;
 988         :group=+priority&amp;
 989         :sort=-activity&amp;
 990         :filters=status,topic&amp;
 991         :columns=title,status,fixer
 992 </small></pre></blockquote>
 993
 994 <p>The index view is determined by two parts of the
 995 specifier: the layout part and the filter part.
 996 The layout part consists of the query parameters that
 997 begin with colons, and it determines the way that the
 998 properties of selected nodes are displayed.
 999 The filter part consists of all the other query parameters,
1000 and it determines the criteria by which nodes
1001 are selected for display.
1002
1003 <p>The filter part is interactively manipulated with
1004 the form widgets displayed in the filter section.  The
1005 layout part is interactively manipulated by clicking
1006 on the column headings in the table.
1007
1008 <p>The filter part selects the <em>union</em> of the
1009 sets of items with values matching any specified Link
1010 properties and the <em>intersection</em> of the sets
1011 of items with values matching any specified Multilink
1012 properties.
1013
1014 <p>The example specifies an index of "issue" nodes.
1015 Only items with a "status" of <em>either</em>
1016 "unread" or "in-progres" or "resolved" are displayed,
1017 and only items with "topic" values including <em>both</em>
1018 "security" <em>and</em> "ui" are displayed.  The items
1019 are grouped by priority, arranged in ascending order;
1020 and within groups, sorted by activity, arranged in
1021 descending order.  The filter section shows filters
1022 for the "status" and "topic" properties, and the
1023 table includes columns for the "title", "status", and
1024 "fixer" properties.
1025
1026 <p>Associated with each item class is a default
1027 layout specifier.  The layout specifier in the above
1028 example is the default layout to be provided with
1029 the default bug-tracker schema described above in
1030 section 4.4.
1031
1032 <h4>Filter Section</h4>
1033
1034 <p>The template for a filter section provides the
1035 filtering widgets at the top of the index view.
1036 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
1037 tags are included or omitted depending on whether the
1038 view specifier requests a filter for a particular property.
1039
1040 <p>Here's a simple example of a filter template.
1041
1042 <blockquote><pre><small
1043 >&lt;property name=status&gt;
1044     &lt;display call="checklist('status')"&gt;
1045 &lt;/property&gt;
1046 &lt;br&gt;
1047 &lt;property name=priority&gt;
1048     &lt;display call="checklist('priority')"&gt;
1049 &lt;/property&gt;
1050 &lt;br&gt;
1051 &lt;property name=fixer&gt;
1052     &lt;display call="menu('fixer')"&gt;
1053 &lt;/property&gt;</small></pre></blockquote>
1054
1055 <p>
1056 The standard index generation code appends a section to the index pages
1057 which allows selection of the filters - from those which are defined in the
1058 filter template.
1059
1060 <h4>Index Section</h4>
1061
1062 <p>The template for an index section describes one row of
1063 the index table.
1064 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
1065 tags are included or omitted depending on whether the
1066 view specifier requests a column for a particular property.
1067 The table cells should contain <tt>&lt;display&gt;</tt> tags
1068 to display the values of the item's properties.
1069
1070 <p>Here's a simple example of an index template.
1071
1072 <blockquote><pre><small
1073 >&lt;tr&gt;
1074     &lt;property name=title&gt;
1075         &lt;td&gt;&lt;display call="plain('title', max=50)"&gt;&lt;/td&gt;
1076     &lt;/property&gt;
1077     &lt;property name=status&gt;
1078         &lt;td&gt;&lt;display call="plain('status')"&gt;&lt;/td&gt;
1079     &lt;/property&gt;
1080     &lt;property name=fixer&gt;
1081         &lt;td&gt;&lt;display call="plain('fixer')"&gt;&lt;/td&gt;
1082     &lt;/property&gt;
1083 &lt;/tr&gt;</small></pre></blockquote>
1084
1085 <h4>Sorting</h4>
1086
1087 <p>String and Date values are sorted in the natural way.
1088 Link properties are sorted according to the value of the
1089 "order" property on the linked nodes if it is present; or
1090 otherwise on the key string of the linked nodes; or
1091 finally on the node ids.  Multilink properties are
1092 sorted according to how many links are present.
1093
1094 <h3>Item Views</h3>
1095
1096 <p>An item view contains an editor section and a spool section.
1097 At the top of an item view, links to superseding and superseded
1098 items are always displayed.
1099
1100
1101
1102 <h4>Editor Section</h4>
1103
1104 <p>The editor section is generated from a template
1105 containing <tt>&lt;display&gt;</tt> tags to insert
1106 the appropriate widgets for editing properties.
1107
1108 <p>Here's an example of a basic editor template.
1109
1110 <blockquote><pre><small
1111 >&lt;table&gt;
1112 &lt;tr&gt;
1113     &lt;td colspan=2&gt;
1114         &lt;display call="field('title', size=60)"&gt;
1115     &lt;/td&gt;
1116 &lt;/tr&gt;
1117 &lt;tr&gt;
1118     &lt;td&gt;
1119         &lt;display call="field('fixer', size=30)"&gt;
1120     &lt;/td&gt;
1121     &lt;td&gt;
1122         &lt;display call="menu('status')&gt;
1123     &lt;/td&gt;
1124 &lt;/tr&gt;
1125 &lt;tr&gt;
1126     &lt;td&gt;
1127         &lt;display call="field('nosy', size=30)"&gt;
1128     &lt;/td&gt;
1129     &lt;td&gt;
1130         &lt;display call="menu('priority')&gt;
1131     &lt;/td&gt;
1132 &lt;/tr&gt;
1133 &lt;tr&gt;
1134     &lt;td colspan=2&gt;
1135         &lt;display call="note()"&gt;
1136     &lt;/td&gt;
1137 &lt;/tr&gt;
1138 &lt;/table&gt;
1139 </small></pre></blockquote>
1140
1141 <p>As shown in the example, the editor template can also
1142 request the display of a "note" field, which is a
1143 text area for entering a note to go along with a change.
1144
1145 <p>When a change is submitted, the system automatically
1146 generates a message describing the changed properties.
1147
1148 <p>If a note is given in the "note" field, the note is
1149 appended to the description.  The message is then added
1150 to the item's message spool (thus triggering the standard
1151 detector to react by sending out this message to the nosy list).
1152
1153 <p>
1154 The message also displays all of the property values on the
1155 item and indicates which ones have changed.
1156 An example of such a message might be this:
1157
1158 <blockquote><pre>
1159 Polly's taken a turn for the worse - this is now really important!
1160 -----
1161 title: Polly Parrot is dead
1162 priority: critical
1163 status: unread -&gt; in-progress
1164 fixer: terry
1165 keywords: parrot,plumage,perch,nailed,dead
1166 </pre></blockquote>
1167
1168 <h4>Spool Section</h4>
1169
1170 <p>The spool section lists messages in the item's "messages"
1171 property.  The index of messages displays the "date", "author",
1172 and "summary" properties on the message nodes, and selecting a
1173 message takes you to its content.
1174
1175 <p>The &lt;property&gt; tag used in the index may also be used here -
1176 it checks to see if the nominated Multilink property has any entries.
1177 This can be used to eliminate sections of the spool section if the
1178 property has no entries.
1179
1180 <blockquote><pre>
1181 &lt;property name="files"&gt;
1182  &lt;tr class="strong-header"&gt;
1183   &lt;td&gt;&lt;b&gt;Files&lt;/b&gt;&lt;/td&gt;
1184  &lt;/tr&gt;
1185
1186  &lt;tr&gt;
1187   &lt;td&gt;&lt;display call="list('files')"&gt;&lt;/td&gt;
1188  &lt;/tr&gt;
1189 &lt;/property&gt;
1190 </pre></blockquote>
1191
1192 <p><hr>
1193 <h1><a name="ack">Acknowledgements</a></h1>
1194
1195 Go Ping, you rock! Also, go Bizar Software for letting me implement this
1196 system on their time.
1197
1198 <p>&nbsp;</p>
1199 <hr>
1200 $Id: index.html,v 1.21 2001-12-13 00:20:01 richard Exp $
1201 <p>&nbsp;</p>
1202
1203 </body></html>
1204