The Caboteria / TWiki Web / TWikiUpgradeGuide (29 Feb 2012, TWikiContributor)

TWiki Upgrade Guide

This guide covers upgrading from a previous version of TWiki (such as TWiki-4.3) to TWiki-5.1

Overview

TWiki-5.1 is a minor release introducing mostly usability enhancements, feature enhancements, and adds extensions to strengthen TWiki as an enterprise collaboration platform. Use this guide to upgrade a previous TWiki release to TWiki-5.1. Use the TWikiInstallationGuide if you do not have data to carry forward.

Upgrade Requirements

Major Changes Compared to Earlier TWiki Releases

See TWikiReleaseNotes04x00, TWikiReleaseNotes04x01, TWikiReleaseNotes04x02, TWikiReleaseNotes04x03, TWikiReleaseNotes05x00 and TWikiReleaseNotes05x01

New Upgrade Option with BackupRestorePlugin

TWiki now has a new solution to backup, restore and upgrade TWiki sites. It can be used via browser and on the command line. The BackupRestorePlugin is pre-installed in TWiki-5.1 and later releases; it can be installed in older TWiki releases as low as TWiki-2001-09-01 (Athens Release) to easily create a backup that can be restored on a new TWiki release. This offers an easy upgrade path for TWiki. The plugin is currently in Beta, check TWiki:Plugins.BackupRestorePlugin for updates.

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 including all their topics from Main
  5. Apply customizations to your skin (logos, menu bars etc)
  6. Apply preferences from old installation

TIP After the extensions are installed (or upgraded) in step 2, take a "golden" backup. That will come in handy for your next patch or upgrade: By checking the differences between the golden copy and your production copy, you will be able to identify all the modifications that you have applied to the core or extensions.

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

Customization of Special Pages

Some pages in the TWiki web are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the TWiki web with the tailored versions from your old installation. The topics are:

Upgrading from Cairo to TWiki-4 (additional advice)

Favicon

TWiki-4'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 TWiki-4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki-4 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.

To change the location of favicon.ico in TWikiPreferences to the TWiki web add the following setting to Main.TWikiPreferences:

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

TWikiUsers topic in Main web

Your old Main.TWikiUsers topic will work in the new TWiki but you will need to ensure that the following four users from the TWikiUsersTemplate topic are copied to the existing TWikiUsers topic in proper alphabetical order:

   * TWikiContributor - 2005-01-01
   * TWikiGuest - guest - 1999-02-10
   * TWikiRegistrationAgent - 2005-01-01
   * UnknownUser - 2005-01-01

What these users are:

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

Important Changes since TWiki-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 TWiki-4.1.0

New location for session and other temporary 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.

Important Changes since TWiki-4.1.2

New WYSIWYG Editor

TWiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.
TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor

The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less TWiki Applications are negatively affected by editing WYSIWYG

When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way

The WYSIWYG button has been removed.

NEWTOPICLINKSYMBOL removed

The NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.

UserForm and NewUserTemplate Customization

When a new user registers on TWiki his user topic is created based on the NewUserTemplate and UserForm.

The NewUserTemplate was located in the TWiki web and the UserForm in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.

From 4.2.0 the UserForm and NewUserTemplate are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.

TWikiUsers no longer distributed

The Main.TWikiUsers topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.

From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the Main.TWikiUsers topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important TWikiUsers topic.

New working directory

A new directory working which per default is located in the twiki root, has been introduced which contains:

Note: Remember to restrict access to this new directory when you upgrade.

The configuration setting {WorkingDir} defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working under your installation root.

Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*.

New Internal Admin Login

TWiki 4.2 introduces a new Internal Admin Login feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.TWikiAdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the TWikiAdminGroup topic and on TWikiAdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.

Important Changes since TWiki-5.0.0

New TopMenuSkin

The TopMenuSkin adds pulldown menus for better usability and corporate/modern look&feel. This skin is based on the PatternSkin, which used the WebLeftBar in each web for navigation. The TopMenuSkin has a new WebTopBar that defines the menu structure in each web. A default menu is shown in case WebTopBar is missing in a web, so you do not need to add a WebTopBar topic to all your existing webs. See TopMenuSkin#WebSpecific instructions in case you need a customized menu structure in a specific web.

Important Changes since TWiki-5.1.0

New Page Bookmarks Feature

A new bookmark feature has been introduced that replaces the personal left-bar links. Bookmarking a page is now a simple point and click operation: In the Account pulldown menu, select "Bookmark this page...". Existing bookmarks can be managed with an edit table in Main.<wikiname>Bookmarks topic, accessible via the "----- Bookmarks -----" pulldown menu of the Account pulldown.

The personal left-bar topics such as JohnSmithLeftBar are no longer used. Ask users to select the "----- Bookmarks -----" pulldown menu of the Account pulldown to initially create the bookmarks topic, then to either bookmark pages, or to manually copy & paste old left-bar links to the bookmarks topic.

User Profile Pages Tailored for Workplace

Previous user profile pages had a bare bone look and the form fields were more tailored for public TWiki sites. TWiki-5.1 brings a more visual/modern page layout with profile picture selector, as well as default form fields tailored for the workplace.

Changes to the TWiki.UserForm:

Renamed:

Removed: Added:

When upgrading user profile pages pay attention to the renamed and removed fields.

Related Topics: AdminDocumentationCategory, TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix

Contributors: TWiki:Main.PeterThoeny, TWiki:Main.KennethLavrsen, TWiki:Main.CrawfordCurrie, TWiki:Main.HaraldJoerg, TWiki:Main.BobBagwill

Edit | Attach | Print version | History: r13 < r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding The Caboteria? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiUpgradeGuide.