doc/user_guide.txt

   1 ==========
   2 User Guide
   3 ==========
   4
   5 :Version: $Revision: 1.7 $
   6
   7 .. contents::
   8
   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.
  12
  13 Web Interface
  14 -------------
  15
  16 Index views may be modified by the following arguments:
  17
  18 ========== =============================================================
  19 Argument   Description
  20 ========== =============================================================
  21 :sort      sort by prop name, optionally preceeded with '-'
  22            to give descending or nothing for ascending sorting.
  23 :group     group by prop name, optionally preceeded with '-' or
  24            to sort in descending or nothing for ascending order.
  25 :filter    selects which props should be displayed in the filter
  26            section. Default is all.
  27 :columns   selects the columns that should be displayed.
  28            Default is all.
  29 propname   selects the values the item properties given by propname
  30            must have (very basic search/filter).
  31 ========== =============================================================
  32
  33 Searching
  34 ~~~~~~~~~
  35
  36 TODO: some information about how searching works
  37
  38
  39 Access Controls
  40 ~~~~~~~~~~~~~~~
  41
  42
  43 Managing Issues
  44 ~~~~~~~~~~~~~~~
  45
  46 TODO: some mention of how the various widgets work
  47
  48
  49 E-Mail Gateway
  50 --------------
  51
  52 E-mail sent to Roundup is examined for several pieces of information:
  53
  54 1. `subject-line information`_ identifying the purpose of the e-mail
  55 2. `e-mail message content`_ which is to be extracted
  56 3. e-mail attachments which should be associated with the message
  57
  58 Subject-line information
  59 ~~~~~~~~~~~~~~~~~~~~~~~~
  60
  61 The subject line of the incoming message is examined to find one of:
  62
  63 1. the item that the message is responding to,
  64 2. the type of item the message should create, or
  65 3. we default the item class and try some trickiness
  66
  67 If the subject line contains a prefix in ``[square brackets]`` then we're
  68 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
  69 stripped off the subject line before we start looking for real information.
  70
  71 If an item designator (class name and id number, for example ``issue123``)
  72 is found there, a new "msg" item is added to the "messages" property for
  73 that item, and any new "file" items are added to the "files" property for
  74 the item.
  75
  76 If just an item class name is found there, we attempt to create a new item of
  77 that class with its "messages" property initialized to contain the new "msg"
  78 item and its "files" property initialized to contain any new "file" items.
  79
  80 The third case above - where no ``[information]`` is provided, the tracker's
  81 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
  82 the message relates to. We try to match the subject line to an existing
  83 item of the default class, and if there's a match, the message is related to
  84 that matched item. If not, then a new item of the default class is created.
  85
  86 Setting Properties
  87 ::::::::::::::::::
  88
  89 The e-mail interface also provides a simple way to set properties on items. At
  90 the end of the subject line, propname=value pairs can be specified in square
  91 brackets, using the same conventions as for the roundup set shell command.
  92
  93 For example,
  94
  95 - setting the priority of an issue::
  96
  97    Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
  98
  99 - adding yourself to a nosy list::
 100
 101    Subject: Re: [issue2] we're out of widgets [nosy=+richard]
 102
 103 - setting the nosy list to just you::
 104
 105    Subject: Re: [issue2] we're out of widgets [nosy=richard]
 106
 107 - removing yourself from a nosy list::
 108
 109    Subject: Re: [issue2] we're out of widgets [nosy=-richard]
 110
 111 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
 112 off.
 113
 114
 115 E-Mail Message Content
 116 ~~~~~~~~~~~~~~~~~~~~~~
 117
 118 Roundup only associates plain text (MIME type ``text/plain``) as messages for
 119 items. Any other parts of a message are associated as downloadable files. If
 120 no plain text part is found, the message is rejected.
 121
 122 To do this, incoming messages are examined for multiple parts:
 123
 124 * In a multipart/mixed message or part, each subpart is extracted and
 125   examined. The text/plain subparts are assembled to form the textual body
 126   of the message, to be stored in the file associated with a "msg" class
 127   item. Any parts of other types are each stored in separate files and
 128   given "file" class items that are linked to the "msg" item.
 129 * In a multipart/alternative message or part, we look for a text/plain
 130   subpart and ignore the other parts.
 131
 132 If the message is a response to a previous message, and contains quoted
 133 sections, then these will be stripped out of the message if the
 134 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
 135
 136 Message summary
 137 :::::::::::::::
 138
 139 The "summary" property on message items is taken from the first non-quoting
 140 section in the message body. The message body is divided into sections by blank
 141 lines. Sections where the second and all subsequent lines begin with a ">" or
 142 "|" character are considered "quoting sections". The first line of the first
 143 non-quoting section becomes the summary of the message.
 144
 145
 146 Address handling
 147 ~~~~~~~~~~~~~~~~
 148
 149 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
 150 message are
 151 looked up among the tracker users, and the corresponding users are placed
 152 in the
 153 "recipients" property on the new "msg" item. The address in the ``From:`` header
 154 similarly determines the "author" property of the new "msg" item. The default
 155 handling for addresses that don't have corresponding users is to create new
 156 users with no passwords and a username equal to the address.
 157
 158 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
 159 the message may be added to the `nosy list`_ depending on:
 160
 161 ``ADD_AUTHOR_TO_NOSY``
 162  Does the author of a message get placed on the nosy list automatically?
 163  If 'new' is used, then the author will only be added when a message
 164  creates a new issue. If 'yes', then the author will be added on followups
 165  too. If 'no', they're never added to the nosy.
 166
 167 ``ADD_RECIPIENTS_TO_NOSY``
 168  Do the recipients (To:, Cc:) of a message get placed on the nosy list?
 169  If 'new' is used, then the recipients will only be added when a message
 170  creates a new issue. If 'yes', then the recipients will be added on
 171  followups too. If 'no', they're never added to the nosy.
 172
 173
 174 Nosy List
 175 :::::::::
 176
 177 The nosy list watches for additions to the "messages" property of items.
 178 When a new message is added, it is sent to all the users
 179 on the "nosy" list for the item that are not already on the "recipients" list
 180 of the message. Those users are then appended to the "recipients" property on
 181 the message, so multiple copies of a message are never sent to the same user.
 182 The journal recorded by the hyperdatabase on the "recipients" property then
 183 provides a log of when the message was sent to whom.
 184
 185 If the author of the message is also in the nosy list for the item that the
 186 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
 187 to determine if they get a nosy list copy of the message too.
 188
 189
 190 Command Line Tool
 191 -----------------
 192
 193 The basic usage is::
 194
 195  Help:
 196  roundup-admin -h
 197   roundup-admin help                       -- this help
 198   roundup-admin help <command>             -- command-specific help
 199   roundup-admin help all                   -- all available help
 200
 201  Options:
 202   -i instance home  -- specify the issue tracker "home directory" to administer
 203   -u                -- the user[:password] to use for commands
 204   -c                -- when outputting lists of data, just comma-separate them
 205
 206  Commands:
 207   commit
 208   create classname property=value ...
 209   display designator
 210   export [class[,class]] export_dir
 211   find classname propname=value ...
 212   get property designator[,designator]*
 213   help topic
 214   history designator
 215   import import_dir
 216   initialise [adminpw]
 217   install [template [backend [admin password]]]
 218   list classname [property]
 219   pack period | date
 220   reindex
 221   retire designator[,designator]*
 222   rollback
 223   security [Role name]
 224   set designator[,designator]* propname=value ...
 225   specification classname
 226   table classname [property[,property]*]
 227
 228 Commands may be abbreviated as long as the abbreviation matches only one
 229 command, e.g. l == li == lis == list.
 230
 231 All commands (except help) require a tracker specifier. This is just the
 232 path to the roundup tracker you're working with. A roundup tracker is where
 233 roundup keeps the database and configuration file that defines an issue
 234 tracker. It may be thought of as the issue tracker's "home directory".
 235 It may be specified in the environment variable ``TRACKER_HOME`` or on
 236 the command line as "``-i tracker``".
 237
 238 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
 239 Property values are represented as strings in command arguments and in the printed
 240 results:
 241
 242 - Strings are, well, strings.
 243 - Password values will display as their encoded value.
 244 - Date values are printed in the full date format in the local time zone,
 245   and accepted in the full format or any of the partial formats explained
 246   below.::
 247
 248     Input of...        Means...
 249     "2000-04-17.03:45" 2000-04-17.08:45:00
 250     "2000-04-17"       2000-04-17.00:00:00
 251     "01-25"            yyyy-01-25.00:00:00
 252     "08-13.22:13"      yyyy-08-14.03:13:00
 253     "11-07.09:32:43"   yyyy-11-07.14:32:43
 254     "14:25"            yyyy-mm-dd.19:25:00
 255     "8:47:11"          yyyy-mm-dd.13:47:11
 256     "."                "right now"
 257
 258 - Link values are printed as item designators. When given as an argument,
 259   item designators and key strings are both accepted.
 260 - Multilink values are printed as lists of item designators joined by
 261   commas. When given as an argument, item designators and key strings are
 262   both accepted; an empty string, a single item, or a list of items joined
 263   by commas is accepted.
 264
 265 When multiple items are specified to the roundup get or roundup set
 266 commands, the specified properties are retrieved or set on all the listed
 267 items.  When multiple results are returned by the roundup get or roundup
 268 find commands, they are printed one per line (default) or joined by commas
 269 (with the "``-c``" option).
 270
 271 Where the command changes data, a login name/password is required. The login may
 272 be specified as either "``name``" or "``name:password``".
 273
 274 - ``ROUNDUP_LOGIN`` environment variable
 275 - the "``-u``" command-line option
 276
 277 If either the name or password is not supplied, they are obtained from the
 278 command-line.
 279
 280
 281
 282 -----------------
 283
 284 Back to `Table of Contents`_
 285
 286 .. _`Table of Contents`: index.html
 287