Mercurial > p > roundup > code

annotate doc/overview.txt @ 6290:944e4dfcc9b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551100 - out of date jquery fix security and user.help.html GitHub security scan flagged instances of older 1.3.2 jquery. Updated jQuery to current version 3.5.1 and fix user.help.html to have apply button work.
author John Rouillard <rouilj@ieee.org>
date Fri, 27 Nov 2020 00:15:26 -0500
parents e6073c2291c6
children 24e2eeb2ed9a
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
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
150 For example, forcing each item into a single keyword
1654
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
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
248 or keyword categories relevant to an item.
1654
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",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
317 assignedto=Link("user"), keyword=Multilink("keyword"),
1654
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.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
322 The **keyword** property places the
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
323 item in an arbitrary number of relevant keyword sets (see
1654
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
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
452 permit users to monitor particular keywords or classifications of items
1654
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
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
456 developer could be on the nosy list of the keyword value item for "security".
1654
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
6118
e6073c2291c6 Better Date filtering
Ralf Schlatterbeck <rsc@runtux.com>
parents: 3904
diff changeset
547 range with start, end or both. Multiple date ranges can be specified
e6073c2291c6 Better Date filtering
Ralf Schlatterbeck <rsc@runtux.com>
parents: 3904
diff changeset
548 separated by a comma. An empty date can be searched for by specifying
e6073c2291c6 Better Date filtering
Ralf Schlatterbeck <rsc@runtux.com>
parents: 3904
diff changeset
549 '-' instead of a date range
1654
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550 - *link* properties appear as a group of selectable options
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 (the filter selects the *union* of the sets of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 associated with the active options)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 - *multilink* properties appear as a group of selectable options
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554 (the filter selects the *intersection* of the sets of items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555 associated with the active options)
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 1654
diff changeset
557 For a *multilink* property like **keyword**,
1654
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558 one possibility is to show, as hyperlinks, the keywords whose
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559 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
560 items. Sorting the keywords by popularity seems
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 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
562 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
563 around a directory tree -- but without the restriction of having
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564 to select keywords in a particular hierarchical order, and without
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565 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
566 any items are visible.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 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
569 properties displayed in a table. Rows in the table are
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 generated from a template, as with the editing interface.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 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
572 should aim to maximize the density of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 useful information in accordance with our guiding principle of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574 *efficiency*. Colour may be used to indicate
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 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
576
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 Roundup sorts items
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 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
579 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
580 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
581 up in the list.
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 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
584 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
585 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
586 specifies:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 - search strings for string properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 - date ranges for date properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 - acceptable values for choice properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 - required values for reference properties
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 - a sorting key
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 - a grouping key
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 - a list of properties for which to display filtering widgets
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 Our default index is:
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 - all **status** values except "resolved"
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 - show **priority** and **fixer**
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600 - grouping by **priority** in sections
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 - sorting by decreasing **activity** date
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
602
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603 The starting URL for Roundup immediately presents the listing of
284c26c1ef19 aargh, b2 was b0rken
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 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
605
Roundup Issue Tracker: http://roundup-tracker.org/