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