"Fossies" - the Fresh Open Source Software Archive

Member "roundup-2.0.0/share/doc/roundup/html/overview.html" (13 Jul 2020, 39026 Bytes) of package /linux/www/roundup-2.0.0.tar.gz:

The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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