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