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