1 ==========
2 User Guide
3 ==========
5 :Version: $Revision: 1.14 $
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
108 Some fields in the search page (e.g. "Activity" or "Creation date") accept
109 ranges of dates. You can specify range of dates in one of two formats:
111 1. Native english syntax:
112 [[From] <value>][ To <value>]
113 Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
115 2. "Geek" syntax:
116 [<value>][; <value>]
118 Either first or second <value> can be omitted in both syntaxes.
120 For example:
122 if you enter string "from 9:00" to "Creation date" field, roundup
123 will find all issues, that were created today since 9 AM.
125 Searching of "-2m; -1m" on activity field gives you issues, which were
126 active between period of time since 2 months up-till month ago.
128 Other possible examples (consider local time is Sat Mar 8 22:07:48 EET 2003):
130 >>> Range("from 2-12 to 4-2")
131 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
133 >>> Range("18:00 TO +2m")
134 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
136 >>> Range("12:00")
137 <Range from 2003-03-08.12:00:00 to None>
139 >>> Range("tO +3d")
140 <Range from None to 2003-03-11.20:07:48>
142 >>> Range("2002-11-10; 2002-12-12")
143 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
145 >>> Range("; 20:00 +1d")
146 <Range from None to 2003-03-09.20:00:00>
149 Under the covers
150 ----------------
152 Index views may be modified by the following arguments:
154 ========== =============================================================
155 Argument Description
156 ========== =============================================================
157 :sort sort by prop name, optionally preceeded with '-'
158 to give descending or nothing for ascending sorting.
159 :group group by prop name, optionally preceeded with '-' or
160 to sort in descending or nothing for ascending order.
161 :filter selects which props should be displayed in the filter
162 section. Default is all.
163 :columns selects the columns that should be displayed.
164 Default is all.
165 propname selects the values the item properties given by propname
166 must have (very basic search/filter).
167 ========== =============================================================
169 Access Controls
170 ---------------
172 User access is controlled through Permissions. These are are grouped into
173 Roles, and users have a comma-separated list of Roles assigned to them.
175 Permissions divide access controls up into answering questions like:
177 - may the user edit issues ("Edit", "issue")
178 - is the user allowed to use the web interface ("Web Access")
179 - may the user edit other user's Roles through the web ("Web Roles")
181 Any number of new Permissions and Roles may be created as described in the
182 customisation documentation. Examples of new access controls are:
184 - only managers may sign off issues as complete
185 - don't give users who register through email web access
186 - let some users edit the details of all users
189 E-Mail Gateway
190 ==============
192 E-mail sent to Roundup is examined for several pieces of information:
194 1. `subject-line information`_ identifying the purpose of the e-mail
195 2. `e-mail message content`_ which is to be extracted
196 3. e-mail attachments which should be associated with the message
198 Subject-line information
199 ------------------------
201 The subject line of the incoming message is examined to find one of:
203 1. the item that the message is responding to,
204 2. the type of item the message should create, or
205 3. we default the item class and try some trickiness
207 If the subject line contains a prefix in ``[square brackets]`` then we're
208 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
209 stripped off the subject line before we start looking for real information.
211 If an item designator (class name and id number, for example ``issue123``)
212 is found there, a new "msg" item is added to the "messages" property for
213 that item, and any new "file" items are added to the "files" property for
214 the item.
216 If just an item class name is found there, we attempt to create a new item of
217 that class with its "messages" property initialized to contain the new "msg"
218 item and its "files" property initialized to contain any new "file" items.
220 The third case above - where no ``[information]`` is provided, the tracker's
221 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
222 the message relates to. We try to match the subject line to an existing
223 item of the default class, and if there's a match, the message is related to
224 that matched item. If not, then a new item of the default class is created.
226 Setting Properties
227 ~~~~~~~~~~~~~~~~~~
229 The e-mail interface also provides a simple way to set properties on items. At
230 the end of the subject line, propname=value pairs can be specified in square
231 brackets, using the same conventions as for the roundup set shell command.
233 For example,
235 - setting the priority of an issue::
237 Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
239 - adding yourself to a nosy list::
241 Subject: Re: [issue2] we're out of widgets [nosy=+richard]
243 - setting the nosy list to just you and cliff::
245 Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
247 - removing yourself from a nosy list and setting the priority::
249 Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
251 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
252 off.
255 Automatic Properties
256 ~~~~~~~~~~~~~~~~~~~~
258 **status of new issues**
259 When a new message is received that is not identified as being related to an
260 existing issue, it creates a new issue. The status of the new issue is
261 defaulted to "unread".
263 **reopening of resolved issues**
264 When a message is is received for a resolved issue, the issue status is
265 automatically reset to "chatting" to indicate new information has been
266 received.
269 E-Mail Message Content
270 ----------------------
272 Roundup only associates plain text (MIME type ``text/plain``) as messages for
273 items. Any other parts of a message are associated as downloadable files. If
274 no plain text part is found, the message is rejected.
276 To do this, incoming messages are examined for multiple parts:
278 * In a multipart/mixed message or part, each subpart is extracted and
279 examined. The text/plain subparts are assembled to form the textual body
280 of the message, to be stored in the file associated with a "msg" class
281 item. Any parts of other types are each stored in separate files and
282 given "file" class items that are linked to the "msg" item.
283 * In a multipart/alternative message or part, we look for a text/plain
284 subpart and ignore the other parts.
286 If the message is a response to a previous message, and contains quoted
287 sections, then these will be stripped out of the message if the
288 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
290 Message summary
291 ~~~~~~~~~~~~~~~
293 The "summary" property on message items is taken from the first non-quoting
294 section in the message body. The message body is divided into sections by blank
295 lines. Sections where the second and all subsequent lines begin with a ">" or
296 "|" character are considered "quoting sections". The first line of the first
297 non-quoting section becomes the summary of the message.
300 Address handling
301 ----------------
303 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
304 message are
305 looked up among the tracker users, and the corresponding users are placed
306 in the
307 "recipients" property on the new "msg" item. The address in the ``From:`` header
308 similarly determines the "author" property of the new "msg" item. The default
309 handling for addresses that don't have corresponding users is to create new
310 users with no passwords and a username equal to the address.
312 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
313 the message may be added to the `nosy list`_ depending on:
315 ``ADD_AUTHOR_TO_NOSY``
316 Does the author of a message get placed on the nosy list automatically?
317 If 'new' is used, then the author will only be added when a message
318 creates a new issue. If 'yes', then the author will be added on followups
319 too. If 'no', they're never added to the nosy.
321 ``ADD_RECIPIENTS_TO_NOSY``
322 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
323 If 'new' is used, then the recipients will only be added when a message
324 creates a new issue. If 'yes', then the recipients will be added on
325 followups too. If 'no', they're never added to the nosy.
328 Nosy List
329 ~~~~~~~~~
331 Roundup watches for additions to the "messages" property of items.
333 When a new message is added, it is sent to all the users
334 on the "nosy" list for the item that are not already on the "recipients" list
335 of the message. Those users are then appended to the "recipients" property on
336 the message, so multiple copies of a message are never sent to the same user.
337 The journal recorded by the hyperdatabase on the "recipients" property then
338 provides a log of when the message was sent to whom.
340 If the author of the message is also in the nosy list for the item that the
341 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
342 to determine if they get a nosy list copy of the message too.
345 Mail gateway script command line
346 --------------------------------
348 The roundup mail gateway may be called in one of three ways:
350 . with an instance home as the only argument,
351 . with both an instance home and a mail spool file, or
352 . with both an instance home and a pop server account.
354 It also supports optional -C and -S arguments that allows you to set a
355 fields for a class created by the roundup-mailgw. The default class if
356 not specified is msg, but the other classes: issue, file, user can
357 also be used. The -S or --set options uses the same
358 property=value[;property=value] notation accepted by the command line
359 roundup command or the commands that can be given on the Subject line
360 of an email message.
362 It can let you set the type of the message on a per email address basis.
364 PIPE:
365 In the first case, the mail gateway reads a single message from the
366 standard input and submits the message to the roundup.mailgw module.
368 UNIX mailbox:
369 In the second case, the gateway reads all messages from the mail spool
370 file and submits each in turn to the roundup.mailgw module. The file is
371 emptied once all messages have been successfully handled. The file is
372 specified as::
374 mailbox /path/to/mailbox
376 POP:
377 In the third case, the gateway reads all messages from the POP server
378 specified and submits each in turn to the roundup.mailgw module. The
379 server is specified as::
380 pop username:password@server
382 The username and password may be omitted::
383 pop username@server
384 pop server
386 are both valid. The username and/or password will be prompted for if
387 not supplied on the command-line.
390 Command Line Tool
391 =================
393 The basic usage is::
395 Help:
396 roundup-admin -h
397 roundup-admin help -- this help
398 roundup-admin help <command> -- command-specific help
399 roundup-admin help all -- all available help
401 Options:
402 -i instance home -- specify the issue tracker "home directory" to administer
403 -u -- the user[:password] to use for commands
404 -c -- when outputting lists of data, just comma-separate them
406 Commands:
407 commit
408 create classname property=value ...
409 display designator
410 export [class[,class]] export_dir
411 find classname propname=value ...
412 get property designator[,designator]*
413 help topic
414 history designator
415 import import_dir
416 initialise [adminpw]
417 install [template [backend [admin password]]]
418 list classname [property]
419 pack period | date
420 reindex
421 retire designator[,designator]*
422 rollback
423 security [Role name]
424 set designator[,designator]* propname=value ...
425 specification classname
426 table classname [property[,property]*]
428 Commands may be abbreviated as long as the abbreviation matches only one
429 command, e.g. l == li == lis == list.
431 All commands (except help) require a tracker specifier. This is just the
432 path to the roundup tracker you're working with. A roundup tracker is where
433 roundup keeps the database and configuration file that defines an issue
434 tracker. It may be thought of as the issue tracker's "home directory".
435 It may be specified in the environment variable ``TRACKER_HOME`` or on
436 the command line as "``-i tracker``".
438 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
439 Property values are represented as strings in command arguments and in the printed
440 results:
442 - Strings are, well, strings.
443 - Password values will display as their encoded value.
444 - Date values are printed in the full date format in the local time zone,
445 and accepted in the full format or any of the partial formats explained
446 below.::
448 Input of... Means...
449 "2000-04-17.03:45" 2000-04-17.08:45:00
450 "2000-04-17" 2000-04-17.00:00:00
451 "01-25" yyyy-01-25.00:00:00
452 "08-13.22:13" yyyy-08-14.03:13:00
453 "11-07.09:32:43" yyyy-11-07.14:32:43
454 "14:25" yyyy-mm-dd.19:25:00
455 "8:47:11" yyyy-mm-dd.13:47:11
456 "." "right now"
458 - Link values are printed as item designators. When given as an argument,
459 item designators and key strings are both accepted.
460 - Multilink values are printed as lists of item designators joined by
461 commas. When given as an argument, item designators and key strings are
462 both accepted; an empty string, a single item, or a list of items joined
463 by commas is accepted.
465 When multiple items are specified to the roundup get or roundup set
466 commands, the specified properties are retrieved or set on all the listed
467 items. When multiple results are returned by the roundup get or roundup
468 find commands, they are printed one per line (default) or joined by commas
469 (with the "``-c``" option).
471 Where the command changes data, a login name/password is required. The login may
472 be specified as either "``name``" or "``name:password``".
474 - ``ROUNDUP_LOGIN`` environment variable
475 - the "``-u``" command-line option
477 If either the name or password is not supplied, they are obtained from the
478 command-line.
482 -----------------
484 Back to `Table of Contents`_
486 .. _`Table of Contents`: index.html
487 .. _`customisation documentation`: customizing.html