doc/user_guide.txt

   1 ==========
   2 User Guide
   3 ==========
   4
   5 :Version: $Revision: 1.5 $
   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 | :sort     | sort by prop name, optionally preceeded with '-'             |
  20 |           | to give descending or nothing for ascending sorting.         |
  21 +-----------+--------------------------------------------------------------+
  22 | :group    | group by prop name, optionally preceeded with '-' or         |
  23 |           | to sort in descending or nothing for ascending order.        |
  24 +-----------+--------------------------------------------------------------+
  25 | :filter   | selects which props should be displayed in the filter        |
  26 |           | section. Default is all.                                     |
  27 +-----------+--------------------------------------------------------------+
  28 | :columns  | selects the columns that should be displayed.                |
  29 |           | Default is all.                                              |
  30 +-----------+--------------------------------------------------------------+
  31 | propname  | selects the values the node properties given by propname     |
  32 |           | must have (very basic search/filter).                        |
  33 +-----------+--------------------------------------------------------------+
  34
  35 Searching
  36 ~~~~~~~~~
  37
  38 TODO: some information about how searching works
  39
  40
  41 Access Controls
  42 ~~~~~~~~~~~~~~~
  43
  44
  45 Managing Issues
  46 ~~~~~~~~~~~~~~~
  47
  48 TODO: some mention of how the various widgets work
  49
  50
  51 E-Mail Gateway
  52 --------------
  53
  54 E-mail sent to Roundup is examined for several pieces of information:
  55
  56 1. `subject-line information`_ identifying the purpose of the e-mail
  57 2. `e-mail message content`_ which is to be extracted
  58 3. e-mail attachments which should be associated with the message
  59
  60 Subject-line information
  61 ~~~~~~~~~~~~~~~~~~~~~~~~
  62
  63 The subject line of the incoming message is examined to find one of:
  64
  65 1. the item that the message is responding to,
  66 2. the type of item the message should create, or
  67 3. we default the item class and try some trickiness
  68
  69 If the subject line contains a prefix in ``[square brackets]`` then we're
  70 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
  71 stripped off the subject line before we start looking for real information.
  72
  73 If an item designator (class name and id number, for example ``issue123``)
  74 is found there, a new "msg" node is added to the "messages" property for
  75 that item, and any new "file" nodes are added to the "files" property for
  76 the item.
  77
  78 If just an item class name is found there, we attempt to create a new item of
  79 that class with its "messages" property initialized to contain the new "msg"
  80 node and its "files" property initialized to contain any new "file" nodes.
  81
  82 The third case above - where no ``[information]`` is provided, the tracker's
  83 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
  84 the message relates to. We try to match the subject line to an existing
  85 item of the default class, and if there's a match, the message is related to
  86 that matched item. If not, then a new item of the default class is created.
  87
  88 Setting Properties
  89 ::::::::::::::::::
  90
  91 The e-mail interface also provides a simple way to set properties on items. At
  92 the end of the subject line, propname=value pairs can be specified in square
  93 brackets, using the same conventions as for the roundup set shell command.
  94
  95 For example,
  96
  97 - setting the priority of an issue::
  98
  99    Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
 100
 101 - adding yourself to a nosy list::
 102
 103    Subject: Re: [issue2] we're out of widgets [nosy=+richard]
 104
 105 - setting the nosy list to just you::
 106
 107    Subject: Re: [issue2] we're out of widgets [nosy=richard]
 108
 109 - removing yourself from a nosy list::
 110
 111    Subject: Re: [issue2] we're out of widgets [nosy=-richard]
 112
 113 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
 114 off.
 115
 116
 117 E-Mail Message Content
 118 ~~~~~~~~~~~~~~~~~~~~~~
 119
 120 Roundup only associates plain text (MIME type ``text/plain``) as messages for
 121 items. Any other parts of a message are associated as downloadable files. If
 122 no plain text part is found, the message is rejected.
 123
 124 To do this, incoming messages are examined for multiple parts:
 125
 126 * In a multipart/mixed message or part, each subpart is extracted and
 127   examined. The text/plain subparts are assembled to form the textual body
 128   of the message, to be stored in the file associated with a "msg" class
 129   node. Any parts of other types are each stored in separate files and
 130   given "file" class nodes that are linked to the "msg" node.
 131 * In a multipart/alternative message or part, we look for a text/plain
 132   subpart and ignore the other parts.
 133
 134 If the message is a response to a previous message, and contains quoted
 135 sections, then these will be stripped out of the message if the
 136 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
 137
 138 Message summary
 139 :::::::::::::::
 140
 141 The "summary" property on message nodes is taken from the first non-quoting
 142 section in the message body. The message body is divided into sections by blank
 143 lines. Sections where the second and all subsequent lines begin with a ">" or
 144 "|" character are considered "quoting sections". The first line of the first
 145 non-quoting section becomes the summary of the message.
 146
 147
 148 Address handling
 149 ~~~~~~~~~~~~~~~~
 150
 151 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
 152 message are
 153 looked up among the tracker users, and the corresponding users are placed
 154 in the
 155 "recipients" property on the new "msg" node. The address in the ``From:`` header
 156 similarly determines the "author" property of the new "msg" node. The default
 157 handling for addresses that don't have corresponding users is to create new
 158 users with no passwords and a username equal to the address.
 159
 160 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
 161 the message may be added to the `nosy list`_ depending on:
 162
 163 ``ADD_AUTHOR_TO_NOSY``
 164  Does the author of a message get placed on the nosy list automatically?
 165  If 'new' is used, then the author will only be added when a message
 166  creates a new issue. If 'yes', then the author will be added on followups
 167  too. If 'no', they're never added to the nosy.
 168
 169 ``ADD_RECIPIENTS_TO_NOSY``
 170  Do the recipients (To:, Cc:) of a message get placed on the nosy list?
 171  If 'new' is used, then the recipients will only be added when a message
 172  creates a new issue. If 'yes', then the recipients will be added on
 173  followups too. If 'no', they're never added to the nosy.
 174
 175
 176 Nosy List
 177 :::::::::
 178
 179 The nosy list watches for additions to the "messages" property of items.
 180 When a new message is added, it is sent to all the users
 181 on the "nosy" list for the item that are not already on the "recipients" list
 182 of the message. Those users are then appended to the "recipients" property on
 183 the message, so multiple copies of a message are never sent to the same user.
 184 The journal recorded by the hyperdatabase on the "recipients" property then
 185 provides a log of when the message was sent to whom.
 186
 187 If the author of the message is also in the nosy list for the item that the
 188 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
 189 to determine if they get a nosy list copy of the message too.
 190
 191
 192 Command Line Tool
 193 -----------------
 194
 195 Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
 196
 197 Options:
 198
 199 -i          instance home specify the issue tracker "home directory" to administer
 200 -u          the ``user[:password]`` to use for commands
 201 -c          when outputting lists of data, comma-separate them
 202
 203 +-----------------------------------------------------------------------------+
 204 | Command Help                                                                |
 205 +=============+===============================================================+
 206 |commit       |Usage: commit                                                  |
 207 |             |The changes made during an interactive session are not         |
 208 |             |automatically written to the database - they must be committed |
 209 |             |using this command.                                            |
 210 |             |                                                               |
 211 |             |One-off commands on the command-line are automatically         |
 212 |             |committed if they are successful.                              |
 213 +-------------+---------------------------------------------------------------+
 214 |create       |Usage: create classname property=value ...                     |
 215 |             |This creates a new entry of the given class using the property |
 216 |             |name=value arguments provided on the command line after the    |
 217 |             |"create" command.                                              |
 218 +-------------+---------------------------------------------------------------+
 219 |display      |Usage: display designator                                      |
 220 |             |This lists the properties and their associated values for the  |
 221 |             |given node.                                                    |
 222 +-------------+---------------------------------------------------------------+
 223 |export       |Usage: export class[,class] destination dir                    |
 224 |             |This action exports the current data from the database into    |
 225 |             |tab-separated-value files that are placed in the nominated     |
 226 |             |destination                                                    |
 227 |             |directory. The journals are not exported.                      |
 228 +-------------+---------------------------------------------------------------+
 229 |find         |Usage: find classname propname=value ...                       |
 230 |             |Find the nodes of the given class with a given link property   |
 231 |             |value. The                                                     |
 232 |             |value may be either the nodeid of the linked node, or its key  |
 233 |             |value.                                                         |
 234 +-------------+---------------------------------------------------------------+
 235 |get          |Usage: get property designator[,designator]*                   |
 236 |             |Retrieves the property value of the nodes specified by the     |
 237 |             |designators.                                                   |
 238 +-------------+---------------------------------------------------------------+
 239 |help         |Usage: help topic                                              |
 240 |             |commands  -- list commands                                     |
 241 |             |x -- help specific to a command                                |
 242 |             |initopts  -- init command options                              |
 243 |             |all       -- all available help                                |
 244 +-------------+---------------------------------------------------------------+
 245 |history      |Usage: history designator                                      |
 246 |             |Lists the journal entries for the node identified by the       |
 247 |             |designator.                                                    |
 248 +-------------+---------------------------------------------------------------+
 249 |import       |Usage: import class file                                       |
 250 |             |The file must define the same properties as the class          |
 251 |             |(including having                                              |
 252 |             |a "header" line with those property names.) The new nodes are  |
 253 |             |added to                                                       |
 254 |             |the existing database - if you want to create a new database   |
 255 |             |using the                                                      |
 256 |             |imported data, then create a new database (or, tediously,      |
 257 |             |retire all                                                     |
 258 |             |the old data.)                                                 |
 259 +-------------+---------------------------------------------------------------+
 260 |initialise   |Usage: initialise [template [backend [admin password]]]        |
 261 |             |The command will prompt for the instance home directory (if not|
 262 |             |supplied                                                       |
 263 |             |through INSTANCE HOME or the -i option. The template, backend  |
 264 |             |and admin                                                      |
 265 |             |password may be specified on the command-line as arguments, in |
 266 |             |that                                                           |
 267 |             |order.                                                         |
 268 |             |                                                               |
 269 |             |See also initopts help.                                        |
 270 +-------------+---------------------------------------------------------------+
 271 |list         |Usage: list classname [property]                               |
 272 |             |Lists all instances of the given class. If the property is not |
 273 |             |specified, the  "label" property is used. The label property is|
 274 |             |tried                                                          |
 275 |             |in order: the key, "name", "title" and then the first property,|
 276 |             |alphabetically.                                                |
 277 +-------------+---------------------------------------------------------------+
 278 |retire       |Usage: retire designator[,designator]*                         |
 279 |             |This action indicates that a particular node is not to be      |
 280 |             |retrieved by                                                   |
 281 |             |the list or find commands, and its key value may be re-used.   |
 282 +-------------+---------------------------------------------------------------+
 283 |rollback     |Usage: rollback                                                |
 284 |             |The changes made during an interactive session are not         |
 285 |             |automatically written to the database - they must be committed |
 286 |             |manually. This command undoes all those changes, so a commit   |
 287 |             |immediately after would make no changes to the database.       |
 288 +-------------+---------------------------------------------------------------+
 289 |set          |Usage: set designator[,designator]* propname=value ...         |
 290 |             |Sets the property to the value for all designators given.      |
 291 +-------------+---------------------------------------------------------------+
 292 |specification|Usage: specification classname                                 |
 293 |             |This lists the properties for a given class.                   |
 294 +-------------+---------------------------------------------------------------+
 295 |table        |Usage: table classname [property[,property]*]                  |
 296 |             |Lists all instances of the given class. If the properties are  |
 297 |             |not                                                            |
 298 |             |specified, all properties are displayed. By default, the column|
 299 |             |widths                                                         |
 300 |             |are the width of the property names. The width may be          |
 301 |             |explicitly defined                                             |
 302 |             |by defining the property as "name:width". For example::        |
 303 |             |                                                               |
 304 |             |  roundup> table priority id,name:10                           |
 305 |             |  Id Name                                                      |
 306 |             |  1  fatal-bug                                                 |
 307 |             |  2  bug                                                       |
 308 |             |  3  usability                                                 |
 309 |             |  4  feature                                                   |
 310 +-------------+---------------------------------------------------------------+
 311
 312
 313 All commands (except help) require an instance specifier. This is just the path to
 314 the roundup instance you're working with. A roundup instance is where roundup
 315 keeps the database and configuration file that defines an issue tracker. It may be
 316 thought of as the issue tracker's "home directory". It may be specified in the
 317 environment variable ``ROUNDUP_INSTANCE`` or on the command line as "``-i instance``".
 318
 319 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
 320 Property values are represented as strings in command arguments and in the printed
 321 results:
 322
 323 - Strings are, well, strings.
 324 - Password values will display as their encoded value.
 325 - Date values are printed in the full date format in the local time zone,
 326   and accepted in the full format or any of the partial formats explained
 327   below.::
 328
 329     Input of...        Means...
 330     "2000-04-17.03:45" 2000-04-17.08:45:00
 331     "2000-04-17"       2000-04-17.00:00:00
 332     "01-25"            yyyy-01-25.00:00:00
 333     "08-13.22:13"      yyyy-08-14.03:13:00
 334     "11-07.09:32:43"   yyyy-11-07.14:32:43
 335     "14:25"            yyyy-mm-dd.19:25:00
 336     "8:47:11"          yyyy-mm-dd.13:47:11
 337     "."                "right now"
 338
 339 - Link values are printed as node designators. When given as an argument,
 340   node designators and key strings are both accepted.
 341 - Multilink values are printed as lists of node designators joined by
 342   commas. When given as an argument, node designators and key strings are
 343   both accepted; an empty string, a single node, or a list of nodes joined
 344   by commas is accepted.
 345
 346 When multiple nodes are specified to the roundup get or roundup set commands, the
 347 specified properties are retrieved or set on all the listed nodes.  When multiple
 348 results are returned by the roundup get or roundup find commands, they are printed
 349 one per line (default) or joined by commas (with the "``-c``" option).
 350
 351 Where the command changes data, a login name/password is required. The login may
 352 be specified as either "``name``" or "``name:password``".
 353
 354 - ``ROUNDUP_LOGIN`` environment variable
 355 - the "``-u``" command-line option
 356
 357 If either the name or password is not supplied, they are obtained from the
 358 command-line.
 359
 360
 361
 362 -----------------
 363
 364 Back to `Table of Contents`_
 365
 366 .. _`Table of Contents`: index.html
 367