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 2. Installation
15 ===============
16 For installation notes, please see the file INSTALL.TXT
19 3. Usage
20 ========
21 The system is designed to accessed through the command-line, e-mail or web
22 interface.
24 3.1 Command-line
25 ----------------
26 The command-line tool is called "roundup-admin" and is used for most low-level
27 database manipulations such as:
28 . creating a database instance
29 . redefining the list of products ("create" and "retire" commands)
30 . adding users manually, or setting their passwords ("create" and "set")
31 . other stuff - run it with no arguments to get a better description of
32 what it does.
35 3.2 E-mail
36 ----------
37 See the docstring at the start of the roundup/mailgw.py source file.
40 3.3 Web
41 -------
42 Hopefully, this interface is pretty self-explanatory...
44 Index views may be modified by the following arguments:
45 :sort - sort by prop name, optionally preceeded with '-'
46 to give descending or nothing for ascending sorting.
47 :group - group by prop name, optionally preceeded with '-' or
48 to sort in descending or nothing for ascending order.
49 :filter - selects which props should be displayed in the filter
50 section. Default is all.
51 :columns - selects the columns that should be displayed.
52 Default is all.
53 propname - selects the values the node properties given by propname
54 must have (very basic search/filter).
58 3. Design
59 =========
60 This software was written according to the specification found at
62 http://software-carpentry.codesourcery.com/entries/second-round/track/Roundup/
64 a copy of the spec is distributed with roundup as doc/spec.html.
67 There have been some modifications. I've marked these in the source with
68 'XXX' comments when I remember to.
70 In short:
71 Class.find() - may match multiple properties, uses keyword args.
73 Class.filter() - isn't in the spec and it's very useful to have at the Class
74 level.
76 CGI interface index view specifier layout part - lose the '+' from the
77 sorting arguments (it's a reserved URL character ;). Just made no
78 prefix mean ascending and '-' prefix descending.
80 ItemClass - renamed to IssueClass to better match it only having one
81 hypderdb class "issue". Allowing > 1 hyperdb class breaks the
82 "superseder" multilink (since it can only link to one thing, and we'd
83 want bugs to link to support and vice-versa).
85 templates - the call="link()" is handled by special-case mechanisms in my
86 top-level CGI handler. In a nutshell, the handler looks for a method on
87 itself called 'index%s' or 'item%s' where %s is a class. Most items
88 pass on to the templating mechanism, but the file class _always_ does
89 downloading. It'll probably stay this way too...
91 template - call="link(property)" may be used to link "the current node"
92 (from an index) - the link text is the property specified.
94 template - added functions that I found very useful: List, History and
95 Submit.
97 template - items must specify the message lists, history, etc. Having them
98 by default was sometimes not wanted.
100 template - index view determines its default columns from the template's
101 <property> tags.
103 template - menu() and field() look awfully similar now .... ;)
105 roundup.py - the command-line tool has a lot more commands at its disposal
109 4. TODO
110 =======
111 Most of the TODO items are captured in comments in the code. In summary:
113 in general:
114 . better error handling (nicer messages for users)
115 . possibly revert the entire damn thing to 1.5.2 ... :(
116 roundup.py:
117 . getopt() for command line
118 . default init db in some way?
119 hyperdb:
120 . transaction support
121 roundupdb:
122 . split the file storage into multiple files
123 roundup-mailgw:
124 . errors as attachments
125 . snip signatures?
126 server:
127 . check the source file timestamps before reloading
128 date:
129 . blue Date.__sub__ needs food, badly
130 config
131 . default to blank config in distribution and warn appropriately
132 roundup_cgi
133 . searching
134 . keep form fields in form on bad submission - only clear it if all ok
135 . messages should have the roundup CGI URL in them
138 5. Known Bugs
139 =============
141 date:
142 . date subtraction doesn't work correctly "if the dates cross leap years,
143 phases of the moon, ..."
145 filter:
146 . incorrectly embeds hidden fields for filters being displayed - and
147 doesn't use the existing values for filters being displayed either.
150 6. Author
151 =========
152 richard@bizarsoftware.com.au
155 7. Thanks
156 =========
157 Well, Ping, of course ;)
159 Anthony Baxter, for some good first-release feedback. And then continuing
160 support through development on sourceforge.