Mercurial > p > roundup > code

comparison doc/user_guide.txt @ 881:85cc6e6a94b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
better mailgw user docs
author Richard Jones <richard@users.sourceforge.net>
date Thu, 18 Jul 2002 11:26:56 +0000
parents 938edfdeac6e
children 43ab730ee194
comparison
equal deleted inserted replaced
880:de3da99a7c02 881:85cc6e6a94b8
1 ========== 1 ==========
2 User Guide 2 User Guide
3 ========== 3 ==========
4 4
5 :Version: $Revision: 1.4 $ 5 :Version: $Revision: 1.5 $
6 6
7 .. contents:: 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
8 191
9 Command Line Tool 192 Command Line Tool
10 ----------------- 193 -----------------
11 194
12 Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>`` 195 Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
173 356
174 If either the name or password is not supplied, they are obtained from the 357 If either the name or password is not supplied, they are obtained from the
175 command-line. 358 command-line.
176 359
177 360
178 Web Interface
179 -------------
180
181 Index views may be modified by the following arguments:
182
183 +-----------+--------------------------------------------------------------+
184 | :sort | sort by prop name, optionally preceeded with '-' |
185 | | to give descending or nothing for ascending sorting. |
186 +-----------+--------------------------------------------------------------+
187 | :group | group by prop name, optionally preceeded with '-' or |
188 | | to sort in descending or nothing for ascending order. |
189 +-----------+--------------------------------------------------------------+
190 | :filter | selects which props should be displayed in the filter |
191 | | section. Default is all. |
192 +-----------+--------------------------------------------------------------+
193 | :columns | selects the columns that should be displayed. |
194 | | Default is all. |
195 +-----------+--------------------------------------------------------------+
196 | propname | selects the values the node properties given by propname |
197 | | must have (very basic search/filter). |
198 +-----------+--------------------------------------------------------------+
199
200 Not sure what to put in here...
201
202 E-Mail Gateway
203 --------------
204
205 Performing Actions
206 ~~~~~~~~~~~~~~~~~~
207
208 The subject line of the incoming message is examined to determine whether the
209 message is an attempt to create a new item or to discuss an existing item. A
210 designator enclosed in square brackets is sought as the first thing on the
211 subject line (after skipping any "Fwd:" or "Re:" prefixes).
212 If an item designator (class name and id number) is found there, the newly
213 created "msg" node is added to the "messages" property for that item, and any
214 new "file" nodes are added to the "files" property for the item.
215 If just an item class name is found there, we attempt to create a new item of
216 that class with its "messages" property initialized to contain the new "msg"
217 node and its "files" property initialized to contain any new "file" nodes.
218
219 Setting Properties
220 ~~~~~~~~~~~~~~~~~~
221
222 The e-mail interface also provides a simple way to set properties on items. At
223 the end of the subject line, propname=value pairs can be specified in square
224 brackets, using the same conventions as for the roundup set shell command.
225
226 For example,
227
228 - setting the priority of an issue::
229
230 Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
231
232 - adding yourself to a nosy list (both of these are equivalent)::
233
234 Subject: Re: [issue2] we're out of widgets [nosy=+richard]
235 Subject: Re: [issue2] we're out of widgets [nosy=richard]
236
237 - removing yourself from a nosy list::
238
239 Subject: Re: [issue2] we're out of widgets [nosy=-richard]
240
241
242 Message content
243 ~~~~~~~~~~~~~~~
244
245 Incoming messages are examined for multiple parts:
246
247 * In a multipart/mixed message or part, each subpart is extracted and
248 examined. The text/plain subparts are assembled to form the textual body
249 of the message, to be stored in the file associated with a "msg" class
250 node. Any parts of other types are each stored in separate files and
251 given "file" class nodes that are linked to the "msg" node.
252 * In a multipart/alternative message or part, we look for a text/plain
253 subpart and ignore the other parts.
254
255 Message summary
256 :::::::::::::::
257
258 The "summary" property on message nodes is taken from the first non-quoting
259 section in the message body. The message body is divided into sections by blank
260 lines. Sections where the second and all subsequent lines begin with a ">" or
261 "|" character are considered "quoting sections". The first line of the first
262 non-quoting section becomes the summary of the message.
263
264 Address handling
265 ~~~~~~~~~~~~~~~~
266
267 All of the addresses in the To: and Cc: headers of the incoming message are
268 looked up among the user nodes, and the corresponding users are placed in the
269 "recipients" property on the new "msg" node. The address in the From: header
270 similarly determines the "author" property of the new "msg" node. The default
271 handling for addresses that don't have corresponding users is to create new
272 users with no passwords and a username equal to the address. (The web interface
273 does not permit logins for users with no passwords.) If we prefer to reject
274 mail from outside sources, we can simply register an auditor on the "user"
275 class that prevents the creation of user nodes with no passwords.
276
277 Triggers
278 ~~~~~~~~
279
280 Both cases may trigger detectors (in the first case we are calling the set()
281 method to add the message to the item's spool; in the second case we are
282 calling the create() method to create a new node). If an auditor raises an
283 exception, the original message is bounced back to the sender with the
284
285 Nosy Lists
286 ::::::::::
287
288 A standard detector is provided that watches for additions to the "messages"
289 property. When a new message is added, the detector sends it to all the users
290 on the "nosy" list for the item that are not already on the "recipients" list
291 of the message. Those users are then appended to the "recipients" property on
292 the message, so multiple copies of a message are never sent to the same user.
293 The journal recorded by the hyperdatabase on the "recipients" property then
294 provides a log of when the message was sent to whom.
295
296 361
297 ----------------- 362 -----------------
298 363
299 Back to `Table of Contents`_ 364 Back to `Table of Contents`_
300 365
Roundup Issue Tracker: http://roundup-tracker.org/