File: user_guide.html

package info (click to toggle)
roundup 1.2.1-10%2Betch1
links: PTS
area: main
in suites: etch
size: 4,764 kB
ctags: 3,756
sloc: python: 30,296; sh: 1,497; perl: 23; makefile: 22
file content (1148 lines) | stat: -rw-r--r-- 48,493 bytes
parent folder | download | duplicates (2)
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>User Guide</title>
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="user-guide">
<h1 class="title">User Guide</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Version:</th>
<td>$Revision$</td></tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#your-tracker-in-a-nutshell" id="id1" name="id1">Your Tracker in a Nutshell</a><ul>
<li><a class="reference" href="#accessing-the-tracker" id="id2" name="id2">Accessing the Tracker</a></li>
<li><a class="reference" href="#issue-life-cycles-in-roundup" id="id3" name="id3">Issue life cycles in Roundup</a></li>
<li><a class="reference" href="#entering-values-in-your-tracker" id="id4" name="id4">Entering values in your Tracker</a><ul>
<li><a class="reference" href="#string-and-numeric-properties" id="id5" name="id5">String and Numeric properties</a></li>
<li><a class="reference" href="#boolean-properties" id="id6" name="id6">Boolean properties</a></li>
<li><a class="reference" href="#constrained-link-and-multilink-properties" id="id7" name="id7">Constrained (link and multilink) properties</a></li>
<li><a class="reference" href="#date-properties" id="id8" name="id8">Date properties</a></li>
<li><a class="reference" href="#interval-properties" id="id9" name="id9">Interval properties</a></li>
<li><a class="reference" href="#simple-support-for-collision-detection" id="id10" name="id10">Simple support for collision detection</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#web-interface" id="id11" name="id11">Web Interface</a><ul>
<li><a class="reference" href="#lists-of-items" id="id12" name="id12">Lists of Items</a></li>
<li><a class="reference" href="#display-edit-or-entry-of-an-item" id="id13" name="id13">Display, edit or entry of an item</a></li>
<li><a class="reference" href="#searching-page" id="id14" name="id14">Searching Page</a><ul>
<li><a class="reference" href="#saving-queries" id="id15" name="id15">Saving queries</a></li>
<li><a class="reference" href="#under-the-covers" id="id16" name="id16">Under the covers</a></li>
</ul>
</li>
<li><a class="reference" href="#access-controls" id="id17" name="id17">Access Controls</a></li>
</ul>
</li>
<li><a class="reference" href="#e-mail-gateway" id="id18" name="id18">E-Mail Gateway</a><ul>
<li><a class="reference" href="#subject-line-information" id="id19" name="id19">Subject-line information</a><ul>
<li><a class="reference" href="#setting-properties" id="id20" name="id20">Setting Properties</a></li>
<li><a class="reference" href="#automatic-properties" id="id21" name="id21">Automatic Properties</a></li>
</ul>
</li>
<li><a class="reference" href="#sender-identification" id="id22" name="id22">Sender identification</a></li>
<li><a class="reference" href="#e-mail-message-content" id="id23" name="id23">E-Mail Message Content</a><ul>
<li><a class="reference" href="#message-summary" id="id24" name="id24">Message summary</a></li>
</ul>
</li>
<li><a class="reference" href="#address-handling" id="id25" name="id25">Address handling</a><ul>
<li><a class="reference" href="#nosy-list" id="id26" name="id26">Nosy List</a></li>
</ul>
</li>
<li><a class="reference" href="#mail-gateway-script-command-line" id="id27" name="id27">Mail gateway script command line</a></li>
</ul>
</li>
<li><a class="reference" href="#command-line-tool" id="id28" name="id28">Command Line Tool</a><ul>
<li><a class="reference" href="#using-with-the-shell" id="id29" name="id29">Using with the shell</a></li>
</ul>
</li>
</ul>
</div>
<div class="hint">
<p class="first admonition-title">Hint</p>
<p class="last">This document will refer to <em>issues</em> as the primary store of
information in the tracker. This is the default of the classic template,
but may vary in any given installation.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id1" id="your-tracker-in-a-nutshell" name="your-tracker-in-a-nutshell">Your Tracker in a Nutshell</a></h1>
<p>Your tracker holds information about issues in bundles we call <em>items</em>.
An item may be an <em>issue</em> (a bug or feature request) or a <em>user</em>. The
issue-ness or user-ness is called the item's <em>class</em>. So, for bug
reports and features, the class is &quot;issue&quot;, and for users the class is
&quot;user&quot;.</p>
<p>Each item in the tracker has an id number that identifies it along with
its item class. To identify a particular issue or user, we combine the
class with the number to create a unique label, so that user 1 (who,
incidentally, is <em>always</em> the &quot;admin&quot; user) is referred to as &quot;user1&quot;.
Issue number 315 is referred to as &quot;issue315&quot;. We call that label the
item's <em>designator</em>.</p>
<p>Items in the database are never deleted, they're just &quot;retired&quot;. You
can still refer to them by ID - hence removing an item won't break
references to the item. It's just that the item won't appear in any
listings.</p>
<div class="section">
<h2><a class="toc-backref" href="#id2" id="accessing-the-tracker" name="accessing-the-tracker">Accessing the Tracker</a></h2>
<p>You may access your tracker through one of three ways:</p>
<ol class="arabic simple">
<li>through the <a class="reference" href="#web-interface">web interface</a>,</li>
<li>through the <a class="reference" href="#e-mail-gateway">e-mail gateway</a>, or</li>
<li>using the <a class="reference" href="#command-line-tool">command line tool</a>.</li>
</ol>
<p>The last is usually only used by administrators. Most users will use the
web and e-mail interfaces. All three are explained below.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="issue-life-cycles-in-roundup" name="issue-life-cycles-in-roundup">Issue life cycles in Roundup</a></h2>
<p>New issues may be submitted via the web or e-mail.</p>
<p>By default, the issue will have the status &quot;unread&quot;. If another message
is received for the issue, its status will change to &quot;chatting&quot;.</p>
<p>The &quot;home&quot; page for a tracker will generally display all issues which
are not &quot;resolved&quot;.</p>
<p>If an issue is closed, and a new message is received then it'll be
reopened to the state of &quot;chatting&quot;.</p>
<p>The full set of <strong>prority</strong> and <strong>status</strong> values are:</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Priority</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&quot;critical&quot;</td>
<td>panic: work is stopped!</td>
</tr>
<tr><td>&quot;urgent&quot;</td>
<td>important, but not deadly</td>
</tr>
<tr><td>&quot;bug&quot;</td>
<td>lost work or incorrect results</td>
</tr>
<tr><td>&quot;feature&quot;</td>
<td>want missing functionality</td>
</tr>
<tr><td>&quot;wish&quot;</td>
<td>avoidable bugs, missing conveniences</td>
</tr>
</tbody>
</table>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Status</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&quot;unread&quot;</td>
<td>submitted but no action yet</td>
</tr>
<tr><td>&quot;deferred&quot;</td>
<td>intentionally set aside</td>
</tr>
<tr><td>&quot;chatting&quot;</td>
<td>under review or seeking clarification</td>
</tr>
<tr><td>&quot;need-eg&quot;</td>
<td>need a reproducible example of a bug</td>
</tr>
<tr><td>&quot;in-progress&quot;</td>
<td>understood; development in progress</td>
</tr>
<tr><td>&quot;testing&quot;</td>
<td>we think it's done; others, please test</td>
</tr>
<tr><td>&quot;done-cbb&quot;</td>
<td>okay for now, but could be better</td>
</tr>
<tr><td>&quot;resolved&quot;</td>
<td>fix has been released</td>
</tr>
</tbody>
</table>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id4" id="entering-values-in-your-tracker" name="entering-values-in-your-tracker">Entering values in your Tracker</a></h2>
<p>All interfaces to your tracker use the same format for entering values.
This means the web interface for entering a new issue, the web interface
for searching issues, the e-mail interface and even the command-line
administration tool.</p>
<div class="section">
<h3><a class="toc-backref" href="#id5" id="string-and-numeric-properties" name="string-and-numeric-properties">String and Numeric properties</a></h3>
<p>These fields just take a simple text value, like <tt class="docutils literal"><span class="pre">It's</span> <span class="pre">broken</span></tt>.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id6" id="boolean-properties" name="boolean-properties">Boolean properties</a></h3>
<p>These fields take a value which indicates &quot;yes&quot;/&quot;no&quot;, &quot;true&quot;/&quot;false&quot;,
&quot;1&quot;/&quot;0&quot; or &quot;on&quot;/&quot;off&quot;.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id7" id="constrained-link-and-multilink-properties" name="constrained-link-and-multilink-properties">Constrained (link and multilink) properties</a></h3>
<p>Fields like &quot;Assigned To&quot; and &quot;Topics&quot; hold references to items in other
classes (&quot;user&quot; and &quot;keyword&quot; in those two cases.)</p>
<p>Sometimes, the selection is done through a menu, like in the &quot;Assigned
To&quot; field.</p>
<p>Where the input is not a simple menu selection, we use a comma-separated
list of values to indicated which values of &quot;user&quot; or &quot;keyword&quot; are
interesting. The values may be either numeric ids or the names of items.
The special value &quot;-1&quot; may be used to match items where the property is
not set. For example, the following searches on the issues:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">assignedto=richard,george</span></tt></dt>
<dd>match issues which are assigned to richard or george.</dd>
<dt><tt class="docutils literal"><span class="pre">assignedto=-1</span></tt></dt>
<dd>match issues that are not assigned to a user.</dd>
<dt><tt class="docutils literal"><span class="pre">assignedto=2,3,40</span></tt></dt>
<dd>match issues that are assigned to users 2, 3 or 40.</dd>
<dt><tt class="docutils literal"><span class="pre">topic=user</span> <span class="pre">interface</span></tt></dt>
<dd>match issues with the keyword &quot;user interface&quot; in their topic list</dd>
<dt><tt class="docutils literal"><span class="pre">topic=web</span> <span class="pre">interface,e-mail</span> <span class="pre">interface</span></tt></dt>
<dd>match issues with the keyword &quot;web interface&quot; or &quot;e-mail interface&quot; in
their topic list</dd>
<dt><tt class="docutils literal"><span class="pre">topic=-1</span></tt></dt>
<dd>match issues with no topics set</dd>
</dl>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id8" id="date-properties" name="date-properties">Date properties</a></h3>
<p>Date-and-time stamps are specified with the date in
international standard format (<tt class="docutils literal"><span class="pre">yyyy-mm-dd</span></tt>) joined to the time
(<tt class="docutils literal"><span class="pre">hh:mm:ss</span></tt>) by a period <tt class="docutils literal"><span class="pre">.</span></tt>.  Dates in this form can be easily
compared and are fairly readable when printed.  An example of a valid
stamp is <tt class="docutils literal"><span class="pre">2000-06-24.13:03:59</span></tt>. We'll call this the &quot;full date
format&quot;.  When Timestamp objects are printed as strings, they appear in
the full date format.</p>
<p>For user input, some partial forms are also permitted: the whole time or
just the seconds may be omitted; and the whole date may be omitted or
just the year may be omitted.  If the time is given, the time is
interpreted in the user's local time zone. The Date constructor takes
care of these conversions. In the following examples, suppose that
<tt class="docutils literal"><span class="pre">yyyy</span></tt> is the current year, <tt class="docutils literal"><span class="pre">mm</span></tt> is the current month, and <tt class="docutils literal"><span class="pre">dd</span></tt> is
the current day of the month.</p>
<ul class="simple">
<li>&quot;2000-04-17&quot; means &lt;Date 2000-04-17.00:00:00&gt;</li>
<li>&quot;01-25&quot; means &lt;Date yyyy-01-25.00:00:00&gt;</li>
<li>&quot;2000-04-17.03:45&quot; means &lt;Date 2000-04-17.08:45:00&gt;</li>
<li>&quot;08-13.22:13&quot; means &lt;Date yyyy-08-14.03:13:00&gt;</li>
<li>&quot;11-07.09:32:43&quot; means &lt;Date yyyy-11-07.14:32:43&gt;</li>
<li>&quot;14:25&quot; means</li>
<li>&lt;Date yyyy-mm-dd.19:25:00&gt;</li>
<li>&quot;8:47:11&quot; means</li>
<li>&lt;Date yyyy-mm-dd.13:47:11&gt;</li>
<li>the special date &quot;.&quot; means &quot;right now&quot;</li>
</ul>
<p>When searching, a plain date entered as a search field will match that date
exactly in the database.  We may also accept ranges of dates. You can
specify range of dates in one of two formats:</p>
<ol class="arabic">
<li><p class="first">English syntax:</p>
<pre class="literal-block">
[From &lt;value&gt;][To &lt;value&gt;]
</pre>
<p>Keywords &quot;From&quot; and &quot;To&quot; are case insensitive. Keyword &quot;From&quot; is
optional.</p>
</li>
<li><p class="first">&quot;Geek&quot; syntax:</p>
<pre class="literal-block">
[&lt;value&gt;];[&lt;value&gt;]
</pre>
</li>
</ol>
<p>Either first or second <tt class="docutils literal"><span class="pre">&lt;value&gt;</span></tt> can be omitted in both syntaxes.</p>
<p>For example, if you enter string &quot;from 9:00&quot; to &quot;Creation date&quot; field,
roundup will find  all issues, that were created today since 9 AM.</p>
<p>The <tt class="docutils literal"><span class="pre">&lt;value&gt;</span></tt> may also be an interval, as described in the next section.
Searching of &quot;-2m; -1m&quot; on activity field gives you issues which were
active between period of time since 2 months up-till month ago.</p>
<p>Other possible examples (consider local time is 2003-03-08.22:07:48):</p>
<ul class="simple">
<li>&quot;from 2-12 to 4-2&quot; means
&lt;Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00&gt;</li>
<li>&quot;FROM 18:00 TO +2m&quot; means
&lt;Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48&gt;</li>
<li>&quot;12:00;&quot; means
&lt;Range from 2003-03-08.12:00:00 to None&gt;</li>
<li>&quot;tO +3d&quot; means
&lt;Range from None to 2003-03-11.20:07:48&gt;</li>
<li>&quot;2002-11-10; 2002-12-12&quot; means
&lt;Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00&gt;</li>
<li>&quot;; 20:00 +1d&quot; means
&lt;Range from None to 2003-03-09.20:00:00&gt;</li>
<li>&quot;2003&quot; means
&lt;Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59&gt;</li>
<li>&quot;2003-04&quot; means
&lt;Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59&gt;</li>
</ul>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id9" id="interval-properties" name="interval-properties">Interval properties</a></h3>
<p>Date intervals are specified using the suffixes &quot;y&quot;, &quot;m&quot;, and &quot;d&quot;.  The
suffix &quot;w&quot; (for &quot;week&quot;) means 7 days. Time intervals are specified in
hh:mm:ss format (the seconds may be omitted, but the hours and minutes
may not).</p>
<ul class="simple">
<li>&quot;3y&quot; means three years</li>
<li>&quot;2y 1m&quot; means two years and one month</li>
<li>&quot;1m 25d&quot; means one month and 25 days</li>
<li>&quot;2w 3d&quot; means two weeks and three days</li>
<li>&quot;1d 2:50&quot; means one day, two hours, and 50 minutes</li>
<li>&quot;14:00&quot; means 14 hours</li>
<li>&quot;0:04:33&quot; means four minutes and 33 seconds</li>
</ul>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id10" id="simple-support-for-collision-detection" name="simple-support-for-collision-detection">Simple support for collision detection</a></h3>
<p>Item edit pages remember when the item was last edited. When a form is
submitted, the user will be informed if someone else has edited the item
at the same time they tried to.</p>
</div>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id11" id="web-interface" name="web-interface">Web Interface</a></h1>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document contains screenshots of the default look and feel.
Your site may have a slightly (or very) different look, but the
functionality will be very similar, and the concepts still hold.</p>
</div>
<p>The web interface is broken up into the following parts:</p>
<ol class="arabic simple">
<li><a class="reference" href="#lists-of-items">lists of items</a>,</li>
<li><a class="reference" href="#display-edit-or-entry-of-an-item">display, edit or entry of an item</a>, and</li>
<li><a class="reference" href="#searching-page">searching page</a>.</li>
</ol>
<div class="section">
<h2><a class="toc-backref" href="#id12" id="lists-of-items" name="lists-of-items">Lists of Items</a></h2>
<p>The first thing you'll see when you log into Roundup will be a list of
open (ie. not resolved) issues. This list has been generated by a bunch
of controls <a class="reference" href="#under-the-covers">under the covers</a> but for now, you can see something like:</p>
<!-- img: images/index_logged_out.png -->
<p>The screen is divided up into three sections:</p>
<!-- img: images/page_layout.png -->
<p>you may either register or log in. Registration takes you to:</p>
<!-- img: images/registration.png -->
<p>Once you're logged in, the screen changes slightly to:</p>
<!-- img: images/index_logged_in.png -->
<p>Note that the sidebar menu has changed slightly, so you can now get to
your &quot;My Details&quot; page:</p>
<!-- img: images/my_details.png -->
<p>Note the new information on this page - the history.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id13" id="display-edit-or-entry-of-an-item" name="display-edit-or-entry-of-an-item">Display, edit or entry of an item</a></h2>
<p>Create a new issue with &quot;create new&quot; under the issue subheading. This
will take you to:</p>
<!-- img: images/new_issue.png -->
<p>The <a class="reference" href="#nosy-list">nosy list</a> is explained below. Enter some information and click
&quot;submit new entry&quot; and you'll be rewarded with:</p>
<!-- img: images/new_issue_created.png -->
<p>or, if you don't enter all the required information (or some other error
occurs) you'll get something like:</p>
<!-- img: images/new_issue_error.png -->
</div>
<div class="section">
<h2><a class="toc-backref" href="#id14" id="searching-page" name="searching-page">Searching Page</a></h2>
<p>See <a class="reference" href="#entering-values-in-your-tracker">entering values in your tracker</a> for an explanation of what you
may type into the search form.</p>
<div class="section">
<h3><a class="toc-backref" href="#id15" id="saving-queries" name="saving-queries">Saving queries</a></h3>
<p>You may save queries in the tracker by giving the query a name. Each user
may only have one query with a given name - if a subsequent search is
performed with the same query name supplied, then it will edit the
existing query of the same name.</p>
<p>Queries may be marked as &quot;private&quot;. These queries are only visible to the
user that created them. If they're not marked &quot;private&quot; then all other
users may include the query in their list of &quot;Your Queries&quot;. Marking it as
private at a later date does not affect users already using the query, nor
does deleting the query.</p>
<p>If a user subsequently creates or edits a public query, a new personal
version of that query is made, with the same editing rules as described
above.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id16" id="under-the-covers" name="under-the-covers">Under the covers</a></h3>
<p>The searching page converts your selections into the following
arguments:</p>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="84%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Argument</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>&#64;sort</td>
<td>sort by prop name, optionally preceeded with '-' to give
descending or nothing for ascending sorting. The sort
argument can have several props separated with comma.</td>
</tr>
<tr><td>&#64;group</td>
<td>group by prop name, optionally preceeded with '-' or to sort
in descending or nothing for ascending order. The group
argument can have several props separated with comma.</td>
</tr>
<tr><td>&#64;columns</td>
<td>selects the columns that should be displayed. Default is
all.</td>
</tr>
<tr><td>&#64;filter</td>
<td>indicates which properties are being used in filtering.
Default is none.</td>
</tr>
<tr><td>propname</td>
<td>selects the values the item properties given by propname must
have (very basic search/filter).</td>
</tr>
<tr><td>&#64;search_text</td>
<td>performs a full-text search (message bodies, issue titles,
etc)</td>
</tr>
</tbody>
</table>
<p>You may manually write URLS that contain these arguments, like so
(whitespace has been added for clarity):</p>
<pre class="literal-block">
/issue?status=unread,in-progress,resolved&amp;
    topic=security,ui&amp;
    &#64;group=priority,-status&amp;
    &#64;sort=-activity&amp;
    &#64;filters=status,topic&amp;
    &#64;columns=title,status,fixer
