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 The USER_INDEX definition introduced in 0.4.1 was too restrictive in its
  30 allowing replacement of 'assignedto' with the user's userid. Users must change
  31 the None value of 'assignedto' to 'CURRENT USER' (the string, in quotes) for
  32 the replacement behaviour to occur now.
  33
  34
  35 Migrating from 0.4.0 to 0.4.1
  36 =============================
  37
  38 Configuration
  39 -------------
  40
  41 To allow more fine-grained access control, the variable used to check
  42 permission to auto-register users in the mail gateway is now called
  43 ANONYMOUS_REGISTER_MAIL rather than overloading ANONYMOUS_REGISTER. If the
  44 variable doesn't exist, then ANONYMOUS_REGISTER is tested as before.
  45
  46 Configuring the links in the web header is now easier too. The following
  47 variables have been added to the classic instance_config.py:
  48
  49   HEADER_INDEX_LINKS   - defines the "index" links to be made available
  50   HEADER_ADD_LINKS     - defines the "add" links
  51   DEFAULT_INDEX        - specifies the index view for DEFAULT
  52   UNASSIGNED_INDEX     - specifies the index view for UNASSIGNED
  53   USER_INDEX           - specifies the index view for USER
  54
  55 See the <roundup source>/roundup/templates/classic/instance_config.py for more
  56 information - including how the variables are to be set up. Most users will
  57 just be able to copy the variables from the source to their instance home. If
  58 you've modified the header by changing the source of the interfaces.py file in
  59 the instance home, you'll need to remove that customisation and move it into
  60 the appropriate variables in instance_config.py.
  61
  62 The extended schema has similar variables added too - see the source for more
  63 info.
  64
  65
  66
  67 Alternate E-Mail Addresses
  68 --------------------------
  69
  70 If you add the property "alternate_addresses" to your user class, your users
  71 will be able to register alternate email addresses that they may use to
  72 communicate with roundup as. All email from roundup will continue to be sent
  73 to their primary address.
  74
  75 If you have not edited the dbinit.py file in your instance home directory,
  76 you may simply copy the new dbinit.py file from the core code. If you used
  77 the classic schema, the interfaces file is in:
  78
  79  <roundup source>/roundup/templates/classic/dbinit.py
  80
  81 If you used the extended schema, the file is in:
  82
  83  <roundup source>/roundup/templates/extended/dbinit.py
  84
  85 If you have modified your dbinit.py file, you need to edit the dbinit.py
  86 file in your instance home directory. Find the lines which define the user
  87 class:
  88
  89     user = Class(db, "msg",
  90                     username=String(),   password=Password(),
  91                     address=String(),    realname=String(),
  92                     phone=String(),      organisation=String(),
  93                     alternate_addresses=String())
  94
  95 You will also want to add the property to the user's details page. The
  96 template for this is the "user.item" file in your instance home "html"
  97 directory. Similar to above, you may copy the file from the roundup source if
  98 you haven't modified it. Otherwise, add the following to the template:
  99
 100    <display call="multiline('alternate_addresses')">
 101
 102 with appropriate labelling etc. See the standard template for an idea.
 103
 104
 105
 106 Migrating from 0.3.x to 0.4.x
 107 =============================
 108
 109 Message-ID and In-Reply-To addition
 110 -----------------------------------
 111 0.4.0 adds the tracking of messages by message-id and allows threading
 112 using in-reply-to. Most e-mail clients support threading using this
 113 feature, and we hope to add support for it to the web gateway. If you
 114 have not edited the dbinit.py file in your instance home directory, you may
 115 simply copy the new dbinit.py file from the core code. If you used the
 116 classic schema, the interfaces file is in:
 117
 118  <roundup source>/roundup/templates/classic/dbinit.py
 119
 120 If you used the extended schema, the file is in:
 121
 122  <roundup source>/roundup/templates/extended/dbinit.py
 123
 124 If you have modified your dbinit.py file, you need to edit the dbinit.py
 125 file in your instance home directory. Find the lines which define the msg
 126 class:
 127
 128     msg = FileClass(db, "msg",
 129                     author=Link("user"), recipients=Multilink("user"),
 130                     date=Date(),         summary=String(),
 131                     files=Multilink("file"))
 132
 133  and add the messageid and inreplyto properties like so:
 134
 135     msg = FileClass(db, "msg",
 136                     author=Link("user"), recipients=Multilink("user"),
 137                     date=Date(),         summary=String(),
 138                     files=Multilink("file"),
 139                     messageid=String(),  inreplyto=String())
 140
 141 Also, configuration is being cleaned up. This means that your dbinit.py will
 142 also need to be changed in the open function. If you haven't changed your
 143 dbinit.py, the above copy will be enough. If you have, you'll need to change
 144 the line (round line 50):
 145
 146     db = Database(instance_config.DATABASE, name)
 147
 148 to:
 149
 150     db = Database(instance_config, name)
 151
 152
 153 Configuration
 154 -------------
 155 INSTANCE_NAME and EMAIL_SIGNATURE_POSITION have been added to the
 156 instance_config.py. The simplest solution is to copy the default values
 157 from template in the core source.
 158
 159 The mail gateway now checks ANONYMOUS_REGISTER to see if unknown users are to
 160 be automatically registered with the tracker. If it is set to "deny" then
 161 unknown users will not have access. If it is set to "allow" they will be
 162 automatically registered with the tracker.
 163
 164
 165 CGI script roundup.cgi
 166 ----------------------
 167 The CGI script has been updated with some features and a bugfix, so you should
 168 copy it from the roundup cgi-bin source directory again. Make sure you update
 169 the ROUNDUP_INSTANCE_HOMES after the copy.
 170
 171
 172 Nosy reactor
 173 ------------
 174 The nosy reactor has also changed - copy the nosyreactor.py file from the core
 175 source roundup/templates/[schema]/detectors/nosyreactor.py to your instance
 176 home "detectors" directory.
 177
 178
 179 HTML templating
 180 ---------------
 181 The field() function was incorrectly implemented - links and multilinks now
 182 display as text fields when rendered using field(). To display a menu (drop-
 183 down or select box) you need to use the menu() function.
 184
 185
 186
 187 Migrating from 0.2.x to 0.3.x
 188 =============================
 189
 190 Cookie Authentication changes
 191 -----------------------------
 192 0.3.0 introduces cookie authentication - you will need to copy the
 193 interfaces.py file from the roundup source to your instance home to enable
 194 authentication. If you used the classic schema, the interfaces file is in:
 195
 196  <roundup source>/roundup/templates/classic/interfaces.py
 197
 198 If you used the extended schema, the file is in:
 199
 200  <roundup source>/roundup/templates/extended/interfaces.py
 201
 202 If you have modified your interfaces.Client class, you will need to take
 203 note of the login/logout functionality provided in roundup.cgi_client.Client
 204 (classic schema) or roundup.cgi_client.ExtendedClient (extended schema) and
 205 modify your instance code apropriately.
 206
 207
 208 Password encoding
 209 -----------------
 210 This release also introduces encoding of passwords in the database. If you
 211 have not edited the dbinit.py file in your instance home directory, you may
 212 simply copy the new dbinit.py file from the core code. If you used the
 213 classic schema, the interfaces file is in:
 214
 215  <roundup source>/roundup/templates/classic/dbinit.py
 216
 217 If you used the extended schema, the file is in:
 218
 219  <roundup source>/roundup/templates/extended/dbinit.py
 220
 221
 222 If you have modified your dbinit.py file, you may use encoded passwords:
 223
 224  1. Edit the dbinit.py file in your instance home directory
 225  1a. At the first code line of the open() function:
 226
 227     from roundup.hyperdb import String, Date, Link, Multilink
 228
 229       alter to include Password, as so:
 230
 231     from roundup.hyperdb import String, Password, Date, Link, Multilink
 232
 233  1b. Where the password property is defined (around line 66):
 234
 235     user = Class(db, "user",
 236                     username=String(),   password=String(),
 237                     address=String(),    realname=String(),
 238                     phone=String(),      organisation=String())
 239     user.setkey("username")
 240
 241       alter the "password=String()" to "password=Password()":
 242
 243     user = Class(db, "user",
 244                     username=String(),   password=Password(),
 245                     address=String(),    realname=String(),
 246                     phone=String(),      organisation=String())
 247     user.setkey("username")
 248
 249  2. Any existing passwords in the database will remain cleartext until they
 250     are edited. It is recommended that at a minimum the admin password be
 251     changed immediately:
 252
 253       roundup-admin -i <instance home> set user1 password=<new password>
 254
 255
 256 Configuration
 257 -------------
 258 FILTER_POSITION, ANONYMOUS_ACCESS, ANONYMOUS_REGISTER have been added to
 259 the instance_config.py. Simplest solution is to copy the default values from
 260 template in the core source.
 261
 262 MESSAGES_TO_AUTHOR has been added to the IssueClass in dbinit.py. Set to 'yes'
 263 to send nosy messages to the author. Default behaviour is to not send nosy
 264 messages to the author. You will need to add MESSAGES_TO_AUTHOR to your
 265 dbinit.py in your instance home.
 266
 267
 268 CGI script roundup.cgi
 269 ----------------------
 270 There have been some structural changes to the roundup.cgi script - you will
 271 need to install it again from the cgi-bin directory of the source
 272 distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the
 273 copy.
 274
 275
 276