annotate doc/html_extra/original_overview.html @ 5639:f576957cbb1f

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

Roundup Issue Tracker: http://roundup-tracker.org/