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