Code

oops, fixed unit tests for journal change
[roundup.git] / doc / user_guide.txt
1 ==========
2 User Guide
3 ==========
5 :Version: $Revision: 1.11 $
7 .. contents::
9 Note: this document will refer to *issues* as the primary store of information
10 in the tracker. This is the default of the classic template, bubt may vary in
11 any given installation.
13 Your Tracker in a Nutshell
14 ==========================
16 Your tracker holds information about issues in bundles we call *items*. An
17 item may be an *issue* (a bug or feature request) or a *user*. The issue-ness or
18 user-ness is called the item's *class*. So, for bug reports and features, the
19 class is "issue", and for users the class is "user".
21 Each item in the tracker has an id number that identifies it along with its
22 item class. To identify a particular issue or user, we combine the class with
23 the number to create a unique label, so that user 1 (who, incidentally, is
24 *always* the "admin" user) is referred to as "user1".  Issue number 315 is
25 referred to as "issue315". We call that label the item's *designator*.
27 Accessing the Tracker
28 ---------------------
30 You may access your tracker through one of three ways:
32 1. through the `web interface`_,
33 2. through the `e-mail gateway`_, or
34 3. using the `command line tool`_.
36 The last is usually only used by administrators. Most users will use the web
37 and email interfaces. All three are explained below.
40 Web Interface
41 =============
43 Note: this document contains screenshots of the default look and feel. Your
44 site may have a slightly (or very) different look, but the functionality will
45 be very similar, and the concepts still hold.
47 The web interface is broken up into the following parts:
49 1. `lists of items`_,
50 2. `display, edit or entry of an item`_, and
51 3. `searching page`_.
54 Lists of Items
55 --------------
57 The first thing you'll see when you log into Roundup will be a list of open
58 (ie. not resolved) issues. This list has been generated by a bunch of controls
59 `under the covers`_ but for now, you can see something like:
61 .. img: images/index_logged_out.png
63 The screen is divided up into three sections:
65 .. img: images/page_layout.png
67 you may either register or log in. Registration takes you to:
69 .. img: images/registration.png
71 Once you're logged in, the screen changes slightly to:
73 .. img: images/index_logged_in.png
75 Note that the sidebar menu has changed slightly, so you can now get to your
76 "My Details" page:
78 .. img: images/my_details.png
80 Note the new information on this page - the history.
83 Display, edit or entry of an item
84 ---------------------------------
86 Create a new issue with "create new" under the issue subheading. This will
87 take you to:
89 .. img: images/new_issue.png
91 The `nosy list`_ is explained below.
92 Enter some information and click "submit new entry" and you'll be rewarded
93 with:
95 .. img: images/new_issue_created.png
97 or, if you don't enter all the required information (or some other error
98 occurs) you'll get something like:
100 .. img: images/new_issue_error.png
103 Searching Page
104 --------------
106 XXX: some information about how searching works
109 Under the covers
110 ----------------
112 Index views may be modified by the following arguments:
114 ========== =============================================================
115 Argument   Description
116 ========== =============================================================
117 :sort      sort by prop name, optionally preceeded with '-'
118            to give descending or nothing for ascending sorting.
119 :group     group by prop name, optionally preceeded with '-' or
120            to sort in descending or nothing for ascending order.
121 :filter    selects which props should be displayed in the filter
122            section. Default is all.           
123 :columns   selects the columns that should be displayed.
124            Default is all.                     
125 propname   selects the values the item properties given by propname
126            must have (very basic search/filter).
127 ========== =============================================================
129 Access Controls
130 ---------------
132 XXX
135 E-Mail Gateway
136 ==============
138 E-mail sent to Roundup is examined for several pieces of information:
140 1. `subject-line information`_ identifying the purpose of the e-mail
141 2. `e-mail message content`_ which is to be extracted
142 3. e-mail attachments which should be associated with the message
144 Subject-line information
145 ------------------------
147 The subject line of the incoming message is examined to find one of:
149 1. the item that the message is responding to,
150 2. the type of item the message should create, or
151 3. we default the item class and try some trickiness
153 If the subject line contains a prefix in ``[square brackets]`` then we're
154 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
155 stripped off the subject line before we start looking for real information.
157 If an item designator (class name and id number, for example ``issue123``)
158 is found there, a new "msg" item is added to the "messages" property for
159 that item, and any new "file" items are added to the "files" property for
160 the item.
162 If just an item class name is found there, we attempt to create a new item of
163 that class with its "messages" property initialized to contain the new "msg"
164 item and its "files" property initialized to contain any new "file" items.
166 The third case above - where no ``[information]`` is provided, the tracker's
167 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
168 the message relates to. We try to match the subject line to an existing
169 item of the default class, and if there's a match, the message is related to
170 that matched item. If not, then a new item of the default class is created.
172 Setting Properties
173 ~~~~~~~~~~~~~~~~~~
175 The e-mail interface also provides a simple way to set properties on items. At
176 the end of the subject line, propname=value pairs can be specified in square
177 brackets, using the same conventions as for the roundup set shell command.
179 For example,
181 - setting the priority of an issue::
183    Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
185 - adding yourself to a nosy list::
187    Subject: Re: [issue2] we're out of widgets [nosy=+richard]
189 - setting the nosy list to just you and cliff::
191    Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
193 - removing yourself from a nosy list and setting the priority::
195    Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
197 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
198 off.
201 Automatic Properties
202 ~~~~~~~~~~~~~~~~~~~~
204 **status of new issues**
205  When a new message is received that is not identified as being related to an
206  existing issue, it creates a new issue. The status of the new issue is
207  defaulted to "unread".
209 **reopening of resolved issues**
210  When a message is is received for a resolved issue, the issue status is
211  automatically reset to "chatting" to indicate new information has been
212  received.
215 E-Mail Message Content
216 ----------------------
218 Roundup only associates plain text (MIME type ``text/plain``) as messages for
219 items. Any other parts of a message are associated as downloadable files. If
220 no plain text part is found, the message is rejected.
222 To do this, incoming messages are examined for multiple parts:
224 * In a multipart/mixed message or part, each subpart is extracted and
225   examined. The text/plain subparts are assembled to form the textual body
226   of the message, to be stored in the file associated with a "msg" class
227   item. Any parts of other types are each stored in separate files and
228   given "file" class items that are linked to the "msg" item.
229 * In a multipart/alternative message or part, we look for a text/plain
230   subpart and ignore the other parts.
232 If the message is a response to a previous message, and contains quoted
233 sections, then these will be stripped out of the message if the
234 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
236 Message summary
237 ~~~~~~~~~~~~~~~
239 The "summary" property on message items is taken from the first non-quoting
240 section in the message body. The message body is divided into sections by blank
241 lines. Sections where the second and all subsequent lines begin with a ">" or
242 "|" character are considered "quoting sections". The first line of the first
243 non-quoting section becomes the summary of the message.
246 Address handling
247 ----------------
249 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
250 message are
251 looked up among the tracker users, and the corresponding users are placed
252 in the
253 "recipients" property on the new "msg" item. The address in the ``From:`` header
254 similarly determines the "author" property of the new "msg" item. The default
255 handling for addresses that don't have corresponding users is to create new
256 users with no passwords and a username equal to the address.
258 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
259 the message may be added to the `nosy list`_ depending on:
261 ``ADD_AUTHOR_TO_NOSY``
262  Does the author of a message get placed on the nosy list automatically?
263  If 'new' is used, then the author will only be added when a message
264  creates a new issue. If 'yes', then the author will be added on followups
265  too. If 'no', they're never added to the nosy.
267 ``ADD_RECIPIENTS_TO_NOSY``
268  Do the recipients (To:, Cc:) of a message get placed on the nosy list?
269  If 'new' is used, then the recipients will only be added when a message
270  creates a new issue. If 'yes', then the recipients will be added on
271  followups too. If 'no', they're never added to the nosy.
274 Nosy List
275 ~~~~~~~~~
277 Roundup watches for additions to the "messages" property of items.
279 When a new message is added, it is sent to all the users
280 on the "nosy" list for the item that are not already on the "recipients" list
281 of the message. Those users are then appended to the "recipients" property on
282 the message, so multiple copies of a message are never sent to the same user.
283 The journal recorded by the hyperdatabase on the "recipients" property then
284 provides a log of when the message was sent to whom.
286 If the author of the message is also in the nosy list for the item that the
287 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
288 to determine if they get a nosy list copy of the message too.
291 Command Line Tool
292 =================
294 The basic usage is::
296  Help:
297  roundup-admin -h
298   roundup-admin help                       -- this help
299   roundup-admin help <command>             -- command-specific help
300   roundup-admin help all                   -- all available help
302  Options:
303   -i instance home  -- specify the issue tracker "home directory" to administer
304   -u                -- the user[:password] to use for commands
305   -c                -- when outputting lists of data, just comma-separate them
307  Commands:
308   commit
309   create classname property=value ...
310   display designator
311   export [class[,class]] export_dir
312   find classname propname=value ...
313   get property designator[,designator]*
314   help topic
315   history designator
316   import import_dir
317   initialise [adminpw]
318   install [template [backend [admin password]]]
319   list classname [property]
320   pack period | date
321   reindex
322   retire designator[,designator]*
323   rollback
324   security [Role name]
325   set designator[,designator]* propname=value ...
326   specification classname
327   table classname [property[,property]*]
329 Commands may be abbreviated as long as the abbreviation matches only one
330 command, e.g. l == li == lis == list.
332 All commands (except help) require a tracker specifier. This is just the
333 path to the roundup tracker you're working with. A roundup tracker is where
334 roundup keeps the database and configuration file that defines an issue
335 tracker. It may be thought of as the issue tracker's "home directory".
336 It may be specified in the environment variable ``TRACKER_HOME`` or on
337 the command line as "``-i tracker``".
339 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
340 Property values are represented as strings in command arguments and in the printed
341 results:
343 - Strings are, well, strings.
344 - Password values will display as their encoded value.
345 - Date values are printed in the full date format in the local time zone,
346   and accepted in the full format or any of the partial formats explained
347   below.::
348   
349     Input of...        Means...
350     "2000-04-17.03:45" 2000-04-17.08:45:00
351     "2000-04-17"       2000-04-17.00:00:00
352     "01-25"            yyyy-01-25.00:00:00
353     "08-13.22:13"      yyyy-08-14.03:13:00
354     "11-07.09:32:43"   yyyy-11-07.14:32:43
355     "14:25"            yyyy-mm-dd.19:25:00
356     "8:47:11"          yyyy-mm-dd.13:47:11
357     "."                "right now"
358     
359 - Link values are printed as item designators. When given as an argument,
360   item designators and key strings are both accepted.
361 - Multilink values are printed as lists of item designators joined by
362   commas. When given as an argument, item designators and key strings are
363   both accepted; an empty string, a single item, or a list of items joined
364   by commas is accepted.
365   
366 When multiple items are specified to the roundup get or roundup set
367 commands, the specified properties are retrieved or set on all the listed
368 items.  When multiple results are returned by the roundup get or roundup
369 find commands, they are printed one per line (default) or joined by commas
370 (with the "``-c``" option).
372 Where the command changes data, a login name/password is required. The login may
373 be specified as either "``name``" or "``name:password``".
375 - ``ROUNDUP_LOGIN`` environment variable
376 - the "``-u``" command-line option
378 If either the name or password is not supplied, they are obtained from the
379 command-line.
383 -----------------
385 Back to `Table of Contents`_
387 .. _`Table of Contents`: index.html