1 ==========
2 User Guide
3 ==========
5 :Version: $Revision: 1.24 $
7 .. contents::
9 Note: this document will refer to *issues* as the primary store of
10 information in the tracker. This is the default of the classic template,
11 but may vary in any given installation.
14 Your Tracker in a Nutshell
15 ==========================
17 Your tracker holds information about issues in bundles we call *items*.
18 An item may be an *issue* (a bug or feature request) or a *user*. The
19 issue-ness or user-ness is called the item's *class*. So, for bug
20 reports and features, the class is "issue", and for users the class is
21 "user".
23 Each item in the tracker has an id number that identifies it along with
24 its item class. To identify a particular issue or user, we combine the
25 class with the number to create a unique label, so that user 1 (who,
26 incidentally, is *always* the "admin" user) is referred to as "user1".
27 Issue number 315 is referred to as "issue315". We call that label the
28 item's *designator*.
30 Items in the database are never deleted, they're just "retired". You
31 can still refer to them by ID - hence removing an item won't break
32 references to the item. It's just that the item won't appear in any
33 listings.
36 Accessing the Tracker
37 ---------------------
39 You may access your tracker through one of three ways:
41 1. through the `web interface`_,
42 2. through the `e-mail gateway`_, or
43 3. using the `command line tool`_.
45 The last is usually only used by administrators. Most users will use the
46 web and email interfaces. All three are explained below.
49 Issue life cycles in Roundup
50 ----------------------------
52 New issues may be submitted via the web or email.
54 By default, the issue will have the status "unread". If another message
55 is received for the issue, its status will change to "chatting".
57 The "home" page for a tracker will generally display all issues which
58 are not "resolved.
60 If an issue is closed, and a new message is received then it'll be
61 reopened to the state of "chatting".
64 Entering values in your Tracker
65 -------------------------------
67 All interfaces to your tracker use the same format for entering values.
68 This means the web interface for entering a new issue, the web interface
69 for searching issues, the email interface and even the command-line
70 administration tool.
73 String and Numeric properties
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76 These fields just take a simple text value, like ``It's broken``.
79 Boolean properties
80 ~~~~~~~~~~~~~~~~~~
82 These fields take a value which indicates "yes"/"no", "true"/"false",
83 "1"/"0" or "on"/"off".
86 Constrained (link and multilink) properties
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89 Fields like "Assigned To" and "Topics" hold references to items in other
90 classes ("user" and "keyword" in those two cases.)
92 Sometimes, the selection is done through a menu, like in the "Assigned
93 To" field.
95 Where the input is not a simple menu selection, we use a comma-separated
96 list of values to indicated which values of "user" or "keyword" are
97 interesting. The values may be either numeric ids or the names of items.
98 The special value "-1" may be used to match items where the property is
99 not set. For example, the following searches on the issues:
101 ``assignedto=richard,george``
102 match issues which are assigned to richard or george.
103 ``assignedto=-1``
104 match issues that are not assigned to a user.
105 ``assignedto=2,3,40``
106 match issues that are assigned to users 2, 3 or 40.
107 ``topic=user interface``
108 match issues with the keyword "user interface" in their topic list
109 ``topic=web interface,email interface``
110 match issues with the keyword "web interface" or "email interface" in
111 their topic list
112 ``topic=-1``
113 match issues with no topics set
116 Date properties
117 ~~~~~~~~~~~~~~~
119 Some fields in the search page (e.g. "Activity" or "Creation date") hold
120 dates. A plain date entered as a search field will match that date
121 exactly in the database. We may also accept ranges of dates. You can
122 specify range of dates in one of two formats:
124 1. English syntax::
126 [From <value>][To <value>]
128 Keywords "From" and "To" are case insensitive. Keyword "From" is
129 optional.
131 2. "Geek" syntax::
133 [<value>];[<value>]
135 Either first or second ``<value>`` can be omitted in both syntaxes.
137 For example, if you enter string "from 9:00" to "Creation date" field,
138 roundup will find all issues, that were created today since 9 AM.
140 Searching of "-2m; -1m" on activity field gives you issues which were
141 active between period of time since 2 months up-till month ago.
143 Other possible examples (consider local time is Sat Mar 8 22:07:48
144 2003)::
146 >>> Range("from 2-12 to 4-2")
147 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
149 >>> Range("FROM 18:00 TO +2m")
150 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
152 >>> Range("12:00;")
153 <Range from 2003-03-08.12:00:00 to None>
155 >>> Range("tO +3d")
156 <Range from None to 2003-03-11.20:07:48>
158 >>> Range("2002-11-10; 2002-12-12")
159 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
161 >>> Range("; 20:00 +1d")
162 <Range from None to 2003-03-09.20:00:00>
164 >>> Range("2003")
165 <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
167 >>> Range("2003-04")
168 <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
171 Interval properties
172 ~~~~~~~~~~~~~~~~~~~
174 XXX explain...
176 When searching on interval properties use the same syntax as for dates.
179 Web Interface
180 =============
182 Note: this document contains screenshots of the default look and feel.
183 Your site may have a slightly (or very) different look, but the
184 functionality will be very similar, and the concepts still hold.
186 The web interface is broken up into the following parts:
188 1. `lists of items`_,
189 2. `display, edit or entry of an item`_, and
190 3. `searching page`_.
193 Lists of Items
194 --------------
196 The first thing you'll see when you log into Roundup will be a list of
197 open (ie. not resolved) issues. This list has been generated by a bunch
198 of controls `under the covers`_ but for now, you can see something like:
200 .. img: images/index_logged_out.png
202 The screen is divided up into three sections:
204 .. img: images/page_layout.png
206 you may either register or log in. Registration takes you to:
208 .. img: images/registration.png
210 Once you're logged in, the screen changes slightly to:
212 .. img: images/index_logged_in.png
214 Note that the sidebar menu has changed slightly, so you can now get to
215 your "My Details" page:
217 .. img: images/my_details.png
219 Note the new information on this page - the history.
222 Display, edit or entry of an item
223 ---------------------------------
225 Create a new issue with "create new" under the issue subheading. This
226 will take you to:
228 .. img: images/new_issue.png
230 The `nosy list`_ is explained below. Enter some information and click
231 "submit new entry" and you'll be rewarded with:
233 .. img: images/new_issue_created.png
235 or, if you don't enter all the required information (or some other error
236 occurs) you'll get something like:
238 .. img: images/new_issue_error.png
241 Searching Page
242 --------------
244 See `entering values in your tracker`_ for an explanation of what you
245 may type into the search form.
249 Under the covers
250 ~~~~~~~~~~~~~~~~
252 The searching page converts your selections into the following
253 arguments:
255 ========== =============================================================
256 Argument Description
257 ========== =============================================================
258 :sort sort by prop name, optionally preceeded with '-' to give
259 descending or nothing for ascending sorting.
260 :group group by prop name, optionally preceeded with '-' or to sort
261 in descending or nothing for ascending order.
262 :filter selects which props should be displayed in the filter
263 section. Default is all.
264 :columns selects the columns that should be displayed. Default is
265 all.
266 propname selects the values the item properties given by propname must
267 have (very basic search/filter).
268 ========== =============================================================
270 You may manually write URLS that contain these arguments, like so
271 (whitespace has been added for clarity)::
273 /issue?status=unread,in-progress,resolved&
274 topic=security,ui&
275 :group=priority&
276 :sort=-activity&
277 :filters=status,topic&
278 :columns=title,status,fixer
281 Access Controls
282 ---------------
284 User access is controlled through Permissions. These are are grouped
285 into Roles, and users have a comma-separated list of Roles assigned to
286 them.
288 Permissions divide access controls up into answering questions like:
290 - may the user edit issues ("Edit", "issue")
291 - is the user allowed to use the web interface ("Web Access")
292 - may the user edit other user's Roles through the web ("Web Roles")
294 Any number of new Permissions and Roles may be created as described in
295 the customisation documentation. Examples of new access controls are:
297 - only managers may sign off issues as complete
298 - don't give users who register through email web access
299 - let some users edit the details of all users
302 E-Mail Gateway
303 ==============
305 E-mail sent to Roundup is examined for several pieces of information:
307 1. `subject-line information`_ identifying the purpose of the e-mail
308 2. `sender identification`_ using the sender of the message
309 3. `e-mail message content`_ which is to be extracted
310 4. e-mail attachments which should be associated with the message
313 Subject-line information
314 ------------------------
316 The subject line of the incoming message is examined to find one of:
318 1. the item that the message is responding to,
319 2. the type of item the message should create, or
320 3. we default the item class and try some trickiness
322 If the subject line contains a prefix in ``[square brackets]`` then
323 we're looking at case 1 or 2 above. Note that any "re:" or "fwd:"
324 prefixes are stripped off the subject line before we start looking for
325 real information.
327 If an item designator (class name and id number, for example
328 ``issue123``) is found there, a new "msg" item is added to the
329 "messages" property for that item, and any new "file" items are added to
330 the "files" property for the item.
332 If just an item class name is found there, we attempt to create a new
333 item of that class with its "messages" property initialized to contain
334 the new "msg" item and its "files" property initialized to contain any
335 new "file" items.
337 The third case above - where no ``[information]`` is provided, the
338 tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what
339 class of item the message relates to. We try to match the subject line
340 to an existing item of the default class, and if there's a match, the
341 message is related to that matched item. If not, then a new item of the
342 default class is created.
345 Setting Properties
346 ~~~~~~~~~~~~~~~~~~
348 The e-mail interface also provides a simple way to set properties on
349 items. At the end of the subject line, propname=value pairs can be
350 specified in square brackets, using the same conventions as for the
351 roundup set shell command.
353 For example,
355 - setting the priority of an issue::
357 Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
359 - adding yourself to a nosy list::
361 Subject: Re: [issue2] we're out of widgets [nosy=+richard]
363 - setting the nosy list to just you and cliff::
365 Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
367 - removing yourself from a nosy list and setting the priority::
369 Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
371 In all cases, the message relates to issue 2. The ``Re:`` prefix is
372 stripped off.
375 Automatic Properties
376 ~~~~~~~~~~~~~~~~~~~~
378 **status of new issues**
379 When a new message is received that is not identified as being related
380 to an existing issue, it creates a new issue. The status of the new
381 issue is defaulted to "unread".
383 **reopening of resolved issues**
384 When a message is is received for a resolved issue, the issue status is
385 automatically reset to "chatting" to indicate new information has been
386 received.
389 Sender identification
390 ---------------------
392 If the sender of an email is unknown to Roundup (looking up both user
393 primary email addresses and their alternate addresses) then a new user
394 will be created. The new user will have their username set to the "user"
395 part of "user@domain" in their email address. Their password will be
396 completely randomised, and they'll have to visit the web interface to
397 have it changed. Note that some sites don't allow web access by users
398 who register via email like this.
401 E-Mail Message Content
402 ----------------------
404 Roundup only associates plain text (MIME type ``text/plain``) as
405 messages for items. Any other parts of a message are associated as
406 downloadable files. If no plain text part is found, the message is
407 rejected.
409 To do this, incoming messages are examined for multiple parts:
411 * In a multipart/mixed message or part, each subpart is extracted and
412 examined. The text/plain subparts are assembled to form the textual
413 body of the message, to be stored in the file associated with a "msg"
414 class item. Any parts of other types are each stored in separate files
415 and given "file" class items that are linked to the "msg" item.
416 * In a multipart/alternative message or part, we look for a text/plain
417 subpart and ignore the other parts.
419 If the message is a response to a previous message, and contains quoted
420 sections, then these will be stripped out of the message if the
421 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
423 Message summary
424 ~~~~~~~~~~~~~~~
426 The "summary" property on message items is taken from the first
427 non-quoting section in the message body. The message body is divided
428 into sections by blank lines. Sections where the second and all
429 subsequent lines begin with a ">" or "|" character are considered
430 "quoting sections". The first line of the first non-quoting section
431 becomes the summary of the message.
434 Address handling
435 ----------------
437 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
438 message are looked up among the tracker users, and the corresponding
439 users are placed in the "recipients" property on the new "msg" item. The
440 address in the ``From:`` header similarly determines the "author"
441 property of the new "msg" item. The default handling for addresses that
442 don't have corresponding users is to create new users with no passwords
443 and a username equal to the address.
445 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
446 the message may be added to the `nosy list`_ depending on:
448 ``ADD_AUTHOR_TO_NOSY``
449 Does the author of a message get placed on the nosy list automatically?
450 If 'new' is used, then the author will only be added when a message
451 creates a new issue. If 'yes', then the author will be added on
452 followups too. If 'no', they're never added to the nosy.
454 ``ADD_RECIPIENTS_TO_NOSY``
455 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
456 If 'new' is used, then the recipients will only be added when a message
457 creates a new issue. If 'yes', then the recipients will be added on
458 followups too. If 'no', they're never added to the nosy.
461 Nosy List
462 ~~~~~~~~~
464 Roundup watches for additions to the "messages" property of items.
466 When a new message is added, it is sent to all the users on the "nosy"
467 list for the item that are not already on the "recipients" list of the
468 message. Those users are then appended to the "recipients" property on
469 the message, so multiple copies of a message are never sent to the same
470 user. The journal recorded by the hyperdatabase on the "recipients"
471 property then provides a log of when the message was sent to whom.
473 If the author of the message is also in the nosy list for the item that
474 the message is attached to, then the config var ``MESSAGES_TO_AUTHOR``
475 is queried to determine if they get a nosy list copy of the message too.
478 Mail gateway script command line
479 --------------------------------
481 Usage::
483 roundup-mailgw [[-C class] -S field=value]* <instance home> [method]
485 The roundup mail gateway may be called in one of three ways:
487 - with an instance home as the only argument,
488 - with both an instance home and a mail spool file, or
489 - with both an instance home and a pop server account.
491 It also supports optional -C and -S arguments that allows you to set a
492 fields for a class created by the roundup-mailgw. The default class if
493 not specified is msg, but the other classes: issue, file, user can also
494 be used. The -S or --set options uses the same
495 property=value[;property=value] notation accepted by the command line
496 roundup command or the commands that can be given on the Subject line of
497 an email message.
499 It can let you set the type of the message on a per email address basis.
501 PIPE:
502 In the first case, the mail gateway reads a single message from the
503 standard input and submits the message to the roundup.mailgw module.
505 UNIX mailbox:
506 In the second case, the gateway reads all messages from the mail spool
507 file and submits each in turn to the roundup.mailgw module. The file is
508 emptied once all messages have been successfully handled. The file is
509 specified as::
511 mailbox /path/to/mailbox
513 POP:
514 In the third case, the gateway reads all messages from the POP server
515 specified and submits each in turn to the roundup.mailgw module. The
516 server is specified as::
518 pop username:password@server
520 The username and password may be omitted::
522 pop username@server
523 pop server
525 are both valid. The username and/or password will be prompted for if
526 not supplied on the command-line.
528 APOP:
529 Same as POP, but using Authenticated POP::
531 apop username:password@server
534 Command Line Tool
535 =================
537 The basic usage is::
539 Usage: roundup-admin [options] [<command> <arguments>]
541 Options:
542 -i instance home -- specify the issue tracker "home directory" to administer
543 -u -- the user[:password] to use for commands
544 -d -- print full designators not just class id numbers
545 -c -- when outputting lists of data, comma-separate them.
546 Same as '-S ","'.
547 -S <string> -- when outputting lists of data, string-separate them
548 -s -- when outputting lists of data, space-separate them.
549 Same as '-S " "'.
551 Only one of -s, -c or -S can be specified.
553 Help:
554 roundup-admin -h
555 roundup-admin help -- this help
556 roundup-admin help <command> -- command-specific help
557 roundup-admin help all -- all available help
559 Commands:
560 commit
561 create classname property=value ...
562 display designator[,designator]*
563 export [class[,class]] export_dir
564 find classname propname=value ...
565 get property designator[,designator]*
566 help topic
567 history designator
568 import import_dir
569 initialise [adminpw]
570 install [template [backend [admin password]]]
571 list classname [property]
572 pack period | date
573 reindex
574 retire designator[,designator]*
575 rollback
576 security [Role name]
577 set items property=value property=value ...
578 specification classname
579 table classname [property[,property]*]
580 Commands may be abbreviated as long as the abbreviation matches only one
581 command, e.g. l == li == lis == list.
584 All commands (except help) require a tracker specifier. This is just the
585 path to the roundup tracker you're working with. A roundup tracker is
586 where roundup keeps the database and configuration file that defines an
587 issue tracker. It may be thought of as the issue tracker's "home
588 directory". It may be specified in the environment variable
589 ``TRACKER_HOME`` or on the command line as "``-i tracker``".
591 A designator is a classname and an itemid concatenated, eg. bug1,
592 user10, ... Property values are represented as strings in command
593 arguments and in the printed results:
595 - Strings are, well, strings.
596 - Password values will display as their encoded value.
597 - Date values are printed in the full date format in the local time
598 zone, and accepted in the full format or any of the partial formats
599 explained below.::
601 Input of... Means...
602 "2000-04-17.03:45" 2000-04-17.08:45:00
603 "2000-04-17" 2000-04-17.00:00:00
604 "01-25" yyyy-01-25.00:00:00
605 "08-13.22:13" yyyy-08-14.03:13:00
606 "11-07.09:32:43" yyyy-11-07.14:32:43
607 "14:25" yyyy-mm-dd.19:25:00
608 "8:47:11" yyyy-mm-dd.13:47:11
609 "2003" 2003-01-01.00:00:00
610 "2003-04" 2003-04-01.00:00:00
611 "." "right now"
613 - Link values are printed as item designators. When given as an
614 argument, item designators and key strings are both accepted.
615 - Multilink values are printed as lists of item designators joined by
616 commas. When given as an argument, item designators and key strings
617 are both accepted; an empty string, a single item, or a list of items
618 joined by commas is accepted.
620 When multiple items are specified to the roundup get or roundup set
621 commands, the specified properties are retrieved or set on all the
622 listed items. When multiple results are returned by the roundup get or
623 roundup find commands, they are printed one per line (default) or joined
624 by commas (with the "``-c``" option).
626 Where the command changes data, a login name/password is required. The
627 login may be specified as either "``name``" or "``name:password``".
629 - ``ROUNDUP_LOGIN`` environment variable
630 - the "``-u``" command-line option
632 If either the name or password is not supplied, they are obtained from
633 the command-line.
636 Using with the shell
637 --------------------
639 With version 0.6.0 or newer of roundup which supports: multiple
640 designators to display and the -d, -S and -s flags.
642 To find all messages regarding chatting issues that contain the word
643 "spam", for example, you could execute the following command from the
644 directory where the database dumps its files::
646 shell% for issue in `roundup-admin -ds find issue status=chatting`; do
647 > grep -l spam `roundup-admin -ds ' ' get messages $issue`
648 > done
649 msg23
650 msg49
651 msg50
652 msg61
653 shell%
655 Or, using the -dc option, this can be written as a single command::
657 shell% grep -l spam `roundup get messages \
658 \`roundup -dc find issue status=chatting\``
659 msg23
660 msg49
661 msg50
662 msg61
663 shell%
665 You can also display issue contents::
667 shell% roundup-admin display `roundup-admin -dc get messages \
668 issue3,issue1`
669 files: []
670 inreplyto: None
671 recipients: []
672 author: 1
673 date: 2003-02-16.21:23:03
674 messageid: None
675 summary: jkdskldjf
676 files: []
677 inreplyto: None
678 recipients: []
679 author: 1
680 date: 2003-02-15.01:59:11
681 messageid: None
682 summary: jlkfjadsf
684 or status::
686 shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
687 -dc -i /var/roundup/sysadmin get status issue3,issue1`
688 unread
689 deferred
691 or status on a single line::
693 shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
694 -dc -i /var/roundup/sysadmin get status issue3,issue1\``
695 unread deferred
697 which is the same as::
699 shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
700 -dc -i /var/roundup/sysadmin get status issue3,issue1`
701 unread deferred
703 Also the tautological::
705 shell% roundup-admin get name \
706 `roundup-admin -dc get status \`roundup-admin -dc find issue \
707 status=chatting\``
708 chatting
709 chatting
711 Remember the roundup commands that accept multiple designators accept
712 them ',' separated so using '-dc' is almost always required.
714 -----------------
716 Back to `Table of Contents`_
718 .. _`Table of Contents`: index.html
719 .. _`customisation documentation`: customizing.html