doc/original_overview.html

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