TWiki Upgrade Guide

This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.1_

Overview

TWiki-4.0.0 was a major new release. TWiki-4.1.0 is a minor release without dramatic changes since 4.0.0

Upgrade Requirements

• Please review the AdminSkillsAssumptions before you upgrade TWiki
• Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
• To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
• To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.X Production Release, follow the instructions below
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
• Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with 4.X. Make sure the Plugins you use can be upgraded as well!

Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0

See TWikiReleaseNotes04x00 and TWikiReleaseNotes04x01

Upgrade Procedure

The 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:

1. Install the new TWiki version, configure it, and get it to work similar to the old version
2. Install additional extensions (Plugins). Make sure to use the latest versions
3. Copy all the non-default webs from the old installation to the new
4. Copy the users from old installation to the new incl all their topics from Main
5. Apply tailorings to your Skin (logos, menu bars etc)
6. Apply preferences from old installation

Installation

• Follow the installation instructions in INSTALL.html which you find in the root of the new installation. Install the new release in a new directory. Do not install on top of the old release.
• Use the configure script to configure TWiki.
  • If you are upgrading from a 4.0.x release, carry over the configure settings from the old release.
• Additional resources
  • TWiki:TWiki.UpgradingTWiki04x00PatchReleases
  • TWiki:TWiki.InstallingTWiki#OtherPlatforms
  • TWiki:TWiki.ApacheConfigGenerator
  • TWiki:TWiki.SettingFileAccessRightsLinuxUnix
  • Your lib/TWiki.cfg from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
• Make sure you have a working basic TWiki before you continue

Install Extensions

• Note that not all extensions that worked in Cairo have been updated to work with TWiki4.X. Many Cairo plugins work fine. Some do not. Many plugins have been upgraded to work with TWiki4.0 and later.
• From TWiki-4.1.0 the configure script which you ran during installation supports installation of additional plugins.
• Manual installation is possible. Follow the instruction on the Plugin page at twiki.org.
• Check the plugin topics from your old TWiki installation. There may be plugin settings that you want to transfer to the new TWiki installation.
  Hint: For an easier upgrade later on, set the plugin preferences settings in the Main.TWikiPreferences topic, not in the plugin topic. To identify the plugin, prefix the name of the setting with the capitalized name of the plugin. For example, to change the DEFAULT_TYPE setting of the CommentPlugin, create a COMMENTPLUGIN_DEFAULT_TYPE setting in Main.TWikiPreferences.
• Typical plugin settings you may have altered.
  • CommentPlugin - Set DEFAULT_TYPE
  • EditTablePlugin - Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
  • InterwikiPlugin - Set RULESTOPIC
  • InterWikis - If you added your own rules you should save this topic and not overwrite it.
  • SlideShowPlugin - Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
  • SmiliesPlugin - Did you add your own smileys? No smileys were added 4.0.0 and 4.0.2 so you can just leave this topic as it is.
  • TablePlugin - Set TABLEATTRIBUTES
• Remember that a plugin must be activated in configure.

Copy your old webs to new TWiki

• When upgrading from Cairo or earlier it may be necessary to unlock the rcs files in data and pub directories from the old installation using the following shell commands:
  • find data -name '*,v' -exec rcs -u -M '{}' \;
  • find pub -name '*,v' -exec rcs -u -M '{}' \;
• Copy your local webs over to the data and pub directories of the new install. Do not copy the default webs: TWiki, Main, Trash, Sandbox, _default, and _empty.

Copy Users And Their Topics From Main Web

• Copy all the topics from the Main web and corresponding pub/Main directories from the old TWiki to the new TWiki but do not overwrite any of the new topics already inside the new Main directory!
• Manually merge all the users from the old TWiki.TWikiUsers topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic.
• If you use data/.htpasswd for authentication copy this file from the old TWiki to the new.
  • If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.
• The old sandbox web may have a lot of useful topic and users may use it actively for drafts. Manually select the topics (remember the corresponding pub directories) from the old Sandbox web and copy them to the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.

Apply Customizations To The Skin

• Not many of the old Cairo skins work well with TWiki4.X.
• Add Logos, update top bar and left bar as required.
• Apply any desired changes to style sheets and templates. The default PatternSkin has been totally rewritten since Cairo and once more in 4.0.2. Since then changes to PatternSkin have been minor and you may be able to carry over most simpler tailorings directly from 4.0.2-4.0.5.
• Additional resources:
  • TWiki:TWiki.UpgradingTWiki04x00PatchReleases
  • PatternSkinCustomization
  • PatternSkinCssCookbook

Apply Preferences From Old Installation

• Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). Per default this is Main.TWikiPreferences. This avoids having to write over files in the distribution on a later upgrade.
• If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the data/TWiki of the old and new TWiki installation, and transfer the changes into the new TWiki install.
• Compare the WebPreferences topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
• Compare the WebLeftBar topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.

Upgrading from Cairo to TWiki4 (additional advice)

Favicon

TWiki4'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.

• Attach a favicon.ico file to WebPreferences in each web.
• Preferred: Change the setting of the location of favicon.ico in TWikiPreferences so all webs use the favicon.ico from the TWiki web. This is the fastest and easiest solution.

To change the location of favicon.ico in TWikiPreferences to the TWiki web add this line to TWikiPreferences

   * Set FAVICON = %PUBURLPATH%/%TWIKIWEB%/%WEBPREFSTOPIC%/favicon.ico

TWikiUsers topic in Main web

Your 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

• TWikiContributor - placeholder for a TWiki developer, and is used in TWiki documentation
• TWikiGuest - guest user, used as a fallback if the user can't be identified
• TWikiRegistrationAgent - special user used during the new user registration process
• UnknownUser - used where the author of a previously stored piece of data can't be determined

You additionally need to ensure that TWikiUsers has the Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent. Otherwise people will not be able to register.

Important Changes since 4.0.5

Supported Perl version

TWiki 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 changed

Until 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.0

New location for session files

An 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