Mercurial > p > roundup > code

annotate doc/overview.html @ 440:de5bf4191f11

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Enabled transaction support in the bsddb backend. It uses the anydbm code where possible, only replacing methods where the db is opened (it uses the btree opener specifically.) Also cleaned up some change note generation. Made the backends package work with pydoc too.
author Richard Jones <richard@users.sourceforge.net>
date Mon, 10 Dec 2001 22:20:01 +0000
parents 944bb5255eaf
children 1ac46e7e4150
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 <html><head>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4 <link rev=made href="mailto:ping@lfw.org">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 </head><body>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 <table width="100%">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 <tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 <td align="left">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 <a href="http://www.software-carpentry.com">
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
12 <img src="images/logo-software-carpentry-standard.png" alt="[Software Carpentry logo]" border="0">
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 </a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 </td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 <td align="right">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 <table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18 <tr><td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 <a href="http://www.acl.lanl.gov">
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
20 <img src="images/logo-acl-medium.png" alt="[ACL Logo]" border="0">
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 </a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22 </td></tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 <tr><td><hr></td></tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 <tr><td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 <a href="http://www.codesourcery.com">
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
26 <img src="images/logo-codesourcery-medium.png" alt="[CodeSourcery Logo]" border="0">
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 </a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 </td></tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 </table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 </td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 </tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 <tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 <td colspan="2"><em>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 Copyright (c) 2000 Ka-Ping Yee. This material may
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 be distributed only subject to the terms and conditions set forth in
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 the Software Carpentry Open Publication License, which is available at:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 <center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 <a href="http://www.software-carpentry.com/openpub-license.html">http://www.software-carpentry.com/openpub-license.html</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 </center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 </em></td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 </tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 </table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 <p><hr><p>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 <h1 align=center>Roundup</h1>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 <h4 align=center>Ka-Ping Yee</h4>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 <h4 align=center><a href="http://www.lfw.org/">lfw discorporated</a><br>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 <a href="mailto:ping@lfw.org">ping@lfw.org</a></h4>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57 <!-- the following line will start a comment in lynx -soft_dquotes mode -->
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58 <p style="><!--">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 <h2>Contents</h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 <li><a href="#overview">Overview</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 <li><a href="#background">Background</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67 <li><a href="#principles">Guiding Principles</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 <li><a href="#data">Data Model</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 <li><a href="#hyperdb">The Hyperdatabase</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 <li><a href="#rationale">Rationale</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 <li><a href="#roundupdb">Roundup's Hyperdatabase</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 <li><a href="#schema">The Default Schema</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76 <li><a href="#ui">User Interface</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 <li><a href="#discuss">Submission and Discussion (Nosy Lists)</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 <li><a href="#edit">Editing (Templated UI)</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 <li><a href="#browse">Browsing and Searching</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 <li><a href="#devplan">Development Plan</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83 <li><a href="#issues">Open Issues</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 <li><a href="#summary">Summary</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 <li><a href="#ack">Acknowledgements</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88 <!-- this comment will end the comment started in lynx -soft_dquotes mode -->
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 <h2><a name="overview">Overview</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 <p>We propose an issue-tracking system called
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 <em>Roundup</em>, which will manage a number of issues
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 (with properties such as "description", "priority", and so on)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 and provide the ability to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 (a) submit new issues,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 (b) find and edit existing issues,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 (c) discuss issues with other participants.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 The system will facilitate communication
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 among the participants by managing discussions and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103 notifying interested parties when issues are edited.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 <p>This design draws on experience from
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 <a href="http://www.lfw.org/ping/roundup.html">an existing
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 implementation</a> which we will refer to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 as "the Roundup prototype".
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 The graphical interface we have in mind will resemble
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
110 <a href="http://www.lfw.org/ping/roundup-1.png">
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 the main display of the prototype</a>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 <p align=center>
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
114 <a href="images/roundup-1.png">
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
115 <img src="images/roundup.png" width=358 height=205 border=0 alt=""></a>
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 <h2><a name="background">Background</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 <p>A typical software project requires the management of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 many tasks, usually distributed among several collaborators.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 In fact, any project team
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 could use a tool for sorting out and discussing all the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 relevant issues. A common approach is to set up some kind
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 of "to-do" list that people can share.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 <p>However, to address the overall problem we need much more
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128 than just a shared to-do list; we need to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 manage a growing body of knowledge and experience to help a
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 team collaborate effectively on a project. The issue-tracking
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 tool becomes a nexus for communication: the Grand Central
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 Station of the group intelligence.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 <p>The primary focus of this design is to help
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 developers work together well, not to provide a customer
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 service interface to the developers. This is not to say that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 the design is to be made unsuitable for customers to use.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 Rather, it is assumed that many of the same qualities
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 that are good for supporting development (see below)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140 are also good for non-developers using the system.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 Additional niceties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 for providing a safe or simplified interface to clients are
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 intentionally deferred for later consideration.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 <p>A good issue-tracking system should have at least the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 following properties:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 <p><table align=right width="40%" bgcolor="#808080"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 cellspacing=0 cellpadding=0 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 ><table bgcolor="#e8e8e8" width="100%"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 cellspacing=0 cellpadding=5 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 ><p><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 With a nod to the time-honoured computer science tradition
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 of "filling in the fourth quadrant", we note that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 there are really four kinds of information flow
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 going on here. The three mentioned qualities
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 really address the first three quadrants of this 2-by-2 matrix,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 respectively:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 <ol>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 <li>User push: a user submits information to the system.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 <li>User pull: a user queries for information from the system.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 <li>System push: the system sends information out to users.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 <li>System pull: the system solicits information from users.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 </ol>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 An example of the fourth kind of flow is voting.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 Voting isn't described in this design,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 but it should be noted as a potential enhancement.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 <ol>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 <li><strong>Low barrier to participation.</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 The usefulness of the tool depends entirely on the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 information people contribute to it. It must be made
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 as easy as possible to submit new issues and contribute
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 information about existing issues.<p>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 <li><strong>Straightforward navigation.</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 It should be easy for users to extract information they need
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 from the system to direct their decisions and tasks.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 They should be able to get a decent overview of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183 things as well as finding specific information when
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 they know what they're after.<p>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186 <li><strong>Controlled information flow.</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 The users must have control over how much information and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 what information they get. A common flaw of some issue-tracking
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 systems is that they inundate users with so much useless
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 e-mail that people avoid the system altogether.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191 </ol>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192 <br clear=all>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194 <p><br>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195 <h3><a name="principles">Guiding Principles</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 <p><strong>Simplicity.</strong> It is a strong requirement
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 that the tool be accessible and understandable. It should
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 be fairly obvious what different parts of the interface do,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200 and the inner mechanisms should operate in ways that most
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 users can easily predict.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203 <p><strong>Efficiency.</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 We aim to optimize for minimum effort to do the most common
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 operations, and best use of resources like screen real estate
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206 to maximize the amount of information that we summarize and present.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 <p><strong>Generality.</strong> We try to avoid making
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 unnecessary assumptions that would restrict the applicability
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 of the tool. For example, there is no reason why one might
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 not also want to use this tool to manage a design process,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 non-software projects, or organizational decisions.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 <p><strong>Persistence.</strong> We
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 prefer hiding or reclassifying information to deleting it.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 This helps support the collection of statistics later.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 If records are never destroyed, there is little danger
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 in providing access to a larger community, and logging yields
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 accountability, which may encourage better behaviour.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222 <p><table align=right width="40%" bgcolor="#808080"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 cellspacing=0 cellpadding=0 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 ><table bgcolor="#e8e8e8" width="100%"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 cellspacing=0 cellpadding=5 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 ><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 Okay, enough ranting. Let's get down to business.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 <h2><a name="data">Data Model</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 <p>Roundup stores a number of <em>items</em>, each of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 which can have several properties and an associated discussion.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233 The properties can be used to classify or search for items.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 The discussion is a sequence of e-mail messages.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235 Each item is identified by a unique number, and has
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 an activity log which
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 records the time and content of edits made on its properties.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 The log stays fairly small since the design intentionally
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 provides only small data types as item properties, and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240 encourages anything large to be attached to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 e-mail where it becomes part of the discussion.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242 The next section explains how items are organized.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 <h3><a name="hyperdb">The Hyperdatabase</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 <p><table align=right width="40%" bgcolor="#808080"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 cellspacing=0 cellpadding=0 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 ><table bgcolor="#e8e8e8" width="100%"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 cellspacing=0 cellpadding=5 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 ><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 In my opinion, forcing
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252 items into fixed categories is one of the most
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 serious problems with the Roundup prototype.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254 The hyperdatabase is an <em>experimental</em> attempt to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255 address the problem of information organization,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 whose scope goes beyond just Roundup.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 Often when classifying information we are
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260 asked to select exactly one of a number of categories
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 or to fit it into a rigid hierarchy. Yet things
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 only sometimes fall into one category; often,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 a piece of information may be related to several concepts.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 For example, forcing each item into a single topic
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 category is not just suboptimal but counterproductive:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 seekers of that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 item may expect to find it in a different category
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 and conclude that the item is not present in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270 database -- which has them <em>worse</em> off
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 than if the items were not categorized at all.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273 <p>Some systems try to alleviate this problem by
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274 allowing nodes to appear at multiple locations
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 in a tree, as with "aliases" or "symbolic links" in
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276 a filesystem, for example. This does help somewhat,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
277 but we want to be even more flexible
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278 by allowing the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279 organization of nodes into sets that may freely
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280 intersect. Rather than putting each node at exactly
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 one place in an overall "grand scheme", a node can
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 belong to as many sets as are appropriate.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 If we choose to represent the sets themselves as nodes
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285 and set membership as a link between nodes,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286 we're now ready to present the definition of a
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 hyperdatabase.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
288
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289 <p><table align=right width="40%" bgcolor="#808080"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 cellpadding=0 cellspacing=0 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291 ><table bgcolor="#e8e8e8" width="100%"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292 cellspacing=0 cellpadding=5 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293 ><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 Perhaps it's too pretentious a name?
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295 You could say this is just like an object database.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
296 The hyperdatabase is hardly much of an invention; the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297 intent is merely to emphasize querying on links
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298 rather than properties.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
299 (I haven't heard of this being done with
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300 object databases before, but plead ignorance if
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301 there's already a good name for this idea.)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
302 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303 A <em>hyperdatabase</em> is a collection of <em>nodes</em>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304 that may be hyperlinked to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305 each other (hence the name "hyperdatabase").
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 Each node carries a collection of key-value pairs,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307 where some of the values may be links to other nodes.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308 Any node may have an arbitrary number of outgoing and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 incoming links. Hyperdatabases are able to efficiently
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310 answer queries such as "what nodes link to this node?"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 and "what nodes does this node link to?"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 <h3><a name="rationale">Rationale</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 <p>There are several reasons for building our
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316 own kind of database for Roundup rather than using an existing one.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
318 Requiring the installation of a full-blown third-party
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319 SQL database system would probably deter many potential
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320 users from attempting to set up Roundup;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 yet a real relational database would be too
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 complicated to implement on our own.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 On the other hand, a hyperdatabase can be implemented fairly easily
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325 using one of the Python DBM modules, so we can
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 take the "batteries-included" approach and provide it
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327 as part of the system. It's easier to build and understand
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328 than a true relational database (in accordance with our guiding
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 principle of <em>simplicity</em>), but provides
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 most of the query functionality we want.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 <p>A hyperdatabase is well suited for finding the intersection
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333 of a number of sets in which items belong. We expect that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
334 most of the queries people want to do will be of this
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
335 form, rather than complicated SQL queries. For example, a
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
336 typical request might be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
337 "show me all critical items related to security".
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
338 The ability to store arbitrary key-value pairs and links
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339 on nodes gives it more flexibility than an RDBMS.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
341 Users are not going to be making thousands of queries
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
342 per second, so it makes sense to optimize for simplicity
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
343 and flexibility rather than performance.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
344
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
345 <p align=center><img src="images/hyperdb.png" width=433 height=352 alt=""></a>
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
346
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
347
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
348 <h3><a name="roundupdb">Roundup's Hyperdatabase</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350 <p>For our application, we store each item as a node in a
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
351 hyperdatabase. The item's properties are stored
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352 as key-value pairs on its node.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353 Four types of properties are allowed:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354 <em>string</em>, <em>date</em>,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355 <em>choice</em>, and <em>reference</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357 <p>The <em>string</em> type is for short, free-form strings.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 String properties are not intended to contain large
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
359 amounts of text, and it is recommended that they be presented
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
360 as one-line fields to encourage brevity.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362 <p>The <em>date</em> type is for calendar dates and times.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364 <p>The <em>choice</em> type denotes a single selection
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 from a number of options. A <em>choice</em> property
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366 entails a link from the node possessing the property to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 the node representing the chosen option.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 <p>The <em>reference</em> type is for a list of links to any
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370 number of other nodes in the in the database. A <em>reference</em>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 property, for example, can be used to refer to related items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372 or topic categories relevant to an item.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374 <p>For Roundup, all items have five properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375 that are not customizable:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 <li>a <em>string</em> property named <strong>description</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379 <li>a <em>reference</em> property named <strong>superseder</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 <li>a <em>reference</em> property named <strong>nosy</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381 <li>a <em>date</em> property named <strong>creation</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 <li>a <em>date</em> property named <strong>activity</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385 <p>The <strong>description</strong> property is a short
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 one-line description of the item.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387 The detailed description can go in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388 first e-mail message of the item's discussion spool.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390 <p>The <strong>superseder</strong> property is used to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391 support the splitting, joining, or replacing of items.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392 When several items need to be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 joined into a single item, all the old items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394 link to the new item in their <strong>superseder</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395 property.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396 When an item needs to be split apart, the item
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397 references all the new items in its <strong>superseder</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 propety.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399 We can easily list all active items just by checking
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400 for an empty <strong>superseder</strong> property, and trace
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401 the path of an item's origins by querying the hyperdatabase
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402 for links.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 <p>The <strong>nosy</strong> property contains a list of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405 the people who are interested in an item. This
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406 mechanism is explained in
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 <a href="#discuss">the section on Nosy Lists</a>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 <p>The <strong>creation</strong> property records the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410 item's creation time. The <strong>activity</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 property records the last time that the item was edited or
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 a mail message was added to its discussion spool. These two
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413 properties are managed by Roundup and are not available to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414 be edited like other properties.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416 <p>Users of the system are also represented by nodes in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 hyperdatabase, containing properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418 like the user's e-mail address, login name, and password.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420 <h3><a name="schema">The Default Schema</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422 <p><table align=right width="40%" bgcolor="#808080"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423 cellpadding=0 cellspacing=0 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
424 ><table bgcolor="#e8e8e8" width="100%"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425 cellspacing=0 cellpadding=5 border=0><tr><td
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 ><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427 Roundup could be distributed with a few
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428 suggested schemas for different purposes.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
429 One possible enhancement to the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
430 software-development schema is
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431 a <em>reference</em> property
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
432 named <strong>implements</strong> for connecting
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433 development items to design requirements which
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
434 they satisfy, which should
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435 be enough to provide basic support for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
436 <a href="http://software-carpentry.codesourcery.com/lists/sc-discuss/msg00046.html">traceability</a>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437 Clearly there is also potential for adding
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438 properties for related source files, check-ins,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
439 test results, regression tests for resolved items,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
440 and so on, though these have not yet been
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
441 sufficiently well thought out to specify here.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
442 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
443 <p>It is hoped that the hyperdatabase together with the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444 specializations mentioned above for Roundup will be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 applicable in a variety of situations
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446 (in accordance with our guiding principle of <em>generality</em>).
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448 <p>To address the problem at hand, we need
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449 a specific schema for items applied particularly to software development.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450 Again, we are trying to keep the schema simple: too many
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 options make it tougher for someone to make a good choice.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452 The schema is written here in the same form that it would
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 appear in a configuration file.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454 <br clear=all>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 <pre>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457 fixer = Reference() # people who will fix the problem
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459 topic = Reference() # relevant topic keywords
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 priority = Choice("critical", # panic: work is stopped!
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 "urgent", # important, but not deadly
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 "bug", # lost work or incorrect results
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464 "feature", # want missing functionality
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 "wish") # avoidable bugs, missing conveniences
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 status = Choice("unread", # submitted but no action yet
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 "deferred", # intentionally set aside
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469 "chatting", # under review or seeking clarification
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 "need-eg", # need a reproducible example of a bug
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 "in-progress", # understood; development in progress
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472 "testing", # we think it's done; others, please test
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473 "done-cbb", # okay for now, but could be better
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474 "resolved") # fix has been released
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475 </pre>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477 <p>The <strong>fixer</strong> property assigns
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
478 responsibility for an item to a person or a list of people.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
479 The <strong>topic</strong> property places the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
480 item in an arbitrary number of relevant topic sets (see
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
481 <a href="#browse">the section on Browsing and Searching</a>).
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483 <p>As previously mentioned, each item gets an activity log.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
484 Whenever a property on an item is changed, the log
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485 records the time of the change, the user making the change,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486 and the old and new values of the property. This permits
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 the later gathering of statistics (for example, the average time
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 from submission to resolution).
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 <p>We do not specify or enforce a state transition graph,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 since making the system rigid in that fashion is probably more
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492 trouble than it's worth.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 Experience has shown that there are probably
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 two convenient automatic state transitions:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 <li>from <strong>unread</strong> to <strong>chatting</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498 when e-mail is written about an item
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 <li>from <strong>testing</strong> to <strong>resolved</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 when a new release of the software is made
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503 Beyond these, in accordance with our principle of <em>generality</em>,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504 we allow access to the hyperdatabase
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505 API so that scripts can automate transitions themselves or
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 be triggered by changes in the database.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 <h2><a name="ui">User Interface</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 <p>Roundup provides its services through two main interfaces:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512 e-mail and the Web.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513 This division is chosen to optimize the most common tasks.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 <p>E-mail is best suited for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516 the submission of new items since most people are most comfortable
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
517 with composing long messages in their own favourite e-mail client.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518 E-mail also permits them to mention URLs or attach files relevant
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
519 to their submission. Indeed, in many cases people are already
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520 used to making requests by sending e-mail to a mailing list
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521 of people; they can do exactly the same thing to use Roundup
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 without even thinking about it.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523 Similarly, people are already
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
524 familiar with holding discussions in e-mail, and plenty of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
525 valuable usage conventions and software tools already exist for that medium.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
526
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
527 <p>The Web, on the other hand, is best suited for summarizing
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
528 and seeking information, because it can present an interactive
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 overview of items. Since the Web has forms, it's also
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530 the best place to edit items.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
531
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
532 <h3><a name="discuss">Submission and Discussion</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
533
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
534 <p><table align=right width="40%" bgcolor="#808080" cellpadding=0 border=0
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535 ><tr><td><table bgcolor="#e8e8e8" width="100%" cellspacing=0 cellpadding=5
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536 border=0><tr><td><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537 Nosy lists have actually been tried in practice,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538 and their emergent properties have
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539 turned out to be very effective.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 They are one of the key strengths of the Roundup prototype,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 and often cause me to wonder if all mailing lists ought to work this way.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 Roundup could even replace Hypermail.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545 <p>The system needs an address for receiving mail
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546 and an address that forwards mail to all participants.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 Each item has its own list
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548 of interested parties, known as its <em>nosy list</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 Here's how nosy lists work:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 <p><ol type="a">
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 <li>New items are always submitted by sending an e-mail message
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 to Roundup. The "Subject:" field becomes the description
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554 of the new item.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555 The message is saved in the mail spool of the new item,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556 and copied to the list of all participants
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
557 so everyone knows that a new item has been added.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558 The new item's nosy list initially contains the submitter.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 <li>All e-mail messages sent by Roundup have their "Reply-To:"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 field set to Roundup's address, and have the item's
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562 number in the "Subject:" field. Thus, any replies to the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
563 initial announcement and subsequent threads are all received
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564 by Roundup. Roundup notes the item number in the "Subject:"
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565 field of each incoming message and appends the message
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566 to the appropriate spool.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 <li>Any incoming e-mail tagged with an item number is copied
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569 to all the people on the item's nosy list,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 and any users found in the "From:", "To:", or "Cc:" fields
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 are automatically added to the nosy list. Whenever a user
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572 edits an item's properties in the Web interface, they are
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 also added to the nosy list.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574 </ol>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576 <p>The effect
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 is like each item having its own little mailing list,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 except that no one ever has to worry about subscribing to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 anything. Indicating interest in an issue is sufficient, and if you
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580 want to bring someone new into the conversation, all you need to do
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 is Cc: a message to them. It turns out that no one ever has to worry
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582 about unsubscribing, either: the nosy lists are so specific in scope
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 that the conversation tends to die down by itself when the issue is
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 resolved or people no longer find it sufficiently important.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 <p>Each nosy list is like an asynchronous chat room,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 lasting only a short time (typically five or ten messages)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 and involving a small group of people.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 However, that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 group is the <em>right</em> group of people:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 only those who express interest in an item in some way
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 ever end up on
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 the list, so no one gets spammed with mail they
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 don't care about, and no one who <em>wants</em>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595 to see mail about a particular item needs to be left
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 out, for they can easily join in, and just as easily
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 look at the mail spool on an item to catch up on any
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 messages they might have missed.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600 <p>We can take this a step further and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 permit users to monitor particular topics or
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
602 classifications of items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603 by allowing other kinds of nodes to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 also have their own nosy lists.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 For example, a manager could be on the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606 nosy list of the priority value node for "critical", or a
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 developer could be on the nosy list of the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 topic value node for "security".
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 The recipients are then
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 determined by the union of the nosy lists on the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 item and all the nodes it links to.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613 <p>Using many small, specific mailing lists results
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 in much more effective communication than one big list.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 Taking away the effort of subscribing and unsubscribing
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616 gives these lists the "feel" of being cheap and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 disposable.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
618
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
619 The transparent capture of the mail spool attached to each
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
620 issue also yields a nice knowledge repository over time.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
622
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623 <h3><a name="edit">Editing</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625 <p>
108
944bb5255eaf GIF -> PNG, saving about 100k
Richard Jones <richard@users.sourceforge.net>
parents: 107
diff changeset
626 <img src="images/edit.png" align=right width=171 height=471 alt="">
107
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
627 Since Roundup is intended to support arbitrary user-defined
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628 schema for item properties, the editing interface must be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
629 automatically generated from the schema. The configuration for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
630 Roundup will include a template describing how to lay out the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
631 properties to present a UI for inspecting and editing items.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
632 For example:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
633
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634 <pre>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
635 &lt;table width="100%"&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
636 &lt;tr&gt;&lt;td align=right&gt;Description:&lt;/td&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637 &lt;td&gt;&lt;?property description size=70&gt;&lt;/td&gt;&lt;/tr&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638 &lt;tr&gt;&lt;td align=right&gt;Status:&lt;/td&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
639 &lt;td&gt;&lt;?property status&gt;&lt;/td&gt;&lt;/tr&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
640 &lt;/table&gt;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
641 </pre>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
642
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
643 <p>To display the editing form for an item, Roundup substitutes
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
644 an HTML form widget for each <tt>&lt;?property </tt>...<tt>&gt;</tt>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
645 tag, and transfers attributes
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646 (such as <tt>size=70</tt> in the above example)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647 from the processing tag to the form widget's tag.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
648 Each type has its own appropriate editing widget:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
649 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650 <li><em>string</em> properties appear as text fields
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651 <li><em>date</em> properties appear as text fields
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
652 <li><em>choice</em> properties appear as selection lists
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
653 <li><em>reference</em> properties appear as multiple-selection lists
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654 with a text field for adding a new option
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
655 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
656
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
657 <p>We foresee the use of custom date fields for things like deadlines,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
658 so input fields for <em>date</em> properties should support some
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
659 simple way of specifying relative dates (such as "three weeks from now").
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
660
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
661 <p>The <strong>superseder</strong> property is a special case:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
662 although it is more efficient to store a <strong>superseder</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
663 property in the superseded item, it makes more sense to provide
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
664 a "supersedes" edit field on the superseding item. So we need
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
665 a special widget on items for this purpose (perhaps something
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
666 as simple as a text field containing a comma-separated list of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
667 item numbers will do). Links in the <strong>superseder</strong> property
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
668 should appear on both the superseding and superseded items to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
669 facilitate navigating an item's pedigree.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
670
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
671 <p>After the editing widgets, the item inspection page shows
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
672 a "note" text box and then a display of the messages in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
673 discussion spool, like the Roundup prototype. This field
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
674 lets you enter a note explaining your change when you edit the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
675 item, and the note is included in the notification message that
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
676 goes out to tell the interested parties on the nosy list of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
677 your edits.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679 <h3><a name="browse">Browsing and Searching</a></h3>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681 <p>The ideal we would like to achieve is to make searching as
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
682 much like browsing as possible: the user simply clicks about
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
683 on things that seem interesting, and the information narrows
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
684 down comfortably until the goal is in sight. This is preferable
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
685 to trying to digest a screen filled with widgets and buttons
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
686 or entering a search expression in some arcane algebraic syntax.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
687
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
688 <p><table align=right width="40%" bgcolor="#808080" cellpadding=0 border=0
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
689 ><tr><td><table bgcolor="#e8e8e8" width="100%" cellspacing=0 cellpadding=5
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
690 border=0><tr><td><font color="#808080"><small>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
691 Though the generation of each page amounts to a database query,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
692 so that the underlying mechanism is still a series of queries and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
693 responses, the user interface never separates the query from
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
694 the response, so the <em>experience</em> is one of stepwise
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
695 refinement.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
696 </small></font></td></tr></table></td></tr></table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
697 While a one-shot search may be appropriate when you're
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
698 looking for a single item and you know exactly what you want, it's
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
699 not very helpful when you want an overview of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
700 things ("Gee, there are a lot more high-priority items than
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
701 there were last week!") or trying to do comparisons ("I have
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
702 some time today, so who is busiest and could most use some help?")
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
703 <br clear=all>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
704
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
705 <p>The browsing interface presents filtering
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
706 functionality for each of the properties in the schema. As with
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
707 editing, the interface is generated from a template
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
708 describing how to lay out the properties.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
709 Each type of property has its own appropriate filtering widget:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
710 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
711 <li><em>string</em> properties appear as text fields supporting
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
712 case-insensitive substring match
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
713 <li><em>date</em> properties appear as a text field with an
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
714 option to choose dates after or before the specified date
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
715 <li><em>choice</em> properties appear as a group of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
716 selectable options
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
717 (the filter selects the <em>union</em> of the sets of items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
718 associated with the active options)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
719 <li><em>reference</em> properties appear as a group of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
720 selectable options
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
721 (the filter selects the <em>intersection</em> of the sets of items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
722 associated with the active options)
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
723 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
724
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
725 <p>For a <em>reference</em> property like <strong>topic</strong>,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
726 one possibility is to show, as hyperlinks, the keywords whose
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
727 sets have non-empty intersections with the currently displayed set of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
728 items. Sorting the keywords by popularity seems
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
729 reasonable. Clicking on a keyword then narrows both the list of items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
730 and the list of keywords. This gives some of the feel of walking
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
731 around a directory tree -- but without the restriction of having
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
732 to select keywords in a particular hierarchical order, and without
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
733 the need to travel all the way to the leaves of the tree before
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
734 any items are visible.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
735
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
736 <p>Below the filtering form is a listing of items, with their
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
737 properties displayed in a table. Rows in the table can also be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
738 generated from a template, as with the editing interface.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
739 This listing is the central overview of the system, and it
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
740 should aim to maximize the density of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
741 useful information in accordance with our guiding principle of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
742 <em>efficiency</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
743 For example,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
744 <a href="http://www.lfw.org/ping/bugzilla-4.gif">Bugzilla
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
745 initially displays seven or eight items of the index</a>, but only
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
746 after the user has
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
747 <a href="http://www.lfw.org/ping/bugzilla-1.gif">waded</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
748 through
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
749 <a href="http://www.lfw.org/ping/bugzilla-2.gif">three</a>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
750 bewildering
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
751 <a href="http://www.lfw.org/ping/bugzilla-3.gif">screens</a> of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752 form widgets.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
753 <a href="http://www.lfw.org/ping/jitterbug-1.gif">Jitterbug can't
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
754 even fit any items at all in the first screenful</a>, as it's
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
755 taken up by artwork and adminstrative debris. In contrast,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
756 <a href="http://www.lfw.org/ping/roundup-1.gif">in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 Roundup prototype,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
758 25 high-priority issues are immediately visible</a>, with
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
759 most of the screen space devoted to their descriptions.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
760 Colour indicates
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
761 the status of each item to help the eye sift through the index quickly.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763 <p>In both Jitterbug and Bugzilla, items are sorted by default by ID,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
764 a meaningless field. Sorting by ID puts the issues in order by
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765 ascending submission date, which banishes recent issues far away
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
766 at the bottom of the list.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
767 The Roundup prototype sorts items
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
768 in sections by priority, and then within sections by the date
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769 of last activity. This reveals at a glance where discussion is
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 most active, and provides an easy way for anyone to move an issue
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771 up in the list.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773 <p>The page produced by a given set of browsing options constitutes
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774 a <em>view</em>. The options should all be part of the query
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775 parameters in the URL so that views may be bookmarked. A view
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 specifies:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 <li>search strings for string properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780 <li>date ranges for date properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781 <li>acceptable values for choice properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782 <li>required values for reference properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
783 <li>one or more sort keys
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784 <li>a list of properties for which to display filtering widgets
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
787 <p>On each sort key there is the option to use sections -- that is,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
788 instead of making the property's value a column of the table, each
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789 possible value for the property
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790 is displayed at the top of a section and all the items having
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791 that value for that property are grouped underneath. This avoids
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 wasting screen space with redundant information.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794 <p>We propose that our default view should be:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
795
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
796 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797 <li>all options on for <strong>priority</strong> and <strong>fixer</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 <li>all options on except "resolved" for <strong>status</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
799 <li>no options on for <strong>topic</strong>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800 <li>primary sort by <strong>priority</strong> in sections
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
801 <li>secondary sort by decreasing <strong>activity</strong> date
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
802 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804 <p>The starting URL for Roundup should immediately present the listing of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805 items generated by this default view, with no
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
806 preceding query screen.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
808 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809 <h2><a name="devplan">Development Plan</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 <p>The hyperdatabase is clearly a separable component which
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812 can be developed and tested independently to an API specification.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 <p>As soon as the API to the hyperdatabase is nailed down,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815 the implementation of the Roundup database layer
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816 on top of the hyperdatabase can begin.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 (This refers to the data types and five fixed properties
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818 specific to Roundup.) This layer can also be tested separately.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820 <p>When the interface to the Roundup hyperdatabase is ready,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 development can begin on the user interface. The mail handler
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822 and the Web interface can be developed in parallel and mostly
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823 independently of each other.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
825 <p>The mail handler can be set up for testing fairly easily:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
826 mail messages on its standard input can be synthesized;
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
827 its output is outgoing mail, which can be
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828 captured by replacing the implementation of the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
829 "send mail" function; and its side effects appear in the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
830 hyperdatabase, which has a Python API.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
831
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
832 <p>The Web interface is not easily testable in its entirety,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833 though the most important components of it can be unit tested,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 such as the component that translates a view specification
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
835 into a list of items for display, and
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
836 the component that performs replacements on templates
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 to produce an editing or filtering interface.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840 <h2><a name="issues">Open Issues</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 <p>The description of the hyperdatabase above avoids some
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 issues regarding node typing that need to be better specified.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844 It is conceivable that eventually Roundup
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
845 could support multiple kinds of items with their own schemas.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
846
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847 <p>To permit integration with external tools, it is probably
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848 a good idea to provide a command-line tool that exposes the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
849 hyperdatabase API. This tool will be left for a later phase
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850 of development and so isn't specified in detail here.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 <p>Generating the user interface from a template is like
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853 applying an XSL stylesheet to XML, and if there's a standard
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854 Python module for performing these transformations, we could
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855 use XML instead.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
856
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857 <p>More thinking is needed to determine the best filtering
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
858 interface for <em>reference</em> properties.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
859 The proposed interface works well for topic keywords, but
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
860 it isn't clear what to do when there are too many keywords
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
861 to display them all.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
862
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
863 <p>There has been a variety of reactions to the hyperdatabase
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
864 from reviewers: some like it, some are neutral, and some
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
865 would prefer a "standard" RDBMS solution.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
866 For those in the latter camp, note
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
867 that it's still possible to build the Roundup database layer
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
868 around an RDBMS if we really need to. The rest of the design, in
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
869 particular the "nosy list" mechanism, remains intact.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
870
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
871 <p>The possibility of malice by registered users has been disregarded.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
872 The system is intended to be used by a co-operative group.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
874 <p>This design tries to address as many as possible of the
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875 suggested requirements mentioned on
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876 <a href="http://software-carpentry.codesourcery.com/sc_track">the contest page</a>:
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
877
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
878 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
879 <li>configuring states: Edit the schema.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
880 <li>setting state transition rules: We don't enforce any rules.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
881 <li>assigning responsibility: Set the <strong>fixer</strong> property.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
882 <li>splitting and joining: Use the <strong>superseder</strong> property.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
883 <li>hiding information: Add
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884 a property and a pre-defined view that filters on it.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
885 <li>secure protocols: Naturally HTTPS would be nice, though it's largely
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
886 a webserver configuration issue; secure e-mail is not addressed.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
887 <li>archiving old issues: Tag them with a property.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
888 <li>identifying repeated issues: Use the <strong>superseder</strong> property.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
889 <li>connecting state changes to external operations: We provide an
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890 API to the database and the notification mechanism so it can be scripted.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891 <li>non-Latin alphabets: Unicode in Python 1.6 will handle
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 this for string properties, and we can leverage existing standards for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893 internationalizing e-mail messages.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
894 <li>images and other binaries: Attach them to e-mail messages.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895 <li>inspecting item state: Use the editing interface.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
896 <li>translation between system-dependent formats: This is not addressed.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
897 <li>performing searches: Use the browsing and filtering interface.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
898 <li>collecting statistics: Information is gathered in the activity log,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899 though tools to summarize it are not described here.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
900 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
901
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
902 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903 <h2><a name="summary">Summary</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
904
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
905 <p>Roundup is an issue-tracking system that also functions as
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906 a communications center and a knowledge repository. It combines
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
907 the strengths of e-mail and the Web to try to provide the best
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908 possible user interaction.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910 <ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
911 <li>The submission and discussion of items by e-mail, permitting
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912 participants to use an easy and familiar tool, achieves our goal
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
913 of <em>low barrier to participation</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
914 <li>The generic link-based structuring of data and use of
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
915 incremental filtering rather than one-shot querying makes for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
916 <em>straightforward navigation</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
917 <li>The use of <em>nosy lists</em> (a powerful replacement for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
918 e-mail discussion lists) to manage communication on
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
919 a fine-grained level provides <em>controlled information flow</em>.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
920 </ul>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
921
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
922 <p>The use of a "hyperdatabase" as the core model for
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
923 the knowledge repository gives us the flexibility to extend
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
924 Roundup and apply it to a variety of domains by
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
925 providing new item schemas and user-interface templates.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
926
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
927 <p>Roundup is self-contained and easy to set up, requiring
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
928 only a webserver and a mailbox. No one needs to be root to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
929 configure the webserver or to install database software.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
930
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
931 <p>This design is based on an existing deployed
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
932 prototype which has proven its strengths and revealed its
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
933 weaknesses in heavy day-to-day use by a real development team.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
934
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
935 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
936 <h2><a name="ack">Acknowledgements</a></h2>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
937
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
938 <p>My thanks are due to
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
939 Christina Heyl, Jesse Vincent, Mark Miller, Christopher Simons,
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
940 Jeff Dunmall, Wayne Gramlich, and Dean Tribble
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
941 for reviewing this paper and contributing their suggestions.
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
942
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
943 <p><hr><p>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
944
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
945 <center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
946 <table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
947 <tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
948 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/index.html"><b>[Home]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
949 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/faq.html"><b>[FAQ]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
950 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/license.html"><b>[License]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
951 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/contest-rules.html"><b>[Rules]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
952 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/biblio.html"><b>[Resources]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
953 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/lists/"><b>[Archives]</b></a>&nbsp;&nbsp;&nbsp;</td>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
954 </tr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
955 </table>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
956 </center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
957
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
958 <p><hr>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
959 <center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
960 Last modified 2001/04/06 11:50:59.9063 US/Mountain
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
961 </center>
1f459d614e62 added more documentation
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
962 </body></html>
Roundup Issue Tracker: http://roundup-tracker.org/