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