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