doc/whatsnew-0.7.txt

   1 =========================
   2 What's New in Roundup 0.7
   3 =========================
   4
   5 .. contents::
   6
   7 Web Interface
   8 =============
   9
  10 Saving and sharing of user queries
  11 ----------------------------------
  12
  13 Due to popular demand, the user query saving mechanisms have been
  14 overhauled.
  15
  16 As before, you may save queries in the tracker by giving the query a
  17 name. Each user may only have one query with a given name - if a
  18 subsequent search is performed with the same query name supplied, then
  19 it will edit the existing query of the same name.
  20
  21 Queries may be marked as "private". These queries are only visible to the
  22 user that created them. If they're not marked "private" then all other
  23 users may include the query in their list of "Your Queries". Marking it as
  24 private at a later date does not affect users already using the query, nor
  25 does deleting the query.
  26
  27 If a user subsequently creates or edits a public query, a new personal
  28 version of that query is made, with the same editing rules as described
  29 above.
  30
  31 You *are not required* to make these changes in your tracker. You only
  32 need to make them if you wish to use the new query editing features. It's
  33 highly recommended, as the effort is minimal.
  34
  35 1. You will need to edit your tracker's ``dbinit.py`` to change the way
  36    queries are stored. Change the lines::
  37
  38       query = Class(db, "query",
  39                       klass=String(),     name=String(),
  40                       url=String())
  41       query.setkey("name")
  42
  43    to::
  44
  45       query = Class(db, "query",
  46                       klass=String(),     name=String(),
  47                       url=String(),       private_for=Link('user'))
  48
  49    That is, add the "private_for" property, and remove the line that says
  50    ``query.setkey("name")``. The latter is the most important edit here.
  51
  52 2. You will also need to copy the ``query.edit.html`` template page from the
  53    ``templates/classic/html/`` directory of the source to your tracker's
  54    ``html`` directory.
  55
  56 3. Once you've done that, edit the tracker's ``page.html`` template to
  57    change::
  58
  59     <td rowspan="2" valign="top" class="sidebar">
  60      <p class="classblock" tal:condition="request/user/queries">
  61       <b>Your Queries</b><br>
  62       <tal:block tal:repeat="qs request/user/queries">
  63
  64    to::
  65
  66     <td rowspan="2" valign="top" class="sidebar">
  67      <p class="classblock">
  68       <b>Your Queries</b> (<a href="query?@template=edit">edit</a>)<br>
  69       <tal:block tal:repeat="qs request/user/queries">
  70
  71    That is, you're removing the ``tal:condition`` and adding a link to the
  72    new edit page.
  73
  74 4. You might also wish to remove the redundant query editing section from the
  75    ``user.item.html`` page.
  76
  77
  78 Simple support for collision detection
  79 --------------------------------------
  80
  81 Item edit pages that use the ``context/submit`` function to generate their
  82 submit buttons now automatically include a datestamp in the form. This
  83 datestamp is compared to the "activity" property of the item when the form
  84 is submitted. If the "actvity" property is younger than the datestamp in
  85 the form submission, then someone else has edited the item, and a page
  86 indicating this is displayed to the user.
  87
  88
  89 Extending the cgi interface
  90 ---------------------------
  91
  92 Before 0.7.0 adding or extending web actions was done by overriding or adding
  93 methods on the Client class. Though this approach still works to provide
  94 backwards compatibility, it is recommended you upgrade to the new approach, as
  95 described in the `Defining new web actions`__ section of the customization
  96 documentation. You might also want to take a look at the `Using an external
  97 password validation source`__ example.
  98
  99 __ customizing.html#defining-new-web-actions
 100 __ customizing.html#using-an-external-password-validation-source
 101
 102 Actions may also return the content that should return to the user, which
 103 causes the web interface to skip the normal template formatting step.
 104 This could be used to return an image to the user instead of HTML. Be sure
 105 to set the correct content-type header though! The default is still
 106 text/html. This is done with::
 107
 108    self.client.setHeader('Content-Type', 'image/png')
 109
 110 if you were returning a PNG image.
 111
 112
 113 Added CSV export action
 114 -----------------------
 115
 116 A new action has been added which exports the current index page or search
 117 result as a comma-separated-value (CSV) file.
 118
 119 To use it, add this to your "index" templates:
 120
 121 <a tal:attributes="href python:request.indexargs_url('issue',
 122             {'@action':'csv_export'})">Download as CSV</a>
 123
 124 Making sure that the ``'issue'`` part matches the class name of the page
 125 you're editing.
 126
 127 Roundup server
 128 --------------
 129
 130 The roundup-server web interface now supports setgid and running on port
 131 < 1024.
 132
 133
 134 HTML templating made easier
 135 ---------------------------
 136
 137 All HTML templating functions perform checks for permissions required to
 138 display or edit the data they are manipulating. The simplest case is
 139 editing an issue title. Including the expression::
 140
 141    context/title/field
 142
 143 Will present the user with an edit field, if they have edit permission. If
 144 not, then they will be presented with a static display if they have view
 145 permission. If they don't even have view permission, then an error message
 146 is raised, preventing the display of the page, indicating that they don't
 147 have permission to view the information.
 148
 149 This removes the need for the template to perform those checks, which was
 150 just plain messy.
 151
 152
 153 Standards changes
 154 -----------------
 155
 156 We now set the HTTP Content-Length header when we serve up files, either
 157 static ones from the "html" folder or file content from the database.
 158
 159 We also handle If-Modified-Since and supply Last-Modified for both types
 160 of file too.
 161
 162 The HTML generated in the classic tracker is now HTML4 (or optionally
 163 XHTML) compliant. The ``config.py`` variable "HTML_VERSION" is used to
 164 control this behaviour.
 165
 166 We've got a printer setting in the stylesheet now too, so printed pages
 167 don't include the sidebar.
 168
 169
 170 Email Interface
 171 ===============
 172
 173 Better handling of some email headers
 174 -------------------------------------
 175
 176 We ignore messages with the header "Precedence: bulk".
 177
 178 If a Resent-From: header is present, it is used in preference to the From:
 179 header when determining the author of the message. Useful for redirecting
 180 error messages from automated systems.
 181
 182
 183 Email character set
 184 -------------------
 185
 186 The default character set for sending email is UTF-8 (ie. Unicode). If you
 187 have users whose email clients can't handle UTF-8 (eg. Eudora) then you
 188 will need to edit the new config.py variable ``EMAIL_CHARSET``.
 189
 190
 191 Dispatcher configuration
 192 ------------------------
 193
 194 A new config option has been added that specifies the email address of
 195 a "dispatcher" role.  This email address acts as a central sentinel for
 196 issues coming into the system. You can configure it so that all e-mail
 197 error messages get bounced to them, them and the user in question, or
 198 just the user (default).
 199
 200 To toggle these switches, add the "DISPATCHER_EMAIL" and
 201 "ERROR_MESSAGES_TO" configuration values to your tracker's ``config.py``.
 202 See the `customisation documentation`_ for how to use them.
 203
 204
 205 More flexible message generation
 206 --------------------------------
 207
 208 The code for generating email messages in Roundup has been refactored. A
 209 new module, ``roundup.mailer`` contains most of the nuts-n-bolts required
 210 to generate email messages from Roundup.
 211
 212 In addition, the ``IssueClass`` methods ``nosymessage()`` and
 213 ``send_message()`` have both been altered so that they don't require the
 214 message id parameter. This means that change notes with no associated
 215 change message may now be generated much more easily.
 216
 217
 218 Registration confirmation by email
 219 ----------------------------------
 220
 221 Users may now reply to their registration confirmation email, and the
 222 roundup mail gateway will complete their registration.
 223
 224
 225 Database configuration
 226 ======================
 227
 228 Postgresql added as a backend option
 229 ------------------------------------
 230
 231 Trackers may now use the postgresql RDBMS as a database store.
 232
 233 Postgresql is a good choice if you expect your tracker to grow very large,
 234 and are expecting many users.
 235
 236
 237 Other improvements
 238 ------------------
 239
 240 All RDBMS backends now have indexes automatically created on critical
 241 table columns.
 242
 243 Additionally, the RDBMS backends also implement their own session,
 244 one-time-key and full-text indexing stores. These were previously external
 245 dbm stores. This change allows control of locking the database to be
 246 completely handed over to the RDBMS.
 247
 248 Date values capture fractions of seconds now. Note that the MySQL backend
 249 is not capable of storing this precision though, so it will be lost for
 250 users of that backend.
 251
 252
 253 Typed columns in RDBMS backends
 254 -------------------------------
 255
 256 The MySQL (and Postgresql for that matter) backend now creates tables with
 257 appropriate column datatypes (not just varchar). Sqlite got the typing
 258 too, but it ignores the datatypes :)
 259
 260 Your database will be automatically migrated to use the new schemas, but
 261 it will take time. It's probably a good idea to make sure you do this as
 262 part of the upgrade when users are not expected to be using the system.
 263
 264
 265 Permission setup
 266 ----------------
 267
 268 0.7 automatically sets up the Edit and View Permissions for all classes,
 269 thus you don't need to do so. Feel free to remove the code::
 270
 271     # Add new Permissions for this schema
 272     for cl in 'issue', 'file', 'msg', 'user', 'query', 'keyword':
 273         db.security.addPermission(name="Edit", klass=cl,
 274             description="User is allowed to edit "+cl)
 275         db.security.addPermission(name="View", klass=cl,
 276             description="User is allowed to access "+cl)
 277
 278 from your ``dbinit.py``.
 279
 280
 281 New "actor" property
 282 --------------------
 283
 284 Roundup's database has a new per-item property "actor" which reflects the
 285 user performing the last "actvitiy". See the classic template for ways to
 286 integrate this new property into your interface.
 287
 288 The property will be automatically added to your existing database.
 289
 290
 291 New Reject exception for Auditors
 292 ---------------------------------
 293
 294 An auditor may raise this exception when the current create or set
 295 operation should be stopped.
 296
 297 It is up to the specific interface invoking the create or set to
 298 handle this exception sanely. For example:
 299
 300 - mailgw will trap and ignore Reject for file attachments and messages
 301 - cgi will trap and present the exception in a nice format
 302
 303
 304 New auditor fixes Outlook bug
 305 -----------------------------
 306
 307 The new optional auditor ``detectors/emailauditor.py`` fires whenever a
 308 new file entity is created.
 309
 310 If the file is of type message/rfc822, we tack onthe extension .eml.
 311
 312 The reason for this is that Microsoft Internet Explorer will not open
 313 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
 314 they'll just give you an incomprehensible error message. For more
 315 information, please see:
 316
 317 http://support.microsoft.com/default.aspx?scid=kb;EN-US;825803
 318
 319 Their suggested work around is (excerpt):
 320
 321  WORKAROUND
 322
 323  To work around this behavior, rename the .EML file that the URL
 324  links to so that it has a .MHT file name extension, and then update
 325  the URL to reflect the change to the file name. To do this:
 326
 327  1. In Windows Explorer, locate and then select the .EML file that
 328     the URL links.
 329  2. Right-click the .EML file, and then click Rename.
 330  3. Change the file name so that the .EML file uses a .MHT file name
 331     extension, and then press ENTER.
 332  4. Updated the URL that links to the file to reflect the new file
 333     name extension.
 334
 335
 336 New script for copying users
 337 ----------------------------
 338
 339 A new script, ``scripts/copy-user.py``, will copy users from one tracker
 340 to another.  Example usage::
 341
 342     copy-user.py /roundup/tracker1 /roundup/tracker2 `seq 3 10` 14 16
 343
 344 which copies users 3, 4, 5, 6, 7, 8, 9, 10, 14 and 16.
 345
 346
 347 .. _`customisation documentation`: customizing.html