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