1 Roundup
2 =======
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).
10 The stylesheet included with this package has been copied from the Zope
11 management interface and presumably belongs to Digital Creations.
14 TODO: Instructions need re-writing!!
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.
23 Roundup is configurable using a localconfig.py file. It may have the
24 following variable declarations:
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
30 Any further configuration should be possible by editing config.py directly.
31 The email addresses used by the system by default are:
33 issue_tracker@MAIL_DOMAIN - submissions of issues
34 roundup-admin@MAIL_DOMAIN - roundup's internal use (problems, etc)
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
44 Both need the bsddb module.
47 2.1 Initial Setup
48 -----------------
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>"
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>"
62 2.3 Web Interface
63 -----------------
64 This software will work through apache or stand-alone.
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.
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 snip >>>
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 <<< snip
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/"
88 3. Usage
89 ========
90 The system is designed to accessed through the command-line, e-mail or web
91 interface.
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.
103 3.2 E-mail
104 ----------
105 See the docstring at the start of the roundup-mailgw.py source file.
108 3.3 Web
109 -------
110 Hopefully, this interface is pretty self-explanatory...
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).
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/
131 ... with some modifications. I've marked these in the source with 'XXX'
132 comments when I remember to.
134 In short:
135 Class.find() - may match multiple properties, uses keyword args.
137 Class.filter() - isn't in the spec and it's very useful to have at the Class
138 level.
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.
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).
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...
155 template - call="link(property)" may be used to link "the current node"
156 (from an index) - the link text is the property specified.
158 template - added functions that I found very useful: List, History and
159 Submit.
161 template - items must specify the message lists, history, etc. Having them
162 by default was sometimes not wanted.
164 template - index view determines its default columns from the template's
165 <property> tags.
167 template - menu() and field() look awfully similar now .... ;)
169 roundup.py - the command-line tool has a lot more commands at its disposal
173 4. TODO
174 =======
175 Most of the TODO items are captured in comments in the code. In summary:
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
202 5. Known Bugs
203 =============
205 date:
206 . date subtraction doesn't work correctly "if the dates cross leap years,
207 phases of the moon, ..."
209 filter:
210 . incorrectly embeds hidden fields for filters being displayed - and
211 doesn't use the existing values for filters being displayed either.
214 6. Author
215 =========
216 richard@bizarsoftware.com.au
219 7. Thanks
220 =========
221 Well, Ping, of course ;)
223 Anthony Baxter, for some good first-release feedback.