</pre>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id17" id="access-controls" name="access-controls">Access Controls</a></h2>
<p>User access is controlled through Permissions. These are are grouped
into Roles, and users have a comma-separated list of Roles assigned to
them.</p>
<p>Permissions divide access controls up into answering questions like:</p>
<ul class="simple">
<li>may the user edit issues (&quot;Edit&quot;, &quot;issue&quot;)</li>
<li>is the user allowed to use the web interface (&quot;Web Access&quot;)</li>
<li>may the user edit other user's Roles through the web (&quot;Web Roles&quot;)</li>
</ul>
<p>Any number of new Permissions and Roles may be created as described in
the customisation documentation. Examples of new access controls are:</p>
<ul class="simple">
<li>only managers may sign off issues as complete</li>
<li>don't give users who register through e-mail web access</li>
<li>let some users edit the details of all users</li>
</ul>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id18" id="e-mail-gateway" name="e-mail-gateway">E-Mail Gateway</a></h1>
<p>Roundup trackers may be used to facilitate e-mail conversations around
issues. The &quot;nosy&quot; list attached to each issue indicates the users who
should receive e-mail when messages are added to the issue.</p>
<p>When e-mail comes into a tracker that identifies an issue in the subject
line, the content of the e-mail is attached to the issue.</p>
<p>You may even create new issues from e-mail messages.</p>
<p>E-mail sent to a tracker is examined for several pieces of information:</p>
<ol class="arabic simple">
<li><a class="reference" href="#subject-line-information">subject-line information</a> identifying the purpose of the e-mail</li>
<li><a class="reference" href="#sender-identification">sender identification</a> using the sender of the message</li>
<li><a class="reference" href="#e-mail-message-content">e-mail message content</a> which is to be extracted</li>
<li>e-mail attachments which should be associated with the message</li>
</ol>
<div class="section">
<h2><a class="toc-backref" href="#id19" id="subject-line-information" name="subject-line-information">Subject-line information</a></h2>
<p>The subject line of the incoming message is examined to find one of:</p>
<ol class="arabic simple">
<li>the item that the message is responding to,</li>
<li>the type of item the message should create, or</li>
<li>we default the item class and try some trickiness</li>
</ol>
<p>If the subject line contains a prefix in <tt class="docutils literal"><span class="pre">[square</span> <span class="pre">brackets]</span></tt> then
we're looking at case 1 or 2 above. Any &quot;re:&quot; or &quot;fwd:&quot; prefixes are
stripped off the subject line before we start looking for real
information.</p>
<p>If an item designator (class name and id number, for example
<tt class="docutils literal"><span class="pre">issue123</span></tt>) is found there, a new &quot;msg&quot; item is added to the
&quot;messages&quot; property for that item, and any new &quot;file&quot; items are added to
the &quot;files&quot; property for the item.</p>
<p>If just an item class name is found there, we attempt to create a new
item of that class with its &quot;messages&quot; property initialized to contain
the new &quot;msg&quot; item and its &quot;files&quot; property initialized to contain any
new &quot;file&quot; items.</p>
<p>The third case above - where no <tt class="docutils literal"><span class="pre">[information]</span></tt> is provided, the
tracker's <tt class="docutils literal"><span class="pre">MAIL_DEFAULT_CLASS</span></tt> configuration variable defines what
class of item the message relates to. We try to match the subject line
to an existing item of the default class, and if there's a match, the
message is related to that matched item. If not, then a new item of the
default class is created.</p>
<div class="section">
<h3><a class="toc-backref" href="#id20" id="setting-properties" name="setting-properties">Setting Properties</a></h3>
<p>The e-mail interface also provides a simple way to set properties on
items. At the end of the subject line, propname=value pairs can be
specified in square brackets, using the same conventions as for the
roundup set shell command.</p>
<p>For example,</p>
<ul>
<li><p class="first">setting the priority of an issue:</p>
<pre class="literal-block">
Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
</pre>
</li>
<li><p class="first">adding yourself to a nosy list:</p>
<pre class="literal-block">
Subject: Re: [issue2] we're out of widgets [nosy=+richard]
</pre>
</li>
<li><p class="first">setting the nosy list to just you and cliff:</p>
<pre class="literal-block">
Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
</pre>
</li>
<li><p class="first">removing yourself from a nosy list and setting the priority:</p>
<pre class="literal-block">
Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
</pre>
</li>
</ul>
<p>In all cases, the message relates to issue 2. The <tt class="docutils literal"><span class="pre">Re:</span></tt> prefix is
stripped off.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id21" id="automatic-properties" name="automatic-properties">Automatic Properties</a></h3>
<dl class="docutils">
<dt><strong>status of new issues</strong></dt>
<dd>When a new message is received that is not identified as being related
to an existing issue, it creates a new issue. The status of the new
issue is defaulted to &quot;unread&quot;.</dd>
<dt><strong>reopening of resolved issues</strong></dt>
<dd>When a message is is received for a resolved issue, the issue status is
automatically reset to &quot;chatting&quot; to indicate new information has been
received.</dd>
</dl>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id22" id="sender-identification" name="sender-identification">Sender identification</a></h2>
<p>If the sender of an e-mail is unknown to Roundup (looking up both user
primary e-mail addresses and their alternate addresses) then a new user
will be created. The new user will have their username set to the &quot;user&quot;
part of &quot;<a class="reference" href="mailto:user&#64;domain">user&#64;domain</a>&quot; in their e-mail address. Their password will be
completely randomised, and they'll have to visit the web interface to
have it changed. Some sites don't allow web access by users who register
via e-mail like this.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="e-mail-message-content" name="e-mail-message-content">E-Mail Message Content</a></h2>
<p>Roundup only associates plain text (MIME type <tt class="docutils literal"><span class="pre">text/plain</span></tt>) as
messages for items. Any other parts of a message are associated as
downloadable files. If no plain text part is found, the message is
rejected.</p>
<p>To do this, incoming messages are examined for multiple parts:</p>
<ul class="simple">
<li>In a multipart/mixed message or part, each subpart is extracted and
examined. The text/plain subparts are assembled to form the textual
body of the message, to be stored in the file associated with a &quot;msg&quot;
class item. Any parts of other types are each stored in separate files
and given &quot;file&quot; class items that are linked to the &quot;msg&quot; item.</li>
<li>In a multipart/alternative message or part, we look for a text/plain
subpart and ignore the other parts.</li>
</ul>
<p>If the message is a response to a previous message, and contains quoted
sections, then these will be stripped out of the message if the
<tt class="docutils literal"><span class="pre">EMAIL_KEEP_QUOTED_TEXT</span></tt> configuration variable is set to <tt class="docutils literal"><span class="pre">'no'</span></tt>.</p>
<div class="section">
<h3><a class="toc-backref" href="#id24" id="message-summary" name="message-summary">Message summary</a></h3>
<p>The &quot;summary&quot; property on message items is taken from the first
non-quoting section in the message body. The message body is divided
into sections by blank lines. Sections where the second and all
subsequent lines begin with a &quot;&gt;&quot; or &quot;|&quot; character are considered
&quot;quoting sections&quot;. The first line of the first non-quoting section
becomes the summary of the message.</p>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id25" id="address-handling" name="address-handling">Address handling</a></h2>
<p>All of the addresses in the <tt class="docutils literal"><span class="pre">To:</span></tt> and <tt class="docutils literal"><span class="pre">Cc:</span></tt> headers of the incoming
message are looked up among the tracker users, and the corresponding
users are placed in the &quot;recipients&quot; property on the new &quot;msg&quot; item. The
address in the <tt class="docutils literal"><span class="pre">From:</span></tt> header similarly determines the &quot;author&quot;
property of the new &quot;msg&quot; item. The default handling for addresses that
don't have corresponding users is to create new users with no passwords
and a username equal to the address.</p>
<p>The addresses mentioned in the <tt class="docutils literal"><span class="pre">To:</span></tt>, <tt class="docutils literal"><span class="pre">From:</span></tt> and <tt class="docutils literal"><span class="pre">Cc:</span></tt> headers of
the message may be added to the <a class="reference" href="#nosy-list">nosy list</a> depending on:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">ADD_AUTHOR_TO_NOSY</span></tt></dt>
<dd>Does the author of a message get placed on the nosy list automatically?
If 'new' is used, then the author will only be added when a message
creates a new issue. If 'yes', then the author will be added on
followups too. If 'no', they're never added to the nosy.</dd>
<dt><tt class="docutils literal"><span class="pre">ADD_RECIPIENTS_TO_NOSY</span></tt></dt>
<dd>Do the recipients (To:, Cc:) of a message get placed on the nosy list?
If 'new' is used, then the recipients will only be added when a message
creates a new issue. If 'yes', then the recipients will be added on
followups too. If 'no', they're never added to the nosy.</dd>
</dl>
<div class="section">
<h3><a class="toc-backref" href="#id26" id="nosy-list" name="nosy-list">Nosy List</a></h3>
<p>Roundup watches for additions to the &quot;messages&quot; property of items.</p>
<p>When a new message is added, it is sent to all the users on the &quot;nosy&quot;
list for the item that are not already on the &quot;recipients&quot; list of the
message. Those users are then appended to the &quot;recipients&quot; property on
the message, so multiple copies of a message are never sent to the same
user. The journal recorded by the hyperdatabase on the &quot;recipients&quot;
property then provides a log of when the message was sent to whom.</p>
<p>If the author of the message is also in the nosy list for the item that
the message is attached to, then the config var <tt class="docutils literal"><span class="pre">MESSAGES_TO_AUTHOR</span></tt>
is queried to determine if they get a nosy list copy of the message too.</p>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id27" id="mail-gateway-script-command-line" name="mail-gateway-script-command-line">Mail gateway script command line</a></h2>
<p>Usage:</p>
<pre class="literal-block">
roundup-mailgw [[-C class] -S field=value]* &lt;instance home&gt; [method]
</pre>
<p>The roundup mail gateway may be called in one of three ways:</p>
<blockquote>
<ul class="simple">
<li>with an instance home as the only argument,</li>
<li>with both an instance home and a mail spool file, or</li>
<li>with both an instance home and a pop server account.</li>
</ul>
</blockquote>
<p>It also supports optional -C and -S arguments that allows you to set a
fields for a class created by the roundup-mailgw. The default class if
not specified is msg, but the other classes: issue, file, user can also
be used. The -S or --set options uses the same
property=value[;property=value] notation accepted by the command line
roundup command or the commands that can be given on the Subject line of
an e-mail message.</p>
<p>It can let you set the type of the message on a per e-mail address basis.</p>
<dl class="docutils">
<dt>PIPE:</dt>
<dd>In the first case, the mail gateway reads a single message from the
standard input and submits the message to the roundup.mailgw module.</dd>
<dt>UNIX mailbox:</dt>
<dd><p class="first">In the second case, the gateway reads all messages from the mail spool
file and submits each in turn to the roundup.mailgw module. The file is
emptied once all messages have been successfully handled. The file is
specified as:</p>
<pre class="last literal-block">
mailbox /path/to/mailbox
</pre>
</dd>
<dt>POP:</dt>
<dd><p class="first">In the third case, the gateway reads all messages from the POP server
specified and submits each in turn to the roundup.mailgw module. The
server is specified as:</p>
<pre class="literal-block">
pop username:password&#64;server
</pre>
<p>The username and password may be omitted:</p>
<pre class="literal-block">
pop username&#64;server
pop server
</pre>
<p class="last">are both valid. The username and/or password will be prompted for if
not supplied on the command-line.</p>
</dd>
<dt>APOP:</dt>
<dd><p class="first">Same as POP, but using Authenticated POP:</p>
<pre class="last literal-block">
apop username:password&#64;server
</pre>
</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id28" id="command-line-tool" name="command-line-tool">Command Line Tool</a></h1>
<p>The basic usage is:</p>
<pre class="literal-block">
Usage: roundup-admin [options] [&lt;command&gt; &lt;arguments&gt;]

