Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / whatsnew-0.7.txt
1 =========================
2 What's New in Roundup 0.7
3 =========================
4
5 For those completely new to Roundup, you might want to look over the very
6 terse features__ page.
7
8 __ features.html
9
10 .. contents::
11
12 Instant-Gratification script even more gratifying
13 =================================================
14
15 The immensely popular ``python demo.py`` instant-gratification script has
16 been extended to allow you to choose the backend to use with the demo. To
17 select the "sqlite" backend (assuming it is available) you use::
18
19   python demo.py sqlite nuke
20
21 This will nuke any existing demo and reinitialise it with the sqlite
22 backend. Remember folks, if you want to restart the demo at a later point,
23 you just need to type::
24
25   python demo.py
26
27 without the "sqlite nuke" part, or you'll clear out the demo again. The
28 backend names are:
29
30   anydbm bsddb bsddb3 sqlite metakit mysql postgresql
31
32 You will need support modules installed for all except the first two. If
33 you're not sure whether you have support, run::
34
35   python run_tests.py
36
37 and if you see a line saying "Including XXXX tests" where XXXX is the
38 backend you wish to try, then you're on your way. The mysql and postgresql
39 require their test environments to be set up. Read their respective
40 documents in the "doc" directory to do that.
41
42
43 Web Interface
44 =============
45
46 Saving and sharing of user queries
47 ----------------------------------
48
49 Due to popular demand, the user query saving mechanisms have been
50 overhauled.
51
52 As before, you may save queries in the tracker by giving the query a
53 name. Each user may only have one query with a given name - if a
54 subsequent search is performed with the same query name supplied, then
55 it will edit the existing query of the same name.
56
57 Queries may be marked as "private". These queries are only visible to the
58 user that created them. If they're not marked "private" then all other
59 users may include the query in their list of "Your Queries". Marking it as
60 private at a later date does not affect users already using the query, nor
61 does deleting the query.
62
63 If a user subsequently creates or edits a public query, a new personal
64 version of that query is made, with the same editing rules as described
65 above.
66
67 You *are not required* to make these changes in your tracker. You only
68 need to make them if you wish to use the new query editing features. It's
69 highly recommended, as the effort is minimal.
70
71 1. You will need to edit your tracker's ``dbinit.py`` to change the way
72    queries are stored. Change the lines::
73
74       query = Class(db, "query",
75                       klass=String(),     name=String(),
76                       url=String())
77       query.setkey("name")
78
79    to::
80
81       query = Class(db, "query",
82                       klass=String(),     name=String(),
83                       url=String(),       private_for=Link('user'))
84
85    That is, add the "private_for" property, and remove the line that says
86    ``query.setkey("name")``.
87
88 2. You will also need to copy the ``query.edit.html`` template page from the
89    ``templates/classic/html/`` directory of the source to your tracker's
90    ``html`` directory.
91
92 3. Once you've done that, edit the tracker's ``page.html`` template to
93    change::
94
95     <td rowspan="2" valign="top" class="sidebar">
96      <p class="classblock" tal:condition="request/user/queries">
97       <b>Your Queries</b><br>
98       <tal:block tal:repeat="qs request/user/queries">
99
100    to::
101
102     <td rowspan="2" valign="top" class="sidebar">
103      <p class="classblock">
104       <b>Your Queries</b> (<a href="query?@template=edit">edit</a>)<br>
105       <tal:block tal:repeat="qs request/user/queries">
106
107    That is, you're removing the ``tal:condition`` and adding a link to the
108    new edit page.
109
110 4. You might also wish to remove the redundant query editing section from the
111    ``user.item.html`` page.
112
113 ZRoundup reinstated
114 -------------------
115
116 The Zope interface, ZRoundup, lives again!
117
118 See the `upgrading documentation`__ if you wish to use it.
119
120 __ upgrading.html#zroundup-changes
121
122
123 Simple support for collision detection
124 --------------------------------------
125
126 Item edit pages that use the ``context/submit`` function to generate their
127 submit buttons now automatically include a datestamp in the form. This
128 datestamp is compared to the "activity" property of the item when the form
129 is submitted. If the "actvity" property is younger than the datestamp in
130 the form submission, then someone else has edited the item, and a page
131 indicating this is displayed to the user.
132
133
134 Extending the cgi interface
135 ---------------------------
136
137 Before 0.7.0 adding or extending web actions was done by overriding or adding
138 methods on the Client class. Though this approach still works to provide
139 backwards compatibility, it is recommended you upgrade to the new approach, as
140 described in the `Defining new web actions`__ section of the customization
141 documentation. You might also want to take a look at the `Using an external
142 password validation source`__ example.
143
144 __ customizing.html#defining-new-web-actions
145 __ customizing.html#using-an-external-password-validation-source
146
147 Actions may also return the content that should return to the user, which
148 causes the web interface to skip the normal template formatting step.
149 This could be used to return an image to the user instead of HTML. Be sure
150 to set the correct content-type header though! The default is still
151 text/html. This is done with::
152
153    self.client.setHeader('Content-Type', 'image/png')
154
155 if you were returning a PNG image.
156
157
158 Roundup server 
159 --------------
160
161 The roundup-server web interface now supports setgid and running on port
162 < 1024.
163
164 It also forks to handle new connections, which means that trackers using
165 the postgresql or mysql backends will be able to have multiple users
166 accessing the tracker simultaneously.
167
168
169 HTML templating made easier
170 ---------------------------
171
172 All HTML templating functions perform checks for permissions required to
173 display or edit the data they are manipulating. The simplest case is
174 editing an issue title. Including the expression::
175
176    context/title/field
177
178 will present the user with an edit field if they have Edit Permission. If
179 not, then they will be presented with a static display if they have View
180 Permission. If they don't even have View Permission, then an error message
181 is raised, preventing the display of the page, indicating that they don't
182 have permission to view the information.
183
184 This removes the need for the template to perform those checks, which was
185 just plain messy.
186
187 Some new permissions will need to be created in your trackers to cope with
188 this change, as outlined in the `upgrading documentation`__.
189
190 __ upgrading.html#permission-assignments
191
192
193 Standards changes
194 -----------------
195
196 The HTTP Content-Length header when we serve up files, either
197 static ones from the "html" folder or file content from the database.
198
199 We also handle If-Modified-Since and supply Last-Modified for both types
200 of file too.
201
202 The HTML generated in the classic tracker is now HTML4 (or optionally
203 XHTML) compliant. The ``config.py`` variable "HTML_VERSION" is used to
204 control this behaviour.
205
206 The stylesheet includes printer settings now too, so printed pages
207 don't include the sidebar.
208
209
210 Quoting of URLs and HTML
211 ------------------------
212
213 Templates that wish to offer file downloads may now use a new
214 ``download_url`` method::
215
216  <tr tal:repeat="file context/files">
217   <td>
218    <a tal:attributes="href file/download_url"
219       tal:content="file/name">dld link</a>
220   </td>
221  ...
222
223 The ``download_url`` method looks up the file's "id" and "name" and
224 generates a correctly-quoted URL.
225
226 Additionally, users wishing to URL- or HTML- quote text in their templates
227 may use the new ``utils.url_quote(url)`` and ``utils.html_quote(html)``
228 methods.
229
230
231 CSV download of search results
232 ------------------------------
233
234 A new CGI action, ``export_csv`` has been added which exports a given
235 index page query as a comma-separated-value file.
236
237 To use this new action, just add a link to your ``issue.index.html``
238 page::
239
240   <a tal:attributes="href python:request.indexargs_url('issue',
241             {'@action':'export_csv'})">Download as CSV</a>
242
243 You may use this for other classes by adding it to their index page and
244 changing the ``'issue'`` part of the expression to the new class' name.
245
246
247 Other changes
248 -------------
249
250 - we serve up a favicon now
251 - the page titles have the tracker name at the end of the text instead
252   of the start
253 - added url_quote and html_quote methods to the utils object
254 - added isset method to HTMLProperty
255 - added search_checkboxes as an option for the search form
256
257
258 Email Interface
259 ===============
260
261 Better handling of some email headers
262 -------------------------------------
263
264 We ignore messages with the header "Precedence: bulk".
265
266 If a Resent-From: header is present, it is used in preference to the From:
267 header when determining the author of the message. Useful for redirecting
268 error messages from automated systems.
269
270
271 Email character set
272 -------------------
273
274 The default character set for sending email is UTF-8 (ie. Unicode). If you
275 have users whose email clients can't handle UTF-8 (eg. Eudora) then you
276 will need to edit the new config.py variable ``EMAIL_CHARSET``.
277
278
279 Dispatcher configuration
280 ------------------------
281
282 A new config option has been added that specifies the email address of
283 a "dispatcher" role.  This email address acts as a central sentinel for
284 issues coming into the system. You can configure it so that all e-mail
285 error messages get bounced to them, them and the user in question, or
286 just the user (default).
287
288 To toggle these switches, add the "DISPATCHER_EMAIL" and
289 "ERROR_MESSAGES_TO" configuration values to your tracker's ``config.py``.
290 See the `customisation documentation`_ for how to use them.
291
292
293 More flexible message generation
294 --------------------------------
295
296 The code for generating email messages in Roundup has been refactored. A
297 new module, ``roundup.mailer`` contains most of the nuts-n-bolts required
298 to generate email messages from Roundup.
299
300 In addition, the ``IssueClass`` methods ``nosymessage()`` and
301 ``send_message()`` have both been altered so that they don't require the
302 message id parameter. This means that change notes with no associated
303 change message may now be generated much more easily.
304
305 The roundupdb nosymessage() method also accepts a ``bcc`` argument which
306 specifies additional userids to send the message to that will not be
307 included in the To: header of the message.
308
309
310 Registration confirmation by email
311 ----------------------------------
312
313 Users may now reply to their registration confirmation email, and the
314 roundup mail gateway will complete their registration.
315
316
317 ``roundup-mailgw`` now supports IMAP
318 ------------------------------------
319
320 To retrieve from an IMAP mailbox, use a *cron* entry similar to the
321 POP one::
322
323   0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
324
325 where imap_spec is "``username:password@server``" that specifies the roundup
326 submission user's IMAP account name, password and server. You may
327 optionally include a mailbox to use other than the default ``INBOX`` with
328 "``imap username:password@server mailbox``".
329
330 If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
331 in place of ``imap`` in the command to use a secure connection.
332
333
334 Database configuration
335 ======================
336
337 Postgresql added as a backend option
338 ------------------------------------
339
340 Trackers may now use the postgresql RDBMS as a database store.
341
342 Postgresql is a good choice if you expect your tracker to grow very large,
343 and are expecting many users.
344
345
346 API change
347 ----------
348
349 The Database.curuserid attribute was removed. Any code referencing this
350 attribute should be replaced with a call to Database.getuid().
351
352
353 New configuration options
354 -------------------------
355
356 - Added DEFAULT_TIMEZONE which allows the tracker to have a different
357   default to UTC when users don't specify their own preference.
358
359 - Added EMAIL_CHARSET (in 0.6.6, but worth mentioning here) which hard-codes
360   the character set to be used when sending email from Roundup. This works
361   around some email clients' inability to cope well with UTF-8 (the
362   default).
363
364 - ERROR_MESSAGES_TO and DISPATCHER_EMAIL as described above in `Dispatcher
365   configuration`_.
366
367
368 Typed columns in RDBMS backends
369 -------------------------------
370
371 The SQLite, MySQL and Postgresql backends now create tables with
372 appropriate column datatypes (not just varchar).
373
374 Your database will be automatically migrated to use the new schemas, but
375 it will take time. It's probably a good idea to make sure you do this as
376 part of the upgrade when users are not expected to be using the system.
377
378
379 Permission setup
380 ----------------
381
382 0.7 automatically sets up the Edit and View Permissions for all classes,
383 thus you don't need to do so. Feel free to remove the code::
384
385     # Add new Permissions for this schema
386     for cl in 'issue', 'file', 'msg', 'user', 'query', 'keyword':
387         db.security.addPermission(name="Edit", klass=cl,
388             description="User is allowed to edit "+cl)
389         db.security.addPermission(name="View", klass=cl,
390             description="User is allowed to access "+cl)
391
392 from your ``dbinit.py``.
393
394
395 New "actor" property
396 --------------------
397
398 Roundup's database has a new per-item property "actor" which reflects the
399 user performing the last "actvitiy". See the classic template for ways to
400 integrate this new property into your interface.
401
402 The property will be automatically added to your existing database.
403
404
405 New Reject exception for Auditors
406 ---------------------------------
407
408 An auditor may raise this exception when the current create or set
409 operation should be stopped.
410
411 It is up to the specific interface invoking the create or set to
412 handle this exception sanely. For example:
413
414 - mailgw will trap and ignore Reject for file attachments and messages
415 - cgi will trap and present the exception in a nice format
416
417
418 New auditor fixes Outlook bug
419 -----------------------------
420
421 The new optional auditor ``detectors/emailauditor.py`` fires whenever a
422 new file entity is created.
423
424 If the file is of type message/rfc822, we tack on the extension .mht.
425
426 The reason for this is that Microsoft Internet Explorer will not open
427 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
428 they'll just give you an incomprehensible error message. For more 
429 information, please see: 
430
431 http://support.microsoft.com/default.aspx?scid=kb;EN-US;825803
432
433 Their suggested work around is (excerpt):
434
435  WORKAROUND
436
437  To work around this behavior, rename the .EML file that the URL
438  links to so that it has a .MHT file name extension, and then update
439  the URL to reflect the change to the file name. To do this:
440
441  1. In Windows Explorer, locate and then select the .EML file that
442     the URL links.
443  2. Right-click the .EML file, and then click Rename.
444  3. Change the file name so that the .EML file uses a .MHT file name
445     extension, and then press ENTER.
446  4. Updated the URL that links to the file to reflect the new file
447     name extension.
448
449
450 New script for copying users
451 ----------------------------
452
453 A new script, ``scripts/copy-user.py``, will copy users from one tracker
454 to another.  Example usage::
455
456     copy-user.py /roundup/tracker1 /roundup/tracker2 `seq 3 10` 14 16
457
458 which copies users 3, 4, 5, 6, 7, 8, 9, 10, 14 and 16.
459
460
461 Other improvements
462 ------------------
463
464 - All RDBMS backends now have indexes automatically created on critical
465   table columns.
466
467 - Additionally, the RDBMS backends also implement their own session,
468   one-time-key and full-text indexing stores. These were previously external
469   dbm stores. This change allows control of locking the database to be
470   completely handed over to the RDBMS.
471
472 - Date values capture fractions of seconds now. Note that the MySQL backend
473   is not capable of storing this precision though, so it will be lost for
474   users of that backend.
475
476 - The roundup-admin "export" and "import" commands now handle the database
477   journals too. This means that exports from previous versions of Roundup
478   will not work under 0.7!
479
480
481 .. _`customisation documentation`: customizing.html