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