Options:
 -i instance home  -- specify the issue tracker &quot;home directory&quot; to administer
 -u                -- the user[:password] to use for commands
 -d                -- print full designators not just class id numbers
 -c                -- when outputting lists of data, comma-separate them.
              Same as '-S &quot;,&quot;'.
 -S &lt;string&gt;       -- when outputting lists of data, string-separate them
 -s                -- when outputting lists of data, space-separate them.
              Same as '-S &quot; &quot;'.

 Only one of -s, -c or -S can be specified.

Help:
 roundup-admin -h
 roundup-admin help                       -- this help
 roundup-admin help &lt;command&gt;             -- command-specific help
 roundup-admin help all                   -- all available help

Commands:
 commit
 create classname property=value ...
 display designator[,designator]*
 export [class[,class]] export_dir
 find classname propname=value ...
 get property designator[,designator]*
 help topic
 history designator
 import import_dir
 initialise [adminpw]
 install [template [backend [admin password]]]
 list classname [property]
 pack period | date
 reindex
 retire designator[,designator]*
 rollback
 security [Role name]
 set items property=value property=value ...
 specification classname
 table classname [property[,property]*]
Commands may be abbreviated as long as the abbreviation matches only one
command, e.g. l == li == lis == list.
</pre>
<p>All commands (except help) require a tracker specifier. This is just the
path to the roundup tracker you're working with. A roundup tracker is
where roundup keeps the database and configuration file that defines an
issue tracker. It may be thought of as the issue tracker's &quot;home
directory&quot;. It may be specified in the environment variable
<tt class="docutils literal"><span class="pre">TRACKER_HOME</span></tt> or on the command line as &quot;<tt class="docutils literal"><span class="pre">-i</span> <span class="pre">tracker</span></tt>&quot;.</p>
<p>A designator is a classname and an itemid concatenated, eg. bug1,
user10, ... Property values are represented as strings in command
arguments and in the printed results:</p>
<ul>
<li><p class="first">Strings are, well, strings.</p>
</li>
<li><p class="first">Password values will display as their encoded value.</p>
</li>
<li><p class="first">Date values are printed in the full date format in the local time
zone, and accepted in the full format or any of the partial formats
explained below.:</p>
<pre class="literal-block">
Input of...        Means...
&quot;2000-04-17.03:45&quot; 2000-04-17.03:45:00
&quot;2000-04-17&quot;       2000-04-17.00:00:00
&quot;01-25&quot;            yyyy-01-25.00:00:00
&quot;08-13.22:13&quot;      yyyy-08-13.22:13:00
&quot;11-07.09:32:43&quot;   yyyy-11-07.09:32:43
&quot;14:25&quot;            yyyy-mm-dd.14:25:00
&quot;8:47:11&quot;          yyyy-mm-dd.08:47:11
&quot;2003&quot;             2003-01-01.00:00:00
&quot;2003-04&quot;          2003-04-01.00:00:00
&quot;.&quot;                &quot;right now&quot;
</pre>
</li>
<li><p class="first">Link values are printed as item designators. When given as an
argument, item designators and key strings are both accepted.</p>
</li>
<li><p class="first">Multilink values are printed as lists of item designators joined by
commas. When given as an argument, item designators and key strings
are both accepted; an empty string, a single item, or a list of items
joined by commas is accepted.</p>
</li>
</ul>
<p>When multiple items are specified to the roundup get or roundup set
commands, the specified properties are retrieved or set on all the
listed items.  When multiple results are returned by the roundup get or
roundup find commands, they are printed one per line (default) or joined
by commas (with the &quot;<tt class="docutils literal"><span class="pre">-c</span></tt>&quot; option).</p>
<p>Where the command changes data, a login name/password is required. The
login may be specified as either &quot;<tt class="docutils literal"><span class="pre">name</span></tt>&quot; or &quot;<tt class="docutils literal"><span class="pre">name:password</span></tt>&quot;.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">ROUNDUP_LOGIN</span></tt> environment variable</li>
<li>the &quot;<tt class="docutils literal"><span class="pre">-u</span></tt>&quot; command-line option</li>
</ul>
<p>If either the name or password is not supplied, they are obtained from
the command-line.</p>
<div class="section">
<h2><a class="toc-backref" href="#id29" id="using-with-the-shell" name="using-with-the-shell">Using with the shell</a></h2>
<p>With version 0.6.0 or newer of roundup which supports: multiple
designators to display and the -d, -S and -s flags.</p>
<p>To find all messages regarding chatting issues that contain the word
&quot;spam&quot;, for example, you could execute the following command from the
directory where the database dumps its files:</p>
<pre class="literal-block">
shell% for issue in `roundup-admin -ds find issue status=chatting`; do
&gt; grep -l spam `roundup-admin -ds ' ' get messages $issue`
&gt; done
msg23
msg49
msg50
msg61
shell%
</pre>
<p>Or, using the -dc option, this can be written as a single command:</p>
<pre class="literal-block">
shell% grep -l spam `roundup get messages \
    \`roundup -dc find issue status=chatting\``
