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