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