doc/upgrading.txt

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