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