Mercurial > p > roundup > code

annotate doc/overview.txt @ 3754:9f4dd27ae843

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation cleanup from Luke Ross (patch [SF#1594860])
author Richard Jones <richard@users.sourceforge.net>
date Sun, 12 Nov 2006 00:09:42 +0000
parents 284c26c1ef19
children 91008ec8f9a0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1654
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 =======================================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Roundup: an Issue-Tracking System for Knowledge Workers
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 =======================================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 :Authors: Ka-Ping Yee (original_), Richard Jones (implementation)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 .. _original: original_overview.html
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9 .. contents::
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 Introduction
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 ============
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 Roundup is an issue-tracking system called which will manage a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 number of issues (with properties such as "description", "priority",
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 and so on) and provides the ability to:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 (a) submit new issues,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 (b) find and edit existing issues, and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 (c) discuss issues with other participants.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 Roundup facilitates communication among the participants by managing
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 discussions and notifying interested parties when issues are edited.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 Background
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 ----------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 A typical software project requires the management of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 many tasks, usually distributed among several collaborators.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 In fact, any project team
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 could use a tool for sorting out and discussing all the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 relevant issues. A common approach is to set up some kind
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 of "to-do" list that people can share.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 However, to address the overall problem we need much more
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 than just a shared to-do list; we need to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 manage a growing body of knowledge and experience to help a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 team collaborate effectively on a project. The issue-tracking
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 tool becomes a nexus for communication: the Grand Central
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 Station of the group intelligence.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 The primary focus of this design is to help
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 developers work together well, not to provide a customer
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 service interface to the developers. This is not to say that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 the design is to be made unsuitable for customers to use.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 Rather, it is assumed that many of the same qualities
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49 that are good for supporting development (see below)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 are also good for non-developers using the system.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 Additional niceties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 for providing a safe or simplified interface to clients are
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 intentionally deferred for later consideration.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 A good issue-tracking system should have at least the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56 following properties:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58 **Low barrier to participation**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59 The usefulness of the tool depends entirely on the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 information people contribute to it. It must be made
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 as easy as possible to submit new issues and contribute
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 information about existing issues.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 **Straightforward navigation**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 It should be easy for users to extract information they need
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 from the system to direct their decisions and tasks.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67 They should be able to get a decent overview of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 things as well as finding specific information when
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 they know what they're after.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 **Controlled information flow**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 The users must have control over how much information and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 what information they get. A common flaw of some issue-tracking
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 systems is that they inundate users with so much useless
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 e-mail that people avoid the system altogether.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 With a nod to the time-honoured computer science tradition
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 of "filling in the fourth quadrant", we note that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 there are really four kinds of information flow
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 going on here. The three mentioned qualities
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 really address the first three quadrants of this 2-by-2 matrix,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 respectively:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 1. User push: a user submits information to the system.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 2. User pull: a user queries for information from the system.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 3. System push: the system sends information out to users.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87 4. System pull: the system solicits information from users.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 An example of the fourth kind of flow is voting.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 Voting isn't described in this design,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 but it should be noted as a potential enhancement.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 Guiding Principles
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 ------------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 **Simplicity**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 It is a strong requirement
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 that the tool be accessible and understandable. It should
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 be fairly obvious what different parts of the interface do,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 and the inner mechanisms should operate in ways that most
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 users can easily predict.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 **Efficiency**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 We aim to optimize for minimum effort to do the most common
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 operations, and best use of resources like screen real estate
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 to maximize the amount of information that we summarize and present.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 **Generality**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 We try to avoid making
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 unnecessary assumptions that would restrict the applicability
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 of the tool. For example, there is no reason why one might
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 not also want to use this tool to manage a design process,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 non-software projects, or organizational decisions.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116 **Persistence** We
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117 prefer hiding or reclassifying information to deleting it.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 This helps support the collection of statistics later.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 If records are never destroyed, there is little danger
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120 in providing access to a larger community, and logging yields
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 accountability, which may encourage better behaviour.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 Data Model
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 ==========
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 Roundup stores a number of *items*, each of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128 which can have several properties and an associated discussion.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 The properties can be used to classify or search for items.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 The discussion is a sequence of e-mail messages.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 Each item is identified by a unique number, and has
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 an activity log which
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 records the time and content of edits made on its properties.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 The log stays fairly small since the design intentionally
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 provides only small data types as item properties, and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 encourages anything large to be attached to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 e-mail where it becomes part of the discussion.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 The next section explains how items are organized.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 The Hyperdatabase
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 -----------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 Often when classifying information we are
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 asked to select exactly one of a number of categories
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 or to fit it into a rigid hierarchy. Yet things
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 only sometimes fall into one category; often,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 a piece of information may be related to several concepts.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 For example, forcing each item into a single topic
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 category is not just suboptimal but counterproductive:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 seekers of that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 item may expect to find it in a different category
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 and conclude that the item is not present in the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 database -- which has them *worse* off
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 than if the items were not categorized at all.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 Some systems try to alleviate this problem by
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 allowing items to appear at multiple locations
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 in a tree, as with "aliases" or "symbolic links" in
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 a filesystem, for example. This does help somewhat,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 but we want to be even more flexible
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 by allowing the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 organization of items into sets that may freely
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 intersect. Rather than putting each item at exactly
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166 one place in an overall "grand scheme", a item can
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 belong to as many sets as are appropriate.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 If we choose to represent the sets themselves as items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 and set membership as a link between items,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 we're now ready to present the definition of a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 hyperdatabase.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 A *hyperdatabase* is a collection of *items*
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 that may be hyperlinked to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 each other (hence the name "hyperdatabase").
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 Each item carries a collection of key-value pairs,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 where some of the values may be links to other items.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 Any item may have an arbitrary number of outgoing and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 incoming links. Hyperdatabases are able to efficiently
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 answer queries such as "what items link to this item?"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 and "what items does this item link to?"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 Rationale
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185 ---------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 There are several reasons for building our
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 own kind of database for Roundup rather than using an existing one.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 Requiring the installation of a full-blown third-party
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191 SQL database system would probably deter many potential
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192 users from attempting to set up Roundup;
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193 yet a real relational database would be too
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194 complicated to implement on our own.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 On the other hand, a hyperdatabase can be implemented fairly easily
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 using one of the Python DBM modules, so we can
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 take the "batteries-included" approach and provide it
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 as part of the system. It's easier to build and understand
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200 than a true relational database (in accordance with our guiding
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 principle of *simplicity*), but provides
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 most of the query functionality we want.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 A hyperdatabase is well suited for finding the intersection
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 of a number of sets in which items belong. We expect that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206 most of the queries people want to do will be of this
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 form, rather than complicated SQL queries. For example, a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 typical request might be
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 "show me all critical items related to security".
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 The ability to store arbitrary key-value pairs and links
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 on items gives it more flexibility than an RDBMS.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213 Users are not going to be making thousands of queries
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 per second, so it makes sense to optimize for simplicity
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 and flexibility rather than performance.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 .. img: images/hyperdb.png
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 Roundup's Hyperdatabase
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 -----------------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 For our application, we store each item as a item in a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 hyperdatabase. The item's properties are stored
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 as key-value pairs on its item.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 Several types of properties are allowed:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 *string*, *number*, *boolean*, *date*, *interval, *link*,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 and *multlink*. Another type, *password*, is a special type
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 of string and it's only used internally to Roundup.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 The *string* type is for short, free-form strings.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 String properties are not intended to contain large
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233 amounts of text, and it is recommended that they be presented
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 as one-line fields to encourage brevity. A *number* is a special
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235 type of string that represents a numeric value. A *boolean* is
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 further constrained to be a *true* or *false* value.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 The *date* type is for calendar dates and times. An *interval*
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 is the time between two dates.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 The *link* type denotes a single selection from a number of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242 options. A *link* property entails a link from the item
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243 possessing the property to the item representing the chosen option.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245 The *multilink* type is for a list of links to any
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 number of other items in the in the database. A *multilink*
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 property, for example, can be used to refer to related items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 or topic categories relevant to an item.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 For Roundup, all items have four properties that are not customizable:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252 1. a *date* property named **creation**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 2. a *link* property named **creator**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254 3. a *date* property named **activity**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 These properties represent the date of the creation of the item, who
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 created it, and when the last change was made.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 Further, all *issue* items have an additional four properties:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 1. a *string* property named **title**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 2. a *multilink* property named **nosy**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 3. a *multilink* property named **messages**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 4. a *multilink* property named **files**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 5. a *multilink* property named **superseder**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 The **title** property is a short one-line description of the item.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 The detailed description can go in the first e-mail message of the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 item's messages spool.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 The **nosy** property contains a list of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272 the people who are interested in an item. This
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273 mechanism is explained in the section on `Submission and Discussion`_.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 Each message added to the item goes in the **messages** spool - any
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276 attached files go in the **files** spool.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
277
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278 The **superseder** property is used to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279 support the splitting, joining, or replacing of items.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280 When several items need to be
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 joined into a single item, all the old items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 link to the new item in their **superseder**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283 property.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 When an item needs to be split apart, the item
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285 references all the new items in its **superseder**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286 propety.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 We can easily list all active items just by checking
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
288 for an empty **superseder** property, and trace
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289 the path of an item's origins by querying the hyperdatabase
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 for links.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292 Users of the system are also represented by items in the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293 hyperdatabase, containing properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 like the user's e-mail address, login name, and password.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
296 The Default Schema
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297 ------------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
299 It is hoped that the hyperdatabase together with the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300 specializations mentioned above for Roundup will be
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301 applicable in a variety of situations
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
302 (in accordance with our guiding principle of *generality*).
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304 To address the problem at hand, we need
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305 a specific schema for items applied particularly to software development.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 Again, we are trying to keep the schema simple: too many
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307 options make it tougher for someone to make a good choice::
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 # IssueClass automatically gets these properties:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310 # title = String()
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 # messages = Multilink("msg")
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312 # files = Multilink("file")
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 # nosy = Multilink("user")
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314 # superseder = Multilink("issue")
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 # (it also gets the Class properties creation, activity and creator)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316 issue = IssueClass(db, "issue",
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317 assignedto=Link("user"), topic=Multilink("keyword"),
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
318 priority=Link("priority"), status=Link("status"))
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320 The **assignedto** property assigns
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 responsibility for an item to a person or a list of people.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 The **topic** property places the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323 item in an arbitrary number of relevant topic sets (see
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 the section on `Browsing and Searching`_).
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 The **prority** and **status** values are initially:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328 =========== =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 Priority Description
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 =========== =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331 "critical" panic: work is stopped!
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 "urgent" important, but not deadly
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333 "bug" lost work or incorrect results
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
334 "feature" want missing functionality
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
335 "wish" avoidable bugs, missing conveniences
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
336 =========== =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
337
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
338 ============= =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339 Status Description
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340 ============= =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
341 "unread" submitted but no action yet
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
342 "deferred" intentionally set aside
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
343 "chatting" under review or seeking clarification
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
344 "need-eg" need a reproducible example of a bug
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
345 "in-progress" understood; development in progress
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
346 "testing" we think it's done; others, please test
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
347 "done-cbb" okay for now, but could be better
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
348 "resolved" fix has been released
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349 ============= =====================================
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
351 As previously mentioned, each item gets an activity log.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352 Whenever a property on an item is changed, the log
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353 records the time of the change, the user making the change,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354 and the old and new values of the property. This permits
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355 the later gathering of statistics (for example, the average time
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356 from submission to resolution).
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 We do not specify or enforce a state transition graph,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
359 since making the system rigid in that fashion is probably more
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
360 trouble than it's worth.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361 Experience has shown that there are probably
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362 two convenient automatic state transitions:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364 1. from **unread** to **chatting** when e-mail is written about an item
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 2. from **testing** to **resolved** when a new release of the software is made
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 Beyond these, in accordance with our principle of *generality*,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368 we allow access to the hyperdatabase
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 API so that scripts can automate transitions themselves or
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370 be triggered by changes in the database.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373 User Interface
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374 ==============
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376 Roundup provides its services through two main interfaces:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377 e-mail and the Web.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 This division is chosen to optimize the most common tasks.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 E-mail is best suited for
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381 the submission of new items since most people are most comfortable
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 with composing long messages in their own favourite e-mail client.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383 E-mail also permits them to mention URLs or attach files relevant
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384 to their submission. Indeed, in many cases people are already
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385 used to making requests by sending e-mail to a mailing list
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 of people; they can do exactly the same thing to use Roundup
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387 without even thinking about it.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388 Similarly, people are already
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389 familiar with holding discussions in e-mail, and plenty of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390 valuable usage conventions and software tools already exist for that medium.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392 The Web, on the other hand, is best suited for summarizing
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 and seeking information, because it can present an interactive
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394 overview of items. Since the Web has forms, it's also
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395 the best place to edit items.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 Submission and Discussion
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399 -------------------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401 The system needs an address for receiving mail
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402 and an address that forwards mail to all participants.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403 Each item has its own list
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 of interested parties, known as its *nosy list*.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405 Here's how nosy lists work:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 1. New items are always submitted by sending an e-mail message
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408 to Roundup. The "Subject:" field becomes the description
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 of the new item.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410 The message is saved in the mail spool of the new item,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 and copied to the list of all participants
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 so everyone knows that a new item has been added.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413 The new item's nosy list initially contains the submitter.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 2. All e-mail messages sent by Roundup have their "Reply-To:"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416 field set to Roundup's address, and have the item's
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 number in the "Subject:" field. Thus, any replies to the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418 initial announcement and subsequent threads are all received
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419 by Roundup. Roundup notes the item number in the "Subject:"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420 field of each incoming message and appends the message
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421 to the appropriate spool.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423 3. Any incoming e-mail tagged with an item number is copied
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
424 to all the people on the item's nosy list,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425 and any users found in the "From:", "To:", or "Cc:" fields
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 are automatically added to the nosy list. Whenever a user
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427 edits an item's properties in the Web interface, they are
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428 also added to the nosy list.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
429
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
430 The effect is like each item having its own little mailing list,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431 except that no one ever has to worry about subscribing to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
432 anything. Indicating interest in an issue is sufficient, and if you
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433 want to bring someone new into the conversation, all you need to do
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
434 is "Cc:" a message to them. It turns out that no one ever has to worry
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435 about unsubscribing, either: the nosy lists are so specific in scope
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
436 that the conversation tends to die down by itself when the issue is
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437 resolved or people no longer find it sufficiently important.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
439 Each nosy list is like an asynchronous chat room,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
440 lasting only a short time (typically five or ten messages)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
441 and involving a small group of people. However, that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
442 group is the *right* group of people:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
443 only those who express interest in an item in some way
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444 ever end up on the list, so no one gets spammed with mail they
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 don't care about, and no one who *wants*
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446 to see mail about a particular item needs to be left
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447 out, for they can easily join in, and just as easily
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448 look at the mail spool on an item to catch up on any
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449 messages they might have missed.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 We can take this a step further and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452 permit users to monitor particular topics or classifications of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 by allowing other kinds of items to also have their own nosy lists.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454 For example, a manager could be on the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455 nosy list of the priority value item for "critical", or a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 developer could be on the nosy list of the topic value item for "security".
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457 The recipients are then determined by the union of the nosy lists on the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458 item and all the items it links to.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460 Using many small, specific mailing lists results
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 in much more effective communication than one big list.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 Taking away the effort of subscribing and unsubscribing
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 gives these lists the "feel" of being cheap and
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464 disposable.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466 The transparent capture of the mail spool attached to each
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 issue also yields a nice knowledge repository over time.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 Editing
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 -------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473 Since Roundup is intended to support arbitrary user-defined
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474 schema for item properties, the editing interface must be
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475 automatically generated from the schema. The configuration for
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476 Roundup will include a template describing how to lay out the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477 properties to present a UI for inspecting and editing items.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
478 For example::
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
479
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
480 <tr>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
481 <th class="required">Priority</th>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482 <td tal:content="structure context/priority/menu">priority</td>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483 <th>Status</th>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
484 <td tal:content="structure context/status/menu">status</td>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485 </tr>
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 To display the editing form for an item, Roundup inserts
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 an HTML form widget where it encounters an expression like
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489 ``tal:content="structure context/priority/menu"``.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 Each type has its own appropriate editing widget:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492 - *string* and *number* properties appear as text fields
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 - *boolean* properties appear as a yes/no selection
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 - *date* and *interval* properties appear as text fields
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495 - *link* properties appear as selection lists
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496 - *multilink* properties appear as multiple-selection lists
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 or text fields with pop-up widgets for larger selections.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 We foresee the use of custom date fields for things like deadlines,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 so input fields for *date* properties support a
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 simple way of specifying relative dates (such as "3w" for
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502 "three weeks from now").
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504 The **superseder** property is a special case:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505 although it is more efficient to store a **superseder**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 property in the superseded item, it makes more sense to provide
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507 a "supersedes" edit field on the superseding item. We use
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508 a special widget on items for this purpose (a text field containing
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 a comma-separated list of items). Links in the **superseder** property
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510 appear on both the superseding and superseded items to
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 facilitate navigating an item's pedigree.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513 After the editing widgets, the item inspection page shows
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514 a "note" text box and then a display of the messages in the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 discussion spool. This field
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516 lets you enter a note explaining your change when you edit the
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
517 item, and the note is included in the notification message that
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518 goes out to tell the interested parties on the nosy list of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
519 your edits.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521 Browsing and Searching
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 ----------------------
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
524 The ideal we would like to achieve is to make searching as
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
525 much like browsing as possible: the user simply clicks about
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
526 on things that seem interesting, and the information narrows
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
527 down comfortably until the goal is in sight. This is preferable
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
528 to trying to digest a screen filled with widgets and buttons
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 or entering a search expression in some arcane algebraic syntax.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
531 While a one-shot search may be appropriate when you're
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
532 looking for a single item and you know exactly what you want, it's
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
533 not very helpful when you want an overview of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
534 things ("Gee, there are a lot more high-priority items than
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535 there were last week!") or trying to do comparisons ("I have
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536 some time today, so who is busiest and could most use some help?")
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538 The browsing interface presents filtering
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539 functionality for each of the properties in the schema. As with
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 editing, the interface is generated from a template
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 describing how to lay out the properties.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 Each type of property has its own appropriate filtering widget:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544 - *string* properties appear as text fields supporting
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545 case-insensitive substring match
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546 - *date* properties appear as a text field which accepts a date
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 range with start, end or both
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548 - *link* properties appear as a group of selectable options
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 (the filter selects the *union* of the sets of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550 associated with the active options)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 - *multilink* properties appear as a group of selectable options
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 (the filter selects the *intersection* of the sets of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 associated with the active options)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555 For a *multilink* property like **topic**,
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556 one possibility is to show, as hyperlinks, the keywords whose
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
557 sets have non-empty intersections with the currently displayed set of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558 items. Sorting the keywords by popularity seems
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559 reasonable. Clicking on a keyword then narrows both the list of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 and the list of keywords. This gives some of the feel of walking
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 around a directory tree -- but without the restriction of having
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562 to select keywords in a particular hierarchical order, and without
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
563 the need to travel all the way to the leaves of the tree before
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564 any items are visible.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566 Below the filtering form is a listing of items, with their
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567 properties displayed in a table. Rows in the table are
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 generated from a template, as with the editing interface.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569 This listing is the central overview of the system, and it
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 should aim to maximize the density of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 useful information in accordance with our guiding principle of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572 *efficiency*. Colour may be used to indicate
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 the status of each item to help the eye sift through the index quickly.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 Roundup sorts items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576 in groups by priority, and then within groups by the date
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 of last activity. This reveals at a glance where discussion is
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 most active, and provides an easy way for anyone to move an issue
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 up in the list.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 The page produced by a given set of browsing options constitutes
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582 an *index*. The options should all be part of the query
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 parameters in the URL so that views may be bookmarked. An index
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 specifies:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 - search strings for string properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 - date ranges for date properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 - acceptable values for choice properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 - required values for reference properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 - a sorting key
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 - a grouping key
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 - a list of properties for which to display filtering widgets
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 Our default index is:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 - all **status** values except "resolved"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 - show **priority** and **fixer**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 - grouping by **priority** in sections
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 - sorting by decreasing **activity** date
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 The starting URL for Roundup immediately presents the listing of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
602 items generated by this default index, with no preceding query screen.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603
Roundup Issue Tracker: http://roundup-tracker.org/