|
|
|
TWiki Upgrade GuideThis guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.1_OverviewTWiki-4.0.0 was a major new release. TWiki-4.1.0 is a minor release without dramatic changes since 4.0.0Upgrade Requirements
Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0See TWikiReleaseNotes04x00 and TWikiReleaseNotes04x01Upgrade ProcedureThe following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release. The main steps are:
Installation
Install Extensions
Copy your old webs to new TWiki
Copy Users And Their Topics From Main Web
Apply Customizations To The Skin
Apply Preferences From Old Installation
Upgrading from Cairo to TWiki4 (additional advice)FaviconTWiki4's PatternSkin introduces the use of the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks. In TWiki4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki4 you do not have this file and you will get flooded with errors the error log of your web server. There are two solutions to this.
* Set FAVICON = %PUBURLPATH%/%TWIKIWEB%/%WEBPREFSTOPIC%/favicon.ico TWikiUsers topic in Main webYour Cairo Main.TWikiUsers topic will work in TWiki4 but you will need to ensure that these 4 users from the default TWiki4 version of TWikiUsers are copied to the existing TWikiUsers topic. TWikiGuest is probably already there but the others are new
Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent. Otherwise people will not be able to register.
Important Changes since 4.0.5Supported Perl versionTWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately TWiki 4.1.0 does not support Perl versions older then 5.8.0. It is the goal that TWiki should work on at least Perl version 5.6.X but none of the developers have had access to Perl installations older than 5.8.0. Since TWiki 4.1.0 has some urgent bugs the development team decided to release TWiki 4.1.1 without resolving the issue with Perl 5.6.X. We will however address this and try and resolve it for a planned 4.1.2 release. The TWiki community is very interested in contributions from users that have fixes for the code which will enable TWiki to run on older versions of Perl. See the WhatVersionsOfPerlAreSupported topic to keep up to date with the discussion how to get back support for earlier Perl versions.Template spec changedUntil TWiki 4.0.5 TWikiTemplates the text inside template definition blocks (anything between %TMPL:DEF{"block"}% and %TMPL:END% was stripped of leading and trailing white space incl new lines. This caused a lot of problems for skin developers when you wanted a newline before or after the block text. From TWiki 4.1.0 this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments. It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}% needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF. The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%
|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>
From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>
The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
Important Changes since 4.1.0New location for session filesAn upgrader upgrading to 4.1.1 should note the following important change The directory for passthrough files and session files have been replaced by a common directory for temporary files used by TWiki. Previously the two configure settings{PassthroughDir} and {Sessions}{Dir} were by default set to /tmp. These config settings have been replaced by {TempfileDir} with the default setting value /tmp/twiki. If the twiki directory does not exist twiki will create it first time it needs it.
It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the {TempfileDir} for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.
Related Topics: AdminDocumentationCategory, TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix |
|
Hint: For an easier upgrade later on, set the plugin preferences settings in the 