msg23
msg49
msg50
msg61
shell%
</pre>
<p>You can also display issue contents:</p>
<pre class="literal-block">
shell% roundup-admin display `roundup-admin -dc get messages \
           issue3,issue1`
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-16.21:23:03
messageid: None
summary: jkdskldjf
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-15.01:59:11
messageid: None
summary: jlkfjadsf
</pre>
<p>or status:</p>
<pre class="literal-block">
shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
      -dc -i /var/roundup/sysadmin get status issue3,issue1`
unread
deferred
</pre>
<p>or status on a single line:</p>
<pre class="literal-block">
shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
         -dc -i /var/roundup/sysadmin get status issue3,issue1\``
unread deferred
</pre>
<p>which is the same as:</p>
<pre class="literal-block">
shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
         -dc -i /var/roundup/sysadmin get status issue3,issue1`
unread deferred
</pre>
<p>Also the tautological:</p>
<pre class="literal-block">
shell% roundup-admin get name \
   `roundup-admin -dc get status \`roundup-admin -dc find issue \
       status=chatting\``
chatting
chatting
</pre>
<p>Remember the roundup commands that accept multiple designators accept
them ',' separated so using '-dc' is almost always required.</p>
<hr class="docutils" />
<p>Back to <a class="reference" href="index.html">Table of Contents</a></p>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2006-10-04.

</div>
</body>
</html>