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