doc/upgrading.txt

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