MIGRATION.txt

   1 Migrating to newer versions of Roundup
   2 ======================================
   3
   4 Please read each section carefully and edit your instance home files
   5 accordingly.
   6
   7 This file contains information for users upgrading from:
   8   0.4.0 -> 0.4.1
   9   0.3.x -> 0.4.x
  10   0.2.x -> 0.3.x
  11
  12 From CVS
  13 ========
  14
  15 Files storage
  16 -------------
  17
  18 Messages and files from newly created issues will be put into subdierectories
  19 in thousands e.g. msg123 will be put into files/msg/0/msg123, file2003
  20 will go into files/file/2/file2003. Previous messages are still found, but
  21 could be put into this structure.
  22
  23 Migrating from 0.4.0 to 0.4.1
  24 =============================
  25
  26 Configuration
  27 -------------
  28
  29 To allow more fine-grained access control, the variable used to check
  30 permission to auto-register users in the mail gateway is now called
  31 ANONYMOUS_REGISTER_MAIL rather than overloading ANONYMOUS_REGISTER. If the
  32 variable doesn't exist, then ANONYMOUS_REGISTER is tested as before.
  33
  34
  35 Alternate E-Mail Addresses
  36 --------------------------
  37
  38 If you add the property "alternate_addresses" to your user class, your users
  39 will be able to register alternate email addresses that they may use to
  40 communicate with roundup as. All email from roundup will continue to be sent
  41 to their primary address.
  42
  43 If you have not edited the dbinit.py file in your instance home directory,
  44 you may simply copy the new dbinit.py file from the core code. If you used
  45 the classic schema, the interfaces file is in:
  46
  47  <roundup source>/roundup/templates/classic/dbinit.py
  48
  49 If you used the extended schema, the file is in:
  50
  51  <roundup source>/roundup/templates/extended/dbinit.py
  52
  53 If you have modified your dbinit.py file, you need to edit the dbinit.py
  54 file in your instance home directory. Find the lines which define the user
  55 class:
  56
  57     user = Class(db, "msg",
  58                     username=String(),   password=Password(),
  59                     address=String(),    realname=String(),
  60                     phone=String(),      organisation=String(),
  61                     alternate_addresses=String())
  62
  63 You will also want to add the property to the user's details page. The
  64 template for this is the "user.item" file in your instance home "html"
  65 directory. Similar to above, you may copy the file from the roundup source if
  66 you haven't modified it. Otherwise, add the following to the template:
  67
  68    <display call="multiline('alternate_addresses')">
  69
  70 with appropriate labelling etc. See the standard template for an idea.
  71
  72
  73
  74 Migrating from 0.3.x to 0.4.x
  75 =============================
  76
  77 Message-ID and In-Reply-To addition
  78 -----------------------------------
  79 0.4.0 adds the tracking of messages by message-id and allows threading
  80 using in-reply-to. Most e-mail clients support threading using this
  81 feature, and we hope to add support for it to the web gateway. If you
  82 have not edited the dbinit.py file in your instance home directory, you may
  83 simply copy the new dbinit.py file from the core code. If you used the
  84 classic schema, the interfaces file is in:
  85
  86  <roundup source>/roundup/templates/classic/dbinit.py
  87
  88 If you used the extended schema, the file is in:
  89
  90  <roundup source>/roundup/templates/extended/dbinit.py
  91
  92 If you have modified your dbinit.py file, you need to edit the dbinit.py
  93 file in your instance home directory. Find the lines which define the msg
  94 class:
  95
  96     msg = FileClass(db, "msg",
  97                     author=Link("user"), recipients=Multilink("user"),
  98                     date=Date(),         summary=String(),
  99                     files=Multilink("file"))
 100
 101  and add the messageid and inreplyto properties like so:
 102
 103     msg = FileClass(db, "msg",
 104                     author=Link("user"), recipients=Multilink("user"),
 105                     date=Date(),         summary=String(),
 106                     files=Multilink("file"),
 107                     messageid=String(),  inreplyto=String())
 108
 109 Also, configuration is being cleaned up. This means that your dbinit.py will
 110 also need to be changed in the open function. If you haven't changed your
 111 dbinit.py, the above copy will be enough. If you have, you'll need to change
 112 the line (round line 50):
 113
 114     db = Database(instance_config.DATABASE, name)
 115
 116 to:
 117
 118     db = Database(instance_config, name)
 119
 120
 121 Configuration
 122 -------------
 123 INSTANCE_NAME and EMAIL_SIGNATURE_POSITION have been added to the
 124 instance_config.py. The simplest solution is to copy the default values
 125 from template in the core source.
 126
 127 The mail gateway now checks ANONYMOUS_REGISTER to see if unknown users are to
 128 be automatically registered with the tracker. If it is set to "deny" then
 129 unknown users will not have access. If it is set to "allow" they will be
 130 automatically registered with the tracker.
 131
 132
 133 CGI script roundup.cgi
 134 ----------------------
 135 The CGI script has been updated with some features and a bugfix, so you should
 136 copy it from the roundup cgi-bin source directory again. Make sure you update
 137 the ROUNDUP_INSTANCE_HOMES after the copy.
 138
 139
 140 Nosy reactor
 141 ------------
 142 The nosy reactor has also changed - copy the nosyreactor.py file from the core
 143 source roundup/templates/[schema]/detectors/nosyreactor.py to your instance
 144 home "detectors" directory.
 145
 146
 147 HTML templating
 148 ---------------
 149 The field() function was incorrectly implemented - links and multilinks now
 150 display as text fields when rendered using field(). To display a menu (drop-
 151 down or select box) you need to use the menu() function.
 152
 153
 154
 155 Migrating from 0.2.x to 0.3.x
 156 =============================
 157
 158 Cookie Authentication changes
 159 -----------------------------
 160 0.3.0 introduces cookie authentication - you will need to copy the
 161 interfaces.py file from the roundup source to your instance home to enable
 162 authentication. If you used the classic schema, the interfaces file is in:
 163
 164  <roundup source>/roundup/templates/classic/interfaces.py
 165
 166 If you used the extended schema, the file is in:
 167
 168  <roundup source>/roundup/templates/extended/interfaces.py
 169
 170 If you have modified your interfaces.Client class, you will need to take
 171 note of the login/logout functionality provided in roundup.cgi_client.Client
 172 (classic schema) or roundup.cgi_client.ExtendedClient (extended schema) and
 173 modify your instance code apropriately.
 174
 175
 176 Password encoding
 177 -----------------
 178 This release also introduces encoding of passwords in the database. If you
 179 have not edited the dbinit.py file in your instance home directory, you may
 180 simply copy the new dbinit.py file from the core code. If you used the
 181 classic schema, the interfaces file is in:
 182
 183  <roundup source>/roundup/templates/classic/dbinit.py
 184
 185 If you used the extended schema, the file is in:
 186
 187  <roundup source>/roundup/templates/extended/dbinit.py
 188
 189
 190 If you have modified your dbinit.py file, you may use encoded passwords:
 191
 192  1. Edit the dbinit.py file in your instance home directory
 193  1a. At the first code line of the open() function:
 194
 195     from roundup.hyperdb import String, Date, Link, Multilink
 196
 197       alter to include Password, as so:
 198
 199     from roundup.hyperdb import String, Password, Date, Link, Multilink
 200
 201  1b. Where the password property is defined (around line 66):
 202
 203     user = Class(db, "user",
 204                     username=String(),   password=String(),
 205                     address=String(),    realname=String(),
 206                     phone=String(),      organisation=String())
 207     user.setkey("username")
 208
 209       alter the "password=String()" to "password=Password()":
 210
 211     user = Class(db, "user",
 212                     username=String(),   password=Password(),
 213                     address=String(),    realname=String(),
 214                     phone=String(),      organisation=String())
 215     user.setkey("username")
 216
 217  2. Any existing passwords in the database will remain cleartext until they
 218     are edited. It is recommended that at a minimum the admin password be
 219     changed immediately:
 220
 221       roundup-admin -i <instance home> set user1 password=<new password>
 222
 223
 224 Configuration
 225 -------------
 226 FILTER_POSITION, ANONYMOUS_ACCESS, ANONYMOUS_REGISTER have been added to
 227 the instance_config.py. Simplest solution is to copy the default values from
 228 template in the core source.
 229
 230 MESSAGES_TO_AUTHOR has been added to the IssueClass in dbinit.py. Set to 'yes'
 231 to send nosy messages to the author. Default behaviour is to not send nosy
 232 messages to the author. You will need to add MESSAGES_TO_AUTHOR to your
 233 dbinit.py in your instance home.
 234
 235
 236 CGI script roundup.cgi
 237 ----------------------
 238 There have been some structural changes to the roundup.cgi script - you will
 239 need to install it again from the cgi-bin directory of the source
 240 distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the
 241 copy.
 242
 243
 244