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