README

   1                                     Roundup
   2                                     =======
   3
   4
   5 1. License
   6 ==========
   7 This software is released under the GNU GPL. The copyright is held by Bizar
   8 Software Pty Ltd (http://www.bizarsoftware.com.au).
   9
  10 The stylesheet included with this package has been copied from the Zope
  11 management interface and presumably belongs to Digital Creations.
  12
  13
  14
  15 2. Installation
  16 ===============
  17 These instructions work on redhat 6.2 and mandrake 8.0 - with the caveat
  18 that these systems don't come with python 2.0 or newer installed, so you'll
  19 have to upgrade python before this stuff will work.
  20
  21 Roundup is configurable using a localconfig.py file. It may have the
  22 following variable declarations:
  23
  24   ROUNDUP_HOME - This is the root directory for roundup
  25   MAILHOST - The SMTP mail host that roundup will use to send mail
  26   MAIL_DOMAIN - The domain name used for email addresses
  27
  28 Any further configuration should be possible by editing config.py directly.
  29 The email addresses used by the system by default are:
  30
  31   issue_tracker@MAIL_DOMAIN  - submissions of issues
  32   roundup-admin@MAIL_DOMAIN  - roundup's internal use (problems, etc)
  33
  34
  35 2.0 Prerequisites
  36 -----------------
  37 Either:
  38  . Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc.
  39 or
  40  . Python 2.1
  41
  42 Both need the bsddb module.
  43
  44
  45 2.1 Initial Setup
  46 -----------------
  47  1. Make a directory in /home/httpd/html called 'roundup'.
  48  2. Copy the tar file's contents there.
  49  3. Edit config.py
  50  4. "python roundup.py init" to initialise the database (by default, it
  51     goes in a directory called 'db' in the current directory). Choose a
  52     sensible admin password.
  53  5. "chmod -R a+rw db"
  54
  55
  56 2.2 Mail
  57 --------
  58 Set up a mail alias called "issue_tracker" as:
  59   "|/usr/bin/python /home/httpd/html/roundup/roundup-mailgw.py"
  60
  61 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
  62 so sendmail will accept the pipe command. In that case, symlink
  63 /etc/smrsh/python to /usr/bin/python and change the command to:
  64   "|python /home/httpd/html/roundup/roundup-mailgw.py"
  65
  66
  67 2.3 Web Interface
  68 -----------------
  69 This software will work through apache or stand-alone.
  70
  71 Stand-alone:
  72  1. Edit server.py at the bottom to set your hostname and a port that is free.
  73  2. "python server.py"
  74  3. Load up the page "/" using the port number you set.
  75
  76 Apache:
  77  1. Make sure roundup.cgi is executable
  78  2. Edit your /etc/httpd/conf/httpd.conf and make sure that the
  79     /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
  80     script.
  81  3. Add the following to your /etc/httpd/conf/httpd.conf:
  82 snip >>>
  83 RewriteEngine on
  84 RewriteCond %{HTTP:Authorization} ^(.*)
  85 RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
  86 <<< snip
  87    note: the RewriteRule must be on one line - no breaks
  88  4. Re-start your apache to re-load the config
  89  5. Load up the page "/roundup/roundup.cgi/"
  90
  91
  92
  93 3. Usage
  94 ========
  95 The system is designed to accessed through the command-line, e-mail or web
  96 interface.
  97
  98 3.1 Command-line
  99 ----------------
 100 The command-line tool is called "roundup.py" and is used for most low-level
 101 database manipulations such as:
 102  . redefining the list of products ("create" and "retire" commands)
 103  . adding users manually, or setting their passwords ("create" and "set")
 104  . other stuff - run it with no arguments to get a better description of
 105    what it does.
 106
 107
 108 3.2 E-mail
 109 ----------
 110 See the docstring at the start of the roundup-mailgw.py source file.
 111
 112
 113 3.3 Web
 114 -------
 115 Hopefully, this interface is pretty self-explanatory...
 116
 117 Index views may be modified by the following arguments:
 118     :sort    - sort by prop name, optionally preceeded with '-'
 119              to give descending or nothing for ascending sorting.
 120     :group   - group by prop name, optionally preceeded with '-' or
 121              to sort in descending or nothing for ascending order.
 122     :filter  - selects which props should be displayed in the filter
 123              section. Default is all.
 124     :columns - selects the columns that should be displayed.
 125              Default is all.
 126     propname - selects the values the node properties given by propname
 127              must have (very basic search/filter).
 128
 129
 130
 131 3. Design
 132 =========
 133 This software was written according to the specification found at
 134  http://software-carpentry.codesourcery.com/entries/second-round/track/Roundup/
 135
 136 ... with some modifications. I've marked these in the source with 'XXX'
 137 comments when I remember to.
 138
 139 In short:
 140  Class.find() - may match multiple properties, uses keyword args.
 141
 142  Class.filter() - isn't in the spec and it's very useful to have at the Class
 143     level.
 144
 145  CGI interface index view specifier layout part - lose the '+' from the
 146     sorting arguments (it's a reserved URL character ;). Just made no
 147     prefix mean ascending and '-' prefix descending.
 148
 149  ItemClass - renamed to IssueClass to better match it only having one
 150     hypderdb class "issue". Allowing > 1 hyperdb class breaks the
 151     "superseder" multilink (since it can only link to one thing, and we'd
 152     want bugs to link to support and vice-versa).
 153
 154  templates - the call="link()" is handled by special-case mechanisms in my
 155     top-level CGI handler. In a nutshell, the handler looks for a method on
 156     itself called 'index%s' or 'item%s' where %s is a class. Most items
 157     pass on to the templating mechanism, but the file class _always_ does
 158     downloading. It'll probably stay this way too...
 159
 160  template - call="link(property)" may be used to link "the current node"
 161     (from an index) - the link text is the property specified.
 162
 163  template - added functions that I found very useful: List, History and
 164     Submit.
 165
 166  template - items must specify the message lists, history, etc. Having them
 167     by default was sometimes not wanted.
 168
 169  template - index view determines its default columns from the template's
 170     <property> tags.
 171
 172  template - menu() and field() look awfully similar now .... ;)
 173
 174  roundup.py - the command-line tool has a lot more commands at its disposal
 175
 176
 177
 178 4. TODO
 179 =======
 180 Most of the TODO items are captured in comments in the code. In summary:
 181
 182 in general:
 183   . better error handling (nicer messages for users)
 184   . possibly revert the entire damn thing to 1.5.2 ... :(
 185 roundup.py:
 186   . getopt() for command line
 187   . default init db in some way?
 188 hyperdb:
 189   . transaction support
 190 roundupdb:
 191   . split the file storage into multiple files
 192 roundup-mailgw:
 193   . errors as attachments
 194   . snip signatures?
 195 server:
 196   . check the source file timestamps before reloading
 197 date:
 198   . blue Date.__sub__ needs food, badly
 199 config
 200   . default to blank config in distribution and warn appropriately
 201 roundup_cgi
 202   . searching
 203   . keep form fields in form on bad submission - only clear it if all ok
 204   . messages should have the roundup CGI URL in them
 205
 206
 207 5. Known Bugs
 208 =============
 209
 210 date:
 211   . date subtraction doesn't work correctly "if the dates cross leap years,
 212     phases of the moon, ..."
 213
 214
 215
 216 6. Author
 217 =========
 218 richard@bizarsoftware.com.au
 219
 220
 221 7. Thanks
 222 =========
 223 Well, Ping, of course ;)
 224
 225 Anthony Baxter, for some good first-release feedback.
 226