doc/upgrading.txt

   1 ======================================
   2 Upgrading to newer versions of Roundup
   3 ======================================
   4
   5 Please read each section carefully and edit your tracker home files
   6 accordingly.
   7
   8 .. contents::
   9
  10 Migrating from 0.5 to 0.6
  11 =========================
  12
  13 0.6.0 Configuration
  14 -------------------
  15
  16 Introduced EMAIL_FROM_TAG config variable. This value is inserted into
  17 the From: line of nosy email. If the sending user is "Foo Bar", the
  18 From: line is usually::
  19
  20      "Foo Bar" <issue_tracker@tracker.example>
  21
  22 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
  23
  24      "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
  25
  26 I've altered the mechanism in the detectors __init__.py module so that it
  27 doesn't cross-import detectors from other trackers (if you run more than one
  28 in a single roundup-server). This change means that you'll need to copy the
  29 __init__.py from roundup/templates/classic/detectors/__init__.py to your
  30 <tracker home>/detectors/__init__.py. Don't worry, the "classic" __init__ is a
  31 one-size-fits-all, so it'll work even if you've added/removed detectors.
  32
  33
  34 0.6.0 Form handling changes
  35 ---------------------------
  36
  37 Roundup's form handling capabilities have been significantly expanded. This
  38 should not affect users of 0.5 installations - but if you find you're
  39 getting errors from form submissions, please ask for help on the Roundup
  40 users mailing list:
  41
  42   http://lists.sourceforge.net/lists/listinfo/roundup-users
  43
  44 See the customisation doc section on `Form Values`__ for documentation of the
  45 new form variables possible.
  46
  47 __ customizing.html#form-values
  48
  49
  50 0.6.0 Multilingual character set support
  51 ----------------------------------------
  52
  53 Added internationalization support. This is done via encoding all data
  54 stored in roundup database to utf-8 (unicode encoding). To support utf-8 in
  55 web interface you should add the folowing line to your tracker's html/page
  56 and html/_generic.help files inside <head> tag::
  57
  58     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  59
  60 Since latin characters in utf-8 have the same codes as in ASCII table, this
  61 modification is optional for users who use only plain latin characters.
  62
  63 After this modification, you will be able to see and enter any world
  64 character via web interface. Data received via mail interface also converted
  65 to utf-8, however only new messages will be converted. If your roundup
  66 database contains some of non-ASCII characters in one of 8-bit encoding,
  67 they will not be visible in new unicode environment. Some of such data (e.g.
  68 user names, keywords, etc)  can be edited by administrator, the others
  69 (e.g. messages' contents) is not editable via web interface. Currently there
  70 is no tool for converting such data, the only solution is to close
  71 appropriate old issues and create new ones with the same content.
  72
  73 0.6.0 User timezone support
  74 ---------------------------
  75
  76 From version 0.6.0 roundup supports displaying of Date data in user' local
  77 timezone if he/she has provided timezone information. To make it possible
  78 some modification to tracker's schema and HTML templates are required.
  79 First you should add string property 'timezone' to user class in dbinit.py
  80 like this::
  81
  82     user = Class(db, "user",
  83                     username=String(),   password=Password(),
  84                     address=String(),    realname=String(),
  85                     phone=String(),      organisation=String(),
  86                     alternate_addresses=String(),
  87                     queries=Multilink('query'), roles=String(),
  88                     timezone=String())
  89
  90 And second - html interface. Add following lines to
  91 $TRACKER_HOME/html/user.item template::
  92
  93      <tr>
  94       <th>Timezone</th>
  95       <td tal:content="structure context/timezone/field">timezone</td>
  96      </tr>
  97
  98 After that all users should be able to provide their timezone information.
  99 Timezone should be a positive or negative integer - offset from GMT.
 100
 101 After providing timezone, roundup will show all dates values, found in web
 102 and mail interfaces in local time. It will also accept any Date info in
 103 local time, convert and store it in GMT.
 104
 105 However you are not forced to make these modifications. By default roundup
 106 will assume timezone=0 and will work as previous versions did.
 107
 108 0.6.0 Search page structure
 109 ---------------------------
 110
 111 In order to accomodate query editing the search page has been restructured. If
 112 you want to provide your users with query editing, you should update your
 113 search page using the macros detailed in the customisation doc section
 114 `Searching on categories`__.
 115
 116 __ customizing.html#searching-on-categories
 117
 118
 119 0.6.0 Notes for metakit backend users
 120 -------------------------------------
 121
 122 Roundup 0.6.0 introduced searching on ranges of dates and intervals. To
 123 support it, some modifications to interval storing routine were made. So if
 124 your tracker uses metakit backend and your db schema contains intervals
 125 property, searches on that property will not be accurate for db items that
 126 was stored before roundup' upgrade. However all new records should be
 127 searchable on intervals.
 128
 129 It is possible to convert your database to new format: you can export and
 130 import back all your data (consult "Migrating backends" in "Maintenance"
 131 documentation). After this operation all your interval properties should
 132 become searchable.
 133
 134 Users of backends others than metakit should not worry about this issue.
 135
 136
 137 Migrating from 0.4.x to 0.5.0
 138 =============================
 139
 140 This has been a fairly major revision of Roundup:
 141
 142 1. Brand new, much more powerful, flexible, tasty and nutritious templating.
 143    Unfortunately, this means all your current templates are useless. Hopefully
 144    the new documentation and examples will be enough to help you make the
 145    transition. Please don't hesitate to ask on roundup-users for help (or
 146    complete conversions if you're completely stuck)!
 147 2. The database backed got a lot more flexible, allowing Metakit and SQL
 148    databases! The only decent SQL database implemented at present is sqlite,
 149    but others shouldn't be a whole lot more work.
 150 3. A brand new, highly flexible and much more robust security system including
 151    a system of Permissions, Roles and Role assignments to users. You may now
 152    define your own Permissions that may be checked in CGI transactions.
 153 4. Journalling has been made less storage-hungry, so has been turned on
 154    by default *except* for author, recipient and nosy link/unlink events. You
 155    are advised to turn it off in your trackers too.
 156 5. We've changed the terminology from "instance" to "tracker", to ease the
 157    learning curve/impact for new users.
 158 6. Because of the above changes, the tracker configuration has seen some
 159    major changes. See below for the details.
 160
 161 Please, **back up your database** before you start the migration process. This
 162 is as simple as copying the "db" directory and all its contents from your
 163 tracker to somewhere safe.
 164
 165
 166 0.5.0 Configuration
 167 -------------------
 168
 169 First up, rename your ``instance_config.py`` file to just ``config.py``.
 170
 171 Then edit your tracker's ``__init__.py`` module. It'll currently look
 172 like this::
 173
 174  from instance_config import *
 175  try:
 176      from dbinit import *
 177  except ImportError:
 178      pass # in installdir (probably :)
 179  from interfaces import *
 180
 181 and it needs to be::
 182
 183  import config
 184  from dbinit import open, init
 185  from interfaces import Client, MailGW
 186
 187 Due to the new templating having a top-level ``page`` that defines links for
 188 searching, indexes, adding items etc, the following variables are no longer
 189 used:
 190
 191 - HEADER_INDEX_LINKS
 192 - HEADER_ADD_LINKS
 193 - HEADER_SEARCH_LINKS
 194 - SEARCH_FILTERS
 195 - DEFAULT_INDEX
 196 - UNASSIGNED_INDEX
 197 - USER_INDEX
 198 - ISSUE_FILTER
 199
 200 The new security implementation will require additions to the dbinit module,
 201 but also removes the need for the following tracker config variables:
 202
 203 - ANONYMOUS_ACCESS
 204 - ANONYMOUS_REGISTER
 205
 206 but requires two new variables which define the Roles assigned to users who
 207 register through the web and e-mail interfaces:
 208
 209 - NEW_WEB_USER_ROLES
 210 - NEW_EMAIL_USER_ROLES
 211
 212 in both cases, 'User' is a good initial setting. To emulate
 213 ``ANONYMOUS_ACCESS='deny'``, remove all "View" Permissions from the
 214 "Anonymous" Role. To emulate ``ANONYMOUS_REGISTER='deny'``, remove the "Web
 215 Registration" and/or the "Email Registration" Permission from the "Anonymous"
 216 Role. See the section on customising security in the `customisation
 217 documentation`_ for more information.
 218
 219 Finally, the following config variables have been renamed to make more sense:
 220
 221 - INSTANCE_HOME -> TRACKER_HOME
 222 - INSTANCE_NAME -> TRACKER_NAME
 223 - ISSUE_TRACKER_WEB -> TRACKER_WEB
 224 - ISSUE_TRACKER_EMAIL -> TRACKER_EMAIL
 225
 226
 227 0.5.0 Schema Specification
 228 --------------------------
 229
 230 0.5.0 Database backend changes
 231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 232
 233 Your select_db module in your tracker has changed a fair bit. Where it used
 234 to contain::
 235
 236  # WARNING: DO NOT EDIT THIS FILE!!!
 237  from roundup.backends.back_anydbm import Database
 238
 239 it must now contain::
 240
 241  # WARNING: DO NOT EDIT THIS FILE!!!
 242  from roundup.backends.back_anydbm import Database, Class, FileClass, IssueClass
 243
 244 Yes, I realise the irony of the "DO NOT EDIT THIS FILE" statement :)
 245 Note the addition of the Class, FileClass, IssueClass imports. These are very
 246 important, as they're going to make the next change work too. You now need to
 247 modify the top of the dbinit module in your tracker from::
 248
 249  import instance_config
 250  from roundup import roundupdb
 251  from select_db import Database
 252
 253  from roundup.roundupdb import Class, FileClass
 254
 255  class Database(roundupdb.Database, select_db.Database):
 256      ''' Creates a hybrid database from:
 257           . the selected database back-end from select_db
 258           . the roundup extensions from roundupdb
 259      '''
 260      pass
 261
 262  class IssueClass(roundupdb.IssueClass):
 263      ''' issues need the email information
 264      '''
 265      pass
 266
 267 to::
 268
 269  import config
 270  from select_db import Database, Class, FileClass, IssueClass
 271
 272 Yes, remove the Database and IssueClass definitions and those other imports.
 273 They're not needed any more!
 274
 275 Look for places in dbinit.py where ``instance_config`` is used too, and
 276 rename them ``config``.
 277
 278
 279 0.5.0 Journalling changes
 280 ~~~~~~~~~~~~~~~~~~~~~~~~~
 281
 282 Journalling has been optimised for storage. Journalling of links has been
 283 turned back on by default. If your tracker has a large user base, you may wish
 284 to turn off journalling of nosy list, message author and message recipient
 285 link and unlink events. You do this by adding ``do_journal='no'`` to the Class
 286 initialisation in your dbinit. For example, your *msg* class initialisation
 287 probably looks like this::
 288
 289     msg = FileClass(db, "msg",
 290                     author=Link("user"), recipients=Multilink("user"),
 291                     date=Date(),         summary=String(),
 292                     files=Multilink("file"),
 293                     messageid=String(),  inreplyto=String())
 294
 295 to turn off journalling of author and recipient link events, add
 296 ``do_journal='no'`` to the ``author=Link("user")`` part of the statement,
 297 like so::
 298
 299     msg = FileClass(db, "msg",
 300                     author=Link("user", do_journal='no'),
 301                     recipients=Multilink("user", do_journal='no'),
 302                     date=Date(),         summary=String(),
 303                     files=Multilink("file"),
 304                     messageid=String(),  inreplyto=String())
 305
 306 Nosy list link event journalling is actually turned off by default now. If you
 307 want to turn it on, change to your issue class' nosy list, change its
 308 definition from::
 309
 310     issue = IssueClass(db, "issue",
 311                     assignedto=Link("user"), topic=Multilink("keyword"),
 312                     priority=Link("priority"), status=Link("status"))
 313
 314 to::
 315
 316     issue = IssueClass(db, "issue", nosy=Multilink("user", do_journal='yes'),
 317                     assignedto=Link("user"), topic=Multilink("keyword"),
 318                     priority=Link("priority"), status=Link("status"))
 319
 320 noting that your definition of the nosy Multilink will override the normal one.
 321
 322
 323 0.5.0 User schema changes
 324 ~~~~~~~~~~~~~~~~~~~~~~~~~
 325
 326 Users have two more properties, "queries" and "roles". You'll have something
 327 like this in your dbinit module now::
 328
 329     user = Class(db, "user",
 330                     username=String(),   password=Password(),
 331                     address=String(),    realname=String(),
 332                     phone=String(),      organisation=String(),
 333                     alternate_addresses=String())
 334     user.setkey("username")
 335
 336 and you'll need to add the new properties and the new "query" class to it
 337 like so::
 338
 339     query = Class(db, "query",
 340                     klass=String(),     name=String(),
 341                     url=String())
 342     query.setkey("name")
 343
 344     # Note: roles is a comma-separated string of Role names
 345     user = Class(db, "user",
 346                     username=String(),   password=Password(),
 347                     address=String(),    realname=String(),
 348                     phone=String(),      organisation=String(),
 349                     alternate_addresses=String(),
 350                     queries=Multilink('query'), roles=String())
 351     user.setkey("username")
 352
 353 The "queries" property is used to store off the user's favourite database
 354 queries. The "roles" property is explained below in `0.5.0 Security
 355 Settings`_.
 356
 357
 358 0.5.0 Security Settings
 359 ~~~~~~~~~~~~~~~~~~~~~~~
 360
 361 See the `security documentation`_ for an explanation of how the new security
 362 system works. In a nutshell though, the security is handled as a four step
 363 process:
 364
 365 1. Permissions are defined as having a name and optionally a hyperdb class
 366    they're specific to,
 367 2. Roles are defined that have one or more Permissions,
 368 3. Users are assigned Roles in their "roles" property, and finally
 369 4. Roundup checks that users have appropriate Permissions at appropriate times
 370    (like editing issues).
 371
 372 Your tracker dbinit module's *open* function now has to define any
 373 Permissions that are specific to your tracker, and also the assignment
 374 of Permissions to Roles. At the moment, your open function
 375 ends with::
 376
 377     import detectors
 378     detectors.init(db)
 379
 380     return db
 381
 382 and what we need to do is insert some commands that will set up the security
 383 parameters. Right above the ``import detectors`` line, you'll want to insert
 384 these lines::
 385
 386     #
 387     # SECURITY SETTINGS
 388     #
 389     # new permissions for this schema
 390     for cl in 'issue', 'file', 'msg', 'user':
 391         db.security.addPermission(name="Edit", klass=cl,
 392             description="User is allowed to edit "+cl)
 393         db.security.addPermission(name="View", klass=cl,
 394             description="User is allowed to access "+cl)
 395
 396     # Assign the access and edit permissions for issue, file and message
 397     # to regular users now
 398     for cl in 'issue', 'file', 'msg':
 399         p = db.security.getPermission('View', cl)
 400         db.security.addPermissionToRole('User', p)
 401         p = db.security.getPermission('Edit', cl)
 402         db.security.addPermissionToRole('User', p)
 403     # and give the regular users access to the web and email interface
 404     p = db.security.getPermission('Web Access')
 405     db.security.addPermissionToRole('User', p)
 406     p = db.security.getPermission('Email Access')
 407     db.security.addPermissionToRole('User', p)
 408
 409     # May users view other user information? Comment these lines out
 410     # if you don't want them to
 411     p = db.security.getPermission('View', 'user')
 412     db.security.addPermissionToRole('User', p)
 413
 414     # Assign the appropriate permissions to the anonymous user's Anonymous
 415     # Role. Choices here are:
 416     # - Allow anonymous users to register through the web
 417     p = db.security.getPermission('Web Registration')
 418     db.security.addPermissionToRole('Anonymous', p)
 419     # - Allow anonymous (new) users to register through the email gateway
 420     p = db.security.getPermission('Email Registration')
 421     db.security.addPermissionToRole('Anonymous', p)
 422     # - Allow anonymous users access to the "issue" class of data
 423     #   Note: this also grants access to related information like files,
 424     #         messages, statuses etc that are linked to issues
 425     #p = db.security.getPermission('View', 'issue')
 426     #db.security.addPermissionToRole('Anonymous', p)
 427     # - Allow anonymous users access to edit the "issue" class of data
 428     #   Note: this also grants access to create related information like
 429     #         files and messages etc that are linked to issues
 430     #p = db.security.getPermission('Edit', 'issue')
 431     #db.security.addPermissionToRole('Anonymous', p)
 432
 433     # oh, g'wan, let anonymous access the web interface too
 434     p = db.security.getPermission('Web Access')
 435     db.security.addPermissionToRole('Anonymous', p)
 436
 437 Note in the comments there the places where you might change the permissions
 438 to restrict users or grant users more access. If you've created additional
 439 classes that users should be able to edit and view, then you should add them
 440 to the "new permissions for this schema" section at the start of the security
 441 block. Then add them to the "Assign the access and edit permissions" section
 442 too, so people actually have the new Permission you've created.
 443
 444 One final change is needed that finishes off the security system's
 445 initialisation. We need to add a call to ``db.post_init()`` at the end of the
 446 dbinit open() function. Add it like this::
 447
 448     import detectors
 449     detectors.init(db)
 450
 451     # schema is set up - run any post-initialisation
 452     db.post_init()
 453     return db
 454
 455 You may verify the setup of Permissions and Roles using the new
 456 "``roundup-admin security``" command.
 457
 458
 459 0.5.0 User changes
 460 ~~~~~~~~~~~~~~~~~~
 461
 462 To support all those schema changes, you'll need to massage your user database
 463 a little too, to:
 464
 465 1. make sure there's an "anonymous" user - this user is mandatory now and is
 466    the one that unknown users are logged in as.
 467 2. make sure all users have at least one Role.
 468
 469 If you don't have the "anonymous" user, create it now with the command::
 470
 471   roundup-admin create user username=anonymous roles=Anonymous
 472
 473 making sure the capitalisation is the same as above. Once you've done that,
 474 you'll need to set the roles property on all users to a reasonable default.
 475 The admin user should get "Admin", the anonymous user "Anonymous"
 476 and all other users "User". The ``fixroles.py`` script in the tools directory
 477 will do this. Run it like so (where python is your python 2+ binary)::
 478
 479   python tools/fixroles.py -i <tracker home> fixroles
 480
 481
 482
 483 0.5.0 CGI interface changes
 484 ---------------------------
 485
 486 The CGI interface code was completely reorganised and largely rewritten. The
 487 end result is that this section of your tracker interfaces module will need
 488 changing from::
 489
 490  from roundup import cgi_client, mailgw
 491  from roundup.i18n import _
 492
 493  class Client(cgi_client.Client):
 494      ''' derives basic CGI implementation from the standard module,
 495          with any specific extensions
 496      '''
 497      pass
 498
 499 to::
 500
 501  from roundup import mailgw
 502  from roundup.cgi import client
 503
 504  class Client(client.Client):
 505      ''' derives basic CGI implementation from the standard module,
 506          with any specific extensions
 507      '''
 508      pass
 509
 510 You will also need to install the new version of roundup.cgi from the source
 511 cgi-bin directory if you're using it.
 512
 513
 514 0.5.0 HTML templating
 515 ---------------------
 516
 517 You'll want to make a backup of your current tracker html directory. You
 518 should then copy the html directory from the Roundup source "classic" template
 519 and modify it according to your local schema changes.
 520
 521 If you need help with the new templating system, please ask questions on the
 522 roundup-users mailing list (available through the roundup project page on
 523 sourceforge, http://roundup.sf.net/)
 524
 525
 526 0.5.0 Detectors
 527 ---------------
 528
 529 The nosy reactor has been updated to handle the tracker not having an
 530 "assignedto" property on issues. You may want to copy it into your tracker's
 531 detectors directory. Chances are you've already fixed it though :)
 532
 533
 534 Migrating from 0.4.1 to 0.4.2
 535 =============================
 536
 537 0.4.2 Configuration
 538 -------------------
 539 The USER_INDEX definition introduced in 0.4.1 was too restrictive in its
 540 allowing replacement of 'assignedto' with the user's userid. Users must change
 541 the None value of 'assignedto' to 'CURRENT USER' (the string, in quotes) for
 542 the replacement behaviour to occur now.
 543
 544 The new configuration variables are:
 545
 546 - EMAIL_KEEP_QUOTED_TEXT
 547 - EMAIL_LEAVE_BODY_UNCHANGED
 548 - ADD_RECIPIENTS_TO_NOSY
 549
 550 See the sample configuration files in::
 551
 552  <roundup source>/roundup/templates/classic/instance_config.py
 553
 554 and::
 555
 556  <roundup source>/roundup/templates/extended/instance_config.py
 557
 558 and the `customisation documentation`_ for information on how they're used.
 559
 560
 561 0.4.2 Changes to detectors
 562 --------------------------
 563 You will need to copy the detectors from the distribution into your instance
 564 home "detectors" directory. If you used the classic schema, the detectors
 565 are in::
 566
 567  <roundup source>/roundup/templates/classic/detectors/
 568
 569 If you used the extended schema, the detectors are in::
 570
 571  <roundup source>/roundup/templates/extended/detectors/
 572
 573 The change means that schema-specific code has been removed from the
 574 mail gateway and cgi interface and made into auditors:
 575
 576 - nosyreactor.py has now got an updatenosy auditor which updates the nosy
 577   list with author, recipient and assignedto information.
 578 - statusauditor.py makes the unread or resolved -> chatting changes and
 579   presets the status of an issue to unread.
 580
 581 There's also a bug or two fixed in the nosyreactor code.
 582
 583 0.4.2 HTML templating changes
 584 -----------------------------
 585 The link() htmltemplate function now has a "showid" option for links and
 586 multilinks. When true, it only displays the linked item id as the anchor
 587 text. The link value is displayed as a tooltip using the title anchor
 588 attribute. To use in eg. the superseder field, have something like this::
 589
 590    <td>
 591     <display call="field('superseder', showid=1)">
 592     <display call="classhelp('issue', 'id,title', label='list', width=500)">
 593     <property name="superseder">
 594      <br>View: <display call="link('superseder', showid=1)">
 595     </property>
 596    </td>
 597
 598 The stylesheets have been cleaned up too. You may want to use the newer
 599 versions in::
 600
 601  <roundup source>/roundup/templates/<template>/html/default.css
 602
 603
 604
 605 Migrating from 0.4.0 to 0.4.1
 606 =============================
 607
 608 0.4.1 Files storage
 609 -------------------
 610
 611 Messages and files from newly created issues will be put into subdierectories
 612 in thousands e.g. msg123 will be put into files/msg/0/msg123, file2003
 613 will go into files/file/2/file2003. Previous messages are still found, but
 614 could be put into this structure.
 615
 616 0.4.1 Configuration
 617 -------------------
 618
 619 To allow more fine-grained access control, the variable used to check
 620 permission to auto-register users in the mail gateway is now called
 621 ANONYMOUS_REGISTER_MAIL rather than overloading ANONYMOUS_REGISTER. If the
 622 variable doesn't exist, then ANONYMOUS_REGISTER is tested as before.
 623
 624 Configuring the links in the web header is now easier too. The following
 625 variables have been added to the classic instance_config.py::
 626
 627   HEADER_INDEX_LINKS   - defines the "index" links to be made available
 628   HEADER_ADD_LINKS     - defines the "add" links
 629   DEFAULT_INDEX        - specifies the index view for DEFAULT
 630   UNASSIGNED_INDEX     - specifies the index view for UNASSIGNED
 631   USER_INDEX           - specifies the index view for USER
 632
 633 See the <roundup source>/roundup/templates/classic/instance_config.py for more
 634 information - including how the variables are to be set up. Most users will
 635 just be able to copy the variables from the source to their instance home. If
 636 you've modified the header by changing the source of the interfaces.py file in
 637 the instance home, you'll need to remove that customisation and move it into
 638 the appropriate variables in instance_config.py.
 639
 640 The extended schema has similar variables added too - see the source for more
 641 info.
 642
 643 0.4.1 Alternate E-Mail Addresses
 644 --------------------------------
 645
 646 If you add the property "alternate_addresses" to your user class, your users
 647 will be able to register alternate email addresses that they may use to
 648 communicate with roundup as. All email from roundup will continue to be sent
 649 to their primary address.
 650
 651 If you have not edited the dbinit.py file in your instance home directory,
 652 you may simply copy the new dbinit.py file from the core code. If you used
 653 the classic schema, the interfaces file is in::
 654
 655  <roundup source>/roundup/templates/classic/dbinit.py
 656
 657 If you used the extended schema, the file is in::
 658
 659  <roundup source>/roundup/templates/extended/dbinit.py
 660
 661 If you have modified your dbinit.py file, you need to edit the dbinit.py
 662 file in your instance home directory. Find the lines which define the user
 663 class::
 664
 665     user = Class(db, "msg",
 666                     username=String(),   password=Password(),
 667                     address=String(),    realname=String(),
 668                     phone=String(),      organisation=String(),
 669                     alternate_addresses=String())
 670
 671 You will also want to add the property to the user's details page. The
 672 template for this is the "user.item" file in your instance home "html"
 673 directory. Similar to above, you may copy the file from the roundup source if
 674 you haven't modified it. Otherwise, add the following to the template::
 675
 676    <display call="multiline('alternate_addresses')">
 677
 678 with appropriate labelling etc. See the standard template for an idea.
 679
 680
 681
 682 Migrating from 0.3.x to 0.4.0
 683 =============================
 684
 685 0.4.0 Message-ID and In-Reply-To addition
 686 -----------------------------------------
 687 0.4.0 adds the tracking of messages by message-id and allows threading
 688 using in-reply-to. Most e-mail clients support threading using this
 689 feature, and we hope to add support for it to the web gateway. If you
 690 have not edited the dbinit.py file in your instance home directory, you may
 691 simply copy the new dbinit.py file from the core code. If you used the
 692 classic schema, the interfaces file is in::
 693
 694  <roundup source>/roundup/templates/classic/dbinit.py
 695
 696 If you used the extended schema, the file is in::
 697
 698  <roundup source>/roundup/templates/extended/dbinit.py
 699
 700 If you have modified your dbinit.py file, you need to edit the dbinit.py
 701 file in your instance home directory. Find the lines which define the msg
 702 class::
 703
 704     msg = FileClass(db, "msg",
 705                     author=Link("user"), recipients=Multilink("user"),
 706                     date=Date(),         summary=String(),
 707                     files=Multilink("file"))
 708
 709 and add the messageid and inreplyto properties like so::
 710
 711     msg = FileClass(db, "msg",
 712                     author=Link("user"), recipients=Multilink("user"),
 713                     date=Date(),         summary=String(),
 714                     files=Multilink("file"),
 715                     messageid=String(),  inreplyto=String())
 716
 717 Also, configuration is being cleaned up. This means that your dbinit.py will
 718 also need to be changed in the open function. If you haven't changed your
 719 dbinit.py, the above copy will be enough. If you have, you'll need to change
 720 the line (round line 50)::
 721
 722     db = Database(instance_config.DATABASE, name)
 723
 724 to::
 725
 726     db = Database(instance_config, name)
 727
 728
 729 0.4.0 Configuration
 730 --------------------
 731 ``TRACKER_NAME`` and ``EMAIL_SIGNATURE_POSITION`` have been added to the
 732 instance_config.py. The simplest solution is to copy the default values
 733 from template in the core source.
 734
 735 The mail gateway now checks ``ANONYMOUS_REGISTER`` to see if unknown users
 736 are to be automatically registered with the tracker. If it is set to "deny"
 737 then unknown users will not have access. If it is set to "allow" they will be
 738 automatically registered with the tracker.
 739
 740
 741 0.4.0 CGI script roundup.cgi
 742 ----------------------------
 743 The CGI script has been updated with some features and a bugfix, so you should
 744 copy it from the roundup cgi-bin source directory again. Make sure you update
 745 the ROUNDUP_INSTANCE_HOMES after the copy.
 746
 747
 748 0.4.0 Nosy reactor
 749 ------------------
 750 The nosy reactor has also changed - copy the nosyreactor.py file from the core
 751 source::
 752
 753    <roundup source>/roundup/templates/<template>/detectors/nosyreactor.py
 754
 755 to your instance home "detectors" directory.
 756
 757
 758 0.4.0 HTML templating
 759 ---------------------
 760 The field() function was incorrectly implemented - links and multilinks now
 761 display as text fields when rendered using field(). To display a menu (drop-
 762 down or select box) you need to use the menu() function.
 763
 764
 765
 766 Migrating from 0.2.x to 0.3.x
 767 =============================
 768
 769 0.3.x Cookie Authentication changes
 770 -----------------------------------
 771 0.3.0 introduces cookie authentication - you will need to copy the
 772 interfaces.py file from the roundup source to your instance home to enable
 773 authentication. If you used the classic schema, the interfaces file is in::
 774
 775  <roundup source>/roundup/templates/classic/interfaces.py
 776
 777 If you used the extended schema, the file is in::
 778
 779  <roundup source>/roundup/templates/extended/interfaces.py
 780
 781 If you have modified your interfaces.Client class, you will need to take
 782 note of the login/logout functionality provided in roundup.cgi_client.Client
 783 (classic schema) or roundup.cgi_client.ExtendedClient (extended schema) and
 784 modify your instance code apropriately.
 785
 786
 787 0.3.x Password encoding
 788 -----------------------
 789 This release also introduces encoding of passwords in the database. If you
 790 have not edited the dbinit.py file in your instance home directory, you may
 791 simply copy the new dbinit.py file from the core code. If you used the
 792 classic schema, the interfaces file is in::
 793
 794  <roundup source>/roundup/templates/classic/dbinit.py
 795
 796 If you used the extended schema, the file is in::
 797
 798  <roundup source>/roundup/templates/extended/dbinit.py
 799
 800
 801 If you have modified your dbinit.py file, you may use encoded passwords:
 802
 803 1. Edit the dbinit.py file in your instance home directory
 804    a. At the first code line of the open() function::
 805
 806        from roundup.hyperdb import String, Date, Link, Multilink
 807
 808       alter to include Password, as so::
 809
 810        from roundup.hyperdb import String, Password, Date, Link, Multilink
 811
 812    b. Where the password property is defined (around line 66)::
 813
 814        user = Class(db, "user",
 815                        username=String(),   password=String(),
 816                        address=String(),    realname=String(),
 817                        phone=String(),      organisation=String())
 818        user.setkey("username")
 819
 820       alter the "password=String()" to "password=Password()"::
 821
 822        user = Class(db, "user",
 823                        username=String(),   password=Password(),
 824                        address=String(),    realname=String(),
 825                        phone=String(),      organisation=String())
 826        user.setkey("username")
 827
 828 2. Any existing passwords in the database will remain cleartext until they
 829    are edited. It is recommended that at a minimum the admin password be
 830    changed immediately::
 831
 832       roundup-admin -i <instance home> set user1 password=<new password>
 833
 834
 835 0.3.x Configuration
 836 -------------------
 837 FILTER_POSITION, ANONYMOUS_ACCESS, ANONYMOUS_REGISTER have been added to
 838 the instance_config.py. Simplest solution is to copy the default values from
 839 template in the core source.
 840
 841 MESSAGES_TO_AUTHOR has been added to the IssueClass in dbinit.py. Set to 'yes'
 842 to send nosy messages to the author. Default behaviour is to not send nosy
 843 messages to the author. You will need to add MESSAGES_TO_AUTHOR to your
 844 dbinit.py in your instance home.
 845
 846
 847 0.3.x CGI script roundup.cgi
 848 ----------------------------
 849 There have been some structural changes to the roundup.cgi script - you will
 850 need to install it again from the cgi-bin directory of the source
 851 distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the
 852 copy.
 853
 854
 855 .. _`customisation documentation`: customizing.html
 856 .. _`security documentation`: security.html