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