1 ==========
2 User Guide
3 ==========
5 :Version: $Revision: 1.22 $
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*.
28 Accessing the Tracker
29 ---------------------
31 You may access your tracker through one of three ways:
33 1. through the `web interface`_,
34 2. through the `e-mail gateway`_, or
35 3. using the `command line tool`_.
37 The last is usually only used by administrators. Most users will use the web
38 and email interfaces. All three are explained below.
41 Issue life cycles in Roundup
42 ----------------------------
44 New issues may be submitted via the web or email.
46 By default, the issue will have the status "unread". If another message is
47 received for the issue, its status will change to "chatting".
49 The "home" page for a tracker will generally display all issues which are
50 not "resolved.
52 If an issue is closed, and a new message is received then it'll be reopened
53 to the state of "chatting".
56 Entering values in your Tracker
57 -------------------------------
59 All interfaces to your tracker use the same format for entering values. This
60 means the web interface for entering a new issue, the web interface for
61 searching issues, the email interface and even the command-line administration
62 tool.
65 String and Numeric properties
66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68 These fields just take a simple text value, like ``It's broken``.
71 Boolean properties
72 ~~~~~~~~~~~~~~~~~~
74 These fields take a value which indicates "yes"/"no", "true"/"false",
75 "1"/"0" or "on"/"off".
78 Constrained (link and multilink) properties
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81 Fields like "Assigned To" and "Topics" hold references to items in other
82 classes ("user" and "keyword" in those two cases.)
84 Sometimes, the selection is done through a menu, like in the "Assigned To"
85 field.
87 Where the input is not a simple menu selection, we use a comma-separated
88 list of values to indicated which values of "user" or "keyword" are
89 interesting. The values may be either numeric ids or the
90 names of items. The special value "-1" may be used to match items where the
91 property is not set. For example, the following searches on the issues:
93 ``assignedto=richard,george``
94 match issues which are assigned to richard or george.
95 ``assignedto=-1``
96 match issues that are not assigned to a user.
97 ``assignedto=2,3,40``
98 match issues that are assigned to users 2, 3 or 40.
99 ``topic=user interface``
100 match issues with the keyword "user interface" in their topic list
101 ``topic=web interface,email interface``
102 match issues with the keyword "web interface" or "email interface" in
103 their topic list
104 ``topic=-1``
105 match issues with no topics set
108 Date properties
109 ~~~~~~~~~~~~~~~
111 Some fields in the search page (e.g. "Activity" or "Creation date") hold
112 dates. A plain date entered as a search field will match that date exactly
113 in the database. We may also accept ranges of dates. You can specify range
114 of dates in one of two formats:
116 1. English syntax::
118 [From <value>][To <value>]
120 Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
122 2. "Geek" syntax::
124 [<value>];[<value>]
126 Either first or second ``<value>`` can be omitted in both syntaxes.
128 For example, if you enter string "from 9:00" to "Creation date" field,
129 roundup will find all issues, that were created today since 9 AM.
131 Searching of "-2m; -1m" on activity field gives you issues which were
132 active between period of time since 2 months up-till month ago.
134 Other possible examples (consider local time is Sat Mar 8 22:07:48 2003)::
136 >>> Range("from 2-12 to 4-2")
137 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
139 >>> Range("FROM 18:00 TO +2m")
140 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
142 >>> Range("12:00;")
143 <Range from 2003-03-08.12:00:00 to None>
145 >>> Range("tO +3d")
146 <Range from None to 2003-03-11.20:07:48>
148 >>> Range("2002-11-10; 2002-12-12")
149 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
151 >>> Range("; 20:00 +1d")
152 <Range from None to 2003-03-09.20:00:00>
154 >>> Range("2003")
155 <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
157 >>> Range("2003-04")
158 <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
161 Interval properties
162 ~~~~~~~~~~~~~~~~~~~
164 XXX explain...
166 When searching on interval properties use the same syntax as for dates.
169 Web Interface
170 =============
172 Note: this document contains screenshots of the default look and feel. Your
173 site may have a slightly (or very) different look, but the functionality will
174 be very similar, and the concepts still hold.
176 The web interface is broken up into the following parts:
178 1. `lists of items`_,
179 2. `display, edit or entry of an item`_, and
180 3. `searching page`_.
183 Lists of Items
184 --------------
186 The first thing you'll see when you log into Roundup will be a list of open
187 (ie. not resolved) issues. This list has been generated by a bunch of controls
188 `under the covers`_ but for now, you can see something like:
190 .. img: images/index_logged_out.png
192 The screen is divided up into three sections:
194 .. img: images/page_layout.png
196 you may either register or log in. Registration takes you to:
198 .. img: images/registration.png
200 Once you're logged in, the screen changes slightly to:
202 .. img: images/index_logged_in.png
204 Note that the sidebar menu has changed slightly, so you can now get to your
205 "My Details" page:
207 .. img: images/my_details.png
209 Note the new information on this page - the history.
212 Display, edit or entry of an item
213 ---------------------------------
215 Create a new issue with "create new" under the issue subheading. This will
216 take you to:
218 .. img: images/new_issue.png
220 The `nosy list`_ is explained below.
221 Enter some information and click "submit new entry" and you'll be rewarded
222 with:
224 .. img: images/new_issue_created.png
226 or, if you don't enter all the required information (or some other error
227 occurs) you'll get something like:
229 .. img: images/new_issue_error.png
232 Searching Page
233 --------------
235 See `entering values in your tracker`_ for an explanation of what you may
236 type into the search form.
240 Under the covers
241 ~~~~~~~~~~~~~~~~
243 The searching page converts your selections into the following arguments:
245 ========== =============================================================
246 Argument Description
247 ========== =============================================================
248 :sort sort by prop name, optionally preceeded with '-'
249 to give descending or nothing for ascending sorting.
250 :group group by prop name, optionally preceeded with '-' or
251 to sort in descending or nothing for ascending order.
252 :filter selects which props should be displayed in the filter
253 section. Default is all.
254 :columns selects the columns that should be displayed.
255 Default is all.
256 propname selects the values the item properties given by propname
257 must have (very basic search/filter).
258 ========== =============================================================
260 You may manually write URLS that contain these arguments, like so (whitespace
261 has been added for clarity)::
263 /issue?status=unread,in-progress,resolved&
264 topic=security,ui&
265 :group=priority&
266 :sort=-activity&
267 :filters=status,topic&
268 :columns=title,status,fixer
271 Access Controls
272 ---------------
274 User access is controlled through Permissions. These are are grouped into
275 Roles, and users have a comma-separated list of Roles assigned to them.
277 Permissions divide access controls up into answering questions like:
279 - may the user edit issues ("Edit", "issue")
280 - is the user allowed to use the web interface ("Web Access")
281 - may the user edit other user's Roles through the web ("Web Roles")
283 Any number of new Permissions and Roles may be created as described in the
284 customisation documentation. Examples of new access controls are:
286 - only managers may sign off issues as complete
287 - don't give users who register through email web access
288 - let some users edit the details of all users
291 E-Mail Gateway
292 ==============
294 E-mail sent to Roundup is examined for several pieces of information:
296 1. `subject-line information`_ identifying the purpose of the e-mail
297 2. `sender identification`_ using the sender of the message
298 3. `e-mail message content`_ which is to be extracted
299 4. e-mail attachments which should be associated with the message
301 Subject-line information
302 ------------------------
304 The subject line of the incoming message is examined to find one of:
306 1. the item that the message is responding to,
307 2. the type of item the message should create, or
308 3. we default the item class and try some trickiness
310 If the subject line contains a prefix in ``[square brackets]`` then we're
311 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
312 stripped off the subject line before we start looking for real information.
314 If an item designator (class name and id number, for example ``issue123``)
315 is found there, a new "msg" item is added to the "messages" property for
316 that item, and any new "file" items are added to the "files" property for
317 the item.
319 If just an item class name is found there, we attempt to create a new item of
320 that class with its "messages" property initialized to contain the new "msg"
321 item and its "files" property initialized to contain any new "file" items.
323 The third case above - where no ``[information]`` is provided, the tracker's
324 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
325 the message relates to. We try to match the subject line to an existing
326 item of the default class, and if there's a match, the message is related to
327 that matched item. If not, then a new item of the default class is created.
329 Setting Properties
330 ~~~~~~~~~~~~~~~~~~
332 The e-mail interface also provides a simple way to set properties on items. At
333 the end of the subject line, propname=value pairs can be specified in square
334 brackets, using the same conventions as for the roundup set shell command.
336 For example,
338 - setting the priority of an issue::
340 Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
342 - adding yourself to a nosy list::
344 Subject: Re: [issue2] we're out of widgets [nosy=+richard]
346 - setting the nosy list to just you and cliff::
348 Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
350 - removing yourself from a nosy list and setting the priority::
352 Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
354 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
355 off.
358 Automatic Properties
359 ~~~~~~~~~~~~~~~~~~~~
361 **status of new issues**
362 When a new message is received that is not identified as being related to an
363 existing issue, it creates a new issue. The status of the new issue is
364 defaulted to "unread".
366 **reopening of resolved issues**
367 When a message is is received for a resolved issue, the issue status is
368 automatically reset to "chatting" to indicate new information has been
369 received.
372 Sender identification
373 ---------------------
375 If the sender of an email is unknown to Roundup (looking up both user
376 primary email addresses and their alternate addresses) then a new user will
377 be created. The new user will have their username set to the "user" part of
378 "user@domain" in their email address. Their password will be completely
379 randomised, and they'll have to visit the web interface to have it
380 changed. Note that some sites don't allow web access by users who register
381 via email like this.
384 E-Mail Message Content
385 ----------------------
387 Roundup only associates plain text (MIME type ``text/plain``) as messages for
388 items. Any other parts of a message are associated as downloadable files. If
389 no plain text part is found, the message is rejected.
391 To do this, incoming messages are examined for multiple parts:
393 * In a multipart/mixed message or part, each subpart is extracted and
394 examined. The text/plain subparts are assembled to form the textual body
395 of the message, to be stored in the file associated with a "msg" class
396 item. Any parts of other types are each stored in separate files and
397 given "file" class items that are linked to the "msg" item.
398 * In a multipart/alternative message or part, we look for a text/plain
399 subpart and ignore the other parts.
401 If the message is a response to a previous message, and contains quoted
402 sections, then these will be stripped out of the message if the
403 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
405 Message summary
406 ~~~~~~~~~~~~~~~
408 The "summary" property on message items is taken from the first non-quoting
409 section in the message body. The message body is divided into sections by blank
410 lines. Sections where the second and all subsequent lines begin with a ">" or
411 "|" character are considered "quoting sections". The first line of the first
412 non-quoting section becomes the summary of the message.
415 Address handling
416 ----------------
418 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
419 message are
420 looked up among the tracker users, and the corresponding users are placed
421 in the
422 "recipients" property on the new "msg" item. The address in the ``From:`` header
423 similarly determines the "author" property of the new "msg" item. The default
424 handling for addresses that don't have corresponding users is to create new
425 users with no passwords and a username equal to the address.
427 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
428 the message may be added to the `nosy list`_ depending on:
430 ``ADD_AUTHOR_TO_NOSY``
431 Does the author of a message get placed on the nosy list automatically?
432 If 'new' is used, then the author will only be added when a message
433 creates a new issue. If 'yes', then the author will be added on followups
434 too. If 'no', they're never added to the nosy.
436 ``ADD_RECIPIENTS_TO_NOSY``
437 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
438 If 'new' is used, then the recipients will only be added when a message
439 creates a new issue. If 'yes', then the recipients will be added on
440 followups too. If 'no', they're never added to the nosy.
443 Nosy List
444 ~~~~~~~~~
446 Roundup watches for additions to the "messages" property of items.
448 When a new message is added, it is sent to all the users
449 on the "nosy" list for the item that are not already on the "recipients" list
450 of the message. Those users are then appended to the "recipients" property on
451 the message, so multiple copies of a message are never sent to the same user.
452 The journal recorded by the hyperdatabase on the "recipients" property then
453 provides a log of when the message was sent to whom.
455 If the author of the message is also in the nosy list for the item that the
456 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
457 to determine if they get a nosy list copy of the message too.
460 Mail gateway script command line
461 --------------------------------
463 The roundup mail gateway may be called in one of three ways:
465 . with an instance home as the only argument,
466 . with both an instance home and a mail spool file, or
467 . with both an instance home and a pop server account.
469 It also supports optional -C and -S arguments that allows you to set a
470 fields for a class created by the roundup-mailgw. The default class if
471 not specified is msg, but the other classes: issue, file, user can
472 also be used. The -S or --set options uses the same
473 property=value[;property=value] notation accepted by the command line
474 roundup command or the commands that can be given on the Subject line
475 of an email message.
477 It can let you set the type of the message on a per email address basis.
479 PIPE:
480 In the first case, the mail gateway reads a single message from the
481 standard input and submits the message to the roundup.mailgw module.
483 UNIX mailbox:
484 In the second case, the gateway reads all messages from the mail spool
485 file and submits each in turn to the roundup.mailgw module. The file is
486 emptied once all messages have been successfully handled. The file is
487 specified as::
489 mailbox /path/to/mailbox
491 POP:
492 In the third case, the gateway reads all messages from the POP server
493 specified and submits each in turn to the roundup.mailgw module. The
494 server is specified as::
496 pop username:password@server
498 The username and password may be omitted::
500 pop username@server
501 pop server
503 are both valid. The username and/or password will be prompted for if
504 not supplied on the command-line.
506 APOP:
507 Same as POP, but using Authenticated POP::
509 apop username:password@server
512 Command Line Tool
513 =================
515 The basic usage is::
517 Usage: roundup-admin [options] [<command> <arguments>]
519 Options:
520 -i instance home -- specify the issue tracker "home directory" to administer
521 -u -- the user[:password] to use for commands
522 -d -- print full designators not just class id numbers
523 -c -- when outputting lists of data, comma-separate them.
524 Same as '-S ","'.
525 -S <string> -- when outputting lists of data, string-separate them
526 -s -- when outputting lists of data, space-separate them.
527 Same as '-S " "'.
529 Only one of -s, -c or -S can be specified.
531 Help:
532 roundup-admin -h
533 roundup-admin help -- this help
534 roundup-admin help <command> -- command-specific help
535 roundup-admin help all -- all available help
537 Commands:
538 commit
539 create classname property=value ...
540 display designator[,designator]*
541 export [class[,class]] export_dir
542 find classname propname=value ...
543 get property designator[,designator]*
544 help topic
545 history designator
546 import import_dir
547 initialise [adminpw]
548 install [template [backend [admin password]]]
549 list classname [property]
550 pack period | date
551 reindex
552 retire designator[,designator]*
553 rollback
554 security [Role name]
555 set items property=value property=value ...
556 specification classname
557 table classname [property[,property]*]
558 Commands may be abbreviated as long as the abbreviation matches only one
559 command, e.g. l == li == lis == list.
562 All commands (except help) require a tracker specifier. This is just the
563 path to the roundup tracker you're working with. A roundup tracker is where
564 roundup keeps the database and configuration file that defines an issue
565 tracker. It may be thought of as the issue tracker's "home directory".
566 It may be specified in the environment variable ``TRACKER_HOME`` or on
567 the command line as "``-i tracker``".
569 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
570 Property values are represented as strings in command arguments and in the
571 printed results:
573 - Strings are, well, strings.
574 - Password values will display as their encoded value.
575 - Date values are printed in the full date format in the local time zone,
576 and accepted in the full format or any of the partial formats explained
577 below.::
579 Input of... Means...
580 "2000-04-17.03:45" 2000-04-17.08:45:00
581 "2000-04-17" 2000-04-17.00:00:00
582 "01-25" yyyy-01-25.00:00:00
583 "08-13.22:13" yyyy-08-14.03:13:00
584 "11-07.09:32:43" yyyy-11-07.14:32:43
585 "14:25" yyyy-mm-dd.19:25:00
586 "8:47:11" yyyy-mm-dd.13:47:11
587 "2003" 2003-01-01.00:00:00
588 "2003-04" 2003-04-01.00:00:00
589 "." "right now"
591 - Link values are printed as item designators. When given as an argument,
592 item designators and key strings are both accepted.
593 - Multilink values are printed as lists of item designators joined by
594 commas. When given as an argument, item designators and key strings are
595 both accepted; an empty string, a single item, or a list of items joined
596 by commas is accepted.
598 When multiple items are specified to the roundup get or roundup set
599 commands, the specified properties are retrieved or set on all the listed
600 items. When multiple results are returned by the roundup get or roundup
601 find commands, they are printed one per line (default) or joined by commas
602 (with the "``-c``" option).
604 Where the command changes data, a login name/password is required. The login may
605 be specified as either "``name``" or "``name:password``".
607 - ``ROUNDUP_LOGIN`` environment variable
608 - the "``-u``" command-line option
610 If either the name or password is not supplied, they are obtained from the
611 command-line.
613 Using with the shell
614 --------------------
616 With version 0.6.0 or newer of roundup which supports: multiple
617 designators to display and the -d, -S and -s flags.
619 To find all messages regarding chatting issues that
620 contain the word "spam", for example, you could execute the
621 following command from the directory where the database
622 dumps its files::
624 shell% for issue in `roundup-admin -ds find issue status=chatting`; do
625 > grep -l spam `roundup-admin -ds ' ' get messages $issue`
626 > done
627 msg23
628 msg49
629 msg50
630 msg61
631 shell%
633 Or, using the -dc option, this can be written as a single command::
635 shell% grep -l spam `roundup get messages \
636 \`roundup -dc find issue status=chatting\``
637 msg23
638 msg49
639 msg50
640 msg61
641 shell%
643 You can also display issue contents::
645 shell% roundup-admin display `roundup-admin -dc get messages \
646 issue3,issue1`
647 files: []
648 inreplyto: None
649 recipients: []
650 author: 1
651 date: 2003-02-16.21:23:03
652 messageid: None
653 summary: jkdskldjf
654 files: []
655 inreplyto: None
656 recipients: []
657 author: 1
658 date: 2003-02-15.01:59:11
659 messageid: None
660 summary: jlkfjadsf
662 or status::
664 shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
665 -dc -i /var/roundup/sysadmin get status issue3,issue1`
666 unread
667 deferred
669 or status on a single line::
671 shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
672 -dc -i /var/roundup/sysadmin get status issue3,issue1\``
673 unread deferred
675 which is the same as::
677 shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
678 -dc -i /var/roundup/sysadmin get status issue3,issue1`
679 unread deferred
681 Also the tautological::
683 shell% roundup-admin get name \
684 `roundup-admin -dc get status \`roundup-admin -dc find issue \
685 status=chatting\``
686 chatting
687 chatting
689 Remember the roundup commands that accept multiple designators accept
690 them ',' separated so using '-dc' is almost always required.
692 -----------------
694 Back to `Table of Contents`_
696 .. _`Table of Contents`: index.html
697 .. _`customisation documentation`: customizing.html