Overview

Changed:

<<

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.

>>

TWiki-6.0.0 is a major release that has a shiny new dashboard look. It brings many usability enhancements, strengthens TWiki as an application platform, and scales to very large deployments with thousands of webs and a million pages. Use this guide to upgrade a previous TWiki release to TWiki-6.0. Use the TWikiInstallationGuide if you do not have data to carry forward.

To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-5.1 Production Release, follow the instructions below

>>

To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-6.0 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!

Major Changes Compared to Earlier TWiki Releases

Line: 315 to 315

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

Added:

>>

Important Changes since TWiki-6.0.0

Spec Change for Empty DENYTOPICVIEW

From TWiki 4.0 and prior to 6.0, the syntax * Set DENYTOPICVIEW = (nothing) in a topic means deny nobody the topic view. The reason for this behavior is that it allows public access to a topic in a restricted web, e.g. having * Set ALLOWWEBVIEW = Main.VipGroup in WebPreferences. This is not symmetric with the fact that an empty DENYWEBVIEW is the same as an undefined DENYWEBVIEW, hence confusing.

From TWiki 6.0 on, an empty DENYTOPICVIEW means the same as not defined. To open up a topic in a restricted web, you need to use * Set ALLOWTOPICVIEW = Main.AllUsersGroup. The Main.AllUsersGroup is new. It is a pseudo group containing all authenticated and unauthenticated users. You can use Main.AllAuthUsersGroup if you want to specify all authenticated users.

To keep publicly accessible topics in restricted webs publicly accessible, the tools/eliminate_emptydenytopic script is provided, which replaces * Set DENYTOPIC<action> = with * Set ALLOWTOPIC<action> = Main.AllUsersGroup in all topics in all webs.

TWiki Upgrade Guide

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 Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

Added:

>>

If you want users to be able to use a login ID other than their WikiName, such as when using LDAP or SSO authentication, set the configure setting {Register}{AllowLoginName} to 1.

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 file. 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 one of the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.

Line: 228 to 229

New WYSIWYG Editor

Changed:

<<

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

>>

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

Changed:

<<

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

>>

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

Changed:

<<

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

>>

When TinyMCEPlugin is enabled, the Edit button by 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.

Line: 259 to 260

New working directory

Changed:

<<

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

>>

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

registration_approvals - with 4.2.0 it is moved to here from the data directory.

tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.

Line: 267 to 268

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

Changed:

<<

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.

>>

The configure 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*.

Line: 291 to 292

User Profile Pages Tailored for Workplace

Changed:

<<

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.

>>

Previous user profile pages had a bare bones 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.

New Upgrade Option with BackupRestorePlugin

Copy the users from old installation to the new including all their topics from Main

Apply customizations to your skin (logos, menu bars etc)

Apply preferences from old installation

Added:

>>

Switch-over

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.

Line: 112 to 113

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.

Added:

>>

Switch-Over

Once you have tested the new TWiki you can switch over to the new site.

If the same domain and URL is used:

Update the DNS settings of the TWiki domain with the IP address of the new TWiki server.

Keep in mind that the updated DNS is not seen immediately by all users at the same time. The DNS propagation can take several hours and depends on the time to live (TTL) setting. Because of this it is recommended to disable content update on the old server. You could simply rename or move all scripts in twiki/bin that allow content update, such as attach, edit, manage, rename, save, upload, rest. Alternatively, if you have a recent TWiki version on the old server you can set a READONLYSKINMODE = 1 setting in Main.TWikiPreferences to turn the skin into read-only mode.

If the domain or URL changes:

Add a DNS setting for the new TWiki domain if needed.

Redirect users visiting the old TWiki to the new TWiki. The TWiki:Plugins.MovedSkin has been designed for that task. Install it on your old TWiki, and configure it with the proper URL of the new TWiki. After that, users on the old TWiki will see a yellow box informing them of the move, with a link to the new URL of the page visited.

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:

TWiki Upgrade Guide

Line: 25 to 25

New Upgrade Option with BackupRestorePlugin

Changed:

<<

TWiki now as 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.

>>

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

Line: 60 to 60

Install Extensions

Changed:

<<

From TWiki-4.1.0 on the configure script which you ran during installation supports installation of additional plugins.

>>

From TWiki-4.1.0 and on, 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.

Overview

Changed:

<<

TWiki-5.0.0 is a major release introducing 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 5.0. Use the TWikiInstallationGuide if you do not have data to carry forward.

>>

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.

New Upgrade Option with BackupRestorePlugin

TWiki now as 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

Line: 261 to 266

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.

Added:

>>

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.

If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.

You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.

You can also choose to start with a fresh configuration and walk through all the settings using your old twiki/lib/LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.

If at any time during the installation you want to start over from fresh, delete the LocalSite.cfg file and re-run configure.

If you upgrade from an older TWiki 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

Line: 86 to 86

Manually merge all the users from the old Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

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 file. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.

Changed:

<<

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.

>>

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 one of the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.

If you added or removed fields from the user topic form you may also have tailored TWiki.TWikiRegistration. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration topic.

Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly advised to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.

Make sure all data and pub files and directories are owned by the webserver user.

Line: 94 to 94

Apply Customizations To The Skin

Add Logos, update top bar and left bar as required.

Changed:

<<

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.

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.

Changed:

<<

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

>>

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

Line: 134 to 134

TWikiUsers topic in Main web

Changed:

<<

Your Cairo Main.TWikiUsers topic will work in TWiki-4 but you will need to ensure that these 4 users from the default TWiki-4 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

>>

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

Changed:

<<

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

>>

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

Line: 155 to 163

Template spec changed

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.

>>

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.

Changed:

<<

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.

>>

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

Line: 251 to 259

New TopMenuSkin

Changed:

<<

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, 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 web.

>>

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.

Overview

Changed:

<<

TWiki-4.0.0 was a major new release. TWiki-4.1.x, TWiki-4.2.x, TWiki-4.3.x minor releases containing new features that can be seen by the end user, a large number of bug fixes. Use the TWikiInstallationGuide if you do not have data to carry forward.

>>

TWiki-5.0.0 is a major release introducing 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 5.0. Use the TWikiInstallationGuide if you do not have data to carry forward.

Upgrade Procedure

Install the new TWiki version, configure it, and get it to work similar to the old version

Changed:

<<

Install additional extensions (Plugins). Make sure to use the latest versions

>>

Install additional extensions (plugins) -- make sure to use the latest versions

Copy all the non-default webs from the old installation to the new

Changed:

<<

Copy the users from old installation to the new incl all their topics from Main

Apply tailorings to your Skin (logos, menu bars etc)

>>

Copy the users from old installation to the new including all their topics from Main

Apply customizations to your skin (logos, menu bars etc)

Apply preferences from old installation

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

Changed:

<<

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.

If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.

You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.

Changed:

<<

You can also choose to start with a fresh configuration and walk through all the settings using your old LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.

If at any time during the installation you want to start over from fresh all you need to do is delete the lib/LocalSite.cfg file and re-run configure.

>>

You can also choose to start with a fresh configuration and walk through all the settings using your old twiki/lib/LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.

If at any time during the installation you want to start over from fresh, delete the LocalSite.cfg file and re-run configure.

If you upgrade from an older TWiki 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

Changed:

<<

Note that not all extensions that worked in Cairo have been updated to work with TWiki-4.0. Many Cairo plugins work fine. Some do not. Many plugins have been upgraded to work with TWiki-4.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.

>>

From TWiki-4.1.0 on 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.

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.

Changed:

<<

SmiliesPlugin - Did you add your own smileys? No real changes were made to the smilies topic October 2005 so you can just leave this topic as it is.

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 '{}' \;

Line: 88 to 86

Manually merge all the users from the old Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

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 file. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.

Changed:

<<

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.

>>

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.

If you added or removed fields from the user topic form you may also have tailored TWiki.TWikiRegistration. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration topic.

Changed:

<<

Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly adviced to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.

>>

Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly advised to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.

Make sure all data and pub files and directories are owned by the webserver user.

Apply Customizations To The Skin

Deleted:

<<

Not many of the old Cairo skins work well with TWiki-4.0 and later.

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:

Line: 146 to 143

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

Changed:

<<

Important Changes since 4.0.5

>>

Important Changes since TWiki-4.0.5

Supported Perl version

Line: 189 to 186

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.

Changed:

<<

Important Changes since 4.1.0

>>

Important Changes since TWiki-4.1.0

New location for session and other temporary files

Line: 199 to 196

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.

Changed:

<<

Important Changes since 4.1.2

>>

Important Changes since TWiki-4.1.2

New WYSIWYG Editor

Line: 250 to 247

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.

Added:

>>

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, 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 web.

Overview

Changed:

<<

TWiki-4.0.0 was a major new release. TWiki-4.1.0 was a minor release without dramatic changes since 4.0.0. TWiki-4.2.0 is also a minor release containing a few new features that can be seen by the end user, a large number of bug fixes, and a face lift for the skin. It also contains some important updates under the hood to the way users are handled which enables new types of authentication and integration with other systems. The most important new feature is the QuerySearch feature.

>>

TWiki-4.0.0 was a major new release. TWiki-4.1.x, TWiki-4.2.x, TWiki-4.3.x minor releases containing new features that can be seen by the end user, a large number of bug fixes. Use the TWikiInstallationGuide if you do not have data to carry forward.

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

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.

Line: 56 to 57

Install Extensions

Changed:

<<

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.

>>

Note that not all extensions that worked in Cairo have been updated to work with TWiki-4.0. Many Cairo plugins work fine. Some do not. Many plugins have been upgraded to work with TWiki-4.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.

Line: 84 to 85

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!

Changed:

<<

Manually merge all the users from the old Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

>>

Manually merge all the users from the old Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

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 file. 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.

Line: 94 to 95

Apply Customizations To The Skin

Changed:

<<

Not many of the old Cairo skins work well with TWiki4.X.

>>

Not many of the old Cairo skins work well with TWiki-4.0 and later.

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:

Line: 117 to 118

TWiki.ResetPassword

TWiki.ChangeEmailAddress

Changed:

<<

Upgrading from Cairo to TWiki4 (additional advice)

>>

Upgrading from Cairo to TWiki-4 (additional advice)

Favicon

Changed:

<<

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.

>>

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.

Changed:

<<

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.

>>

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.

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.

Line: 136 to 137

TWikiUsers topic in Main web

Changed:

<<

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

>>

Your Cairo Main.TWikiUsers topic will work in TWiki-4 but you will need to ensure that these 4 users from the default TWiki-4 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

Line: 235 to 236

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

Changed:

<<

registration_approvals - with 4.2.0 it is moved to here from the data directory)

>>

registration_approvals - with 4.2.0 it is moved to here from the data directory.

tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.

work_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.

Overview

Changed:

<<

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

>>

TWiki-4.0.0 was a major new release. TWiki-4.1.0 was a minor release without dramatic changes since 4.0.0. TWiki-4.2.0 is also a minor release containing a few new features that can be seen by the end user, a large number of bug fixes, and a face lift for the skin. It also contains some important updates under the hood to the way users are handled which enables new types of authentication and integration with other systems. The most important new feature is the QuerySearch feature.

If you are upgrading from a 4.0.x release, carry over the configure settings from the old release.

>>

If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.

You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.

You can also choose to start with a fresh configuration and walk through all the settings using your old LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.

If at any time during the installation you want to start over from fresh all you need to do is delete the lib/LocalSite.cfg file and re-run configure.

Install Extensions

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.

Changed:

<<

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.

>>

SmiliesPlugin - Did you add your own smileys? No real changes were made to the smilies topic October 2005 so you can just leave this topic as it is.

To avoid having to re-apply plugin settings each time you upgrade a plugin or TWiki itself, define the altered plugin settings in Main.TWikiPreferences instead

Copy your old webs to new TWiki

Line: 74 to 78

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.

Added:

>>

Make sure all data and pub files and directories are owned by the webserver user.

Note: TWiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps.

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!

Changed:

<<

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.

>>

Manually merge all the users from the old Main.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. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.

If you use data/.htpasswd for authentication copy this file from the old TWiki to the new.

Changed:

<<

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.

>>

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 file. 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.

Added:

>>

If you added or removed fields from the user topic form you may also have tailored TWiki.TWikiRegistration. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration topic.

Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly adviced to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.

Make sure all data and pub files and directories are owned by the webserver user.

Apply Customizations To The Skin

Line: 95 to 104

Apply Preferences From Old Installation

Changed:

<<

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.

>>

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. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.

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.

Added:

>>

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:

TWiki.ChangePassword

TWiki.ResetPassword

TWiki.ChangeEmailAddress

Upgrading from Cairo to TWiki4 (additional advice)

Favicon

Line: 114 to 131

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

Changed:

<<

Set FAVICON = /pub/TWiki/WebPreferences/favicon.ico

>>

Set FAVICON = /pub/TWiki/WebPreferences/favicon.ico

TWikiUsers topic in Main web

Line: 173 to 190

Important Changes since 4.1.0

Changed:

<<

New location for session files

>>

New location for session and other temporary files

Changed:

<<

An upgrader upgrading to 4.1.1 should note the following important change

>>

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.

Added:

>>

Important Changes since 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.

For new installers this makes no difference at all

For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.

New working directory

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

registration_approvals - with 4.2.0 it is moved to here from the data directory)

tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.

work_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.

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.

TWiki Upgrade Guide

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

Added:

>>

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.

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.

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.

Major Changes Compared to TWiki Release 01-Sep-2004

Automated Upgrade Procedure

If you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.

The upgrade script will upgrade the TWiki core only. Plugins will need to be upgraded separately.

Note: To upgrade from a Beta, do not use UpgradeTWiki. Instead follow the steps outlined in Upgrading a Beta, below.

It will:

Create a new TWiki installation, placing the files from the distribution there as appropriate

Where possible, merge the changes you've made in your existing topics and attachments into the new twiki

Where not possible, it will tell you, and you can inspect those differences manually

Create new configuration files for the new TWiki based on your existing configuation information

Set the permissions in the new TWiki so that it should work straight away

Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one

UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with

UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:

Clearly you need to point it to a location where there is enough space

If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation.

If 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.

Manual Upgrade Procedure

>>

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.

Changed:

<<

Follow the installation instructions, and install the new release in a new directory.

Copy your local webs over to the data and pub directories of the new install

You could also use softlinks to link the web directories in data and pub to the old installation area

Unlock the rcs files in data and pub directories from the old installation using the following shell commands:

find data -name '*,v' -exec rcs -r -u -M '{}' \;

find pub -name '*,v' -exec rcs -r -u -M '{}' \;

Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the configure interface for the new install.

If you can't use configure, then copy the newTWiki.cfg to LocalSite.cfg, and edit LocalSite.cfg. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your old TWiki.cfg.

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 the following procedure may help:

Install a copy of the original TWiki release you were using in a temporary directory

Use 'diff' to find changed files, and transfer the changes into the new Dakar install.

If 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.

You are highly recommended not to change any distributed files if you can avoid it, to simplify future upgrades!

Upgrading a Beta

If you followed the recommendations and avoided modifying any distributed files, then this is quite straightforward:

Follow the installation instructions, and install the new release in a new directory.

Copy your local webs over to the data and pub directories of the new install

Be careful to copy over the user topics and TWikiUsers.txt in the Main web

Copy over your bin/LocalLib.cfg and lib/LocalSite.cfg files

Copy over any local files you created (such as .htpasswd and .htaccess files)

Point your webserver at the new install.

If you changed any of the distributed files, you will have to continue from Step 5 above.

>>

The main steps are:

Install the new TWiki version, configure it, and get it to work similar to the old version

Install additional extensions (Plugins). Make sure to use the latest versions

Copy all the non-default webs from the old installation to the new

Copy the users from old installation to the new incl all their topics from Main

Apply tailorings to your Skin (logos, menu bars etc)

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.

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.

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.

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.

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)

Line: 110 to 108

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.

Changed:

<<

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.

>>

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

Line: 118 to 116

Set FAVICON = /pub/TWiki/WebPreferences/favicon.ico

Added:

>>

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.

Major Changes Compared to TWiki Release 01-Sep-2004

Automated Upgrade Procedure

If you changed any of the distributed files, you will have to continue from Step 5 above.

Added:

>>

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.

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

confirm your system settings by pointing your browser to cgi-bin/configure

>>

confirm your system settings by pointing your browser to the configure script

Assuming all goes well, UpgradeTwiki will give you the final instructions.

Line: 64 to 64

Clearly you need to point it to a location where there is enough space

If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation.

Added:

>>

If 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.

Deleted:

<<

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTWiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure

If 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.

You are highly recommended not to change any distributed files if you can avoid it, to simplify future upgrades!

Line: 94 to 95

If you followed the recommendations and avoided modifying any distributed files, then this is quite straightforward:

Follow the installation instructions, and install the new release in a new directory.

Copy your local webs over to the data and pub directories of the new install

Changed:

<<

Copy over your bin/setlib.cfg and lib/LocalLib.cfg files

>>

Be careful to copy over the user topics and TWikiUsers.txt in the Main web

Copy over your bin/LocalLib.cfg and lib/LocalSite.cfg files

Copy over any local files you created (such as .htpasswd and .htaccess files)

Point your webserver at the new install.

If you changed any of the distributed files, you will have to continue from Step 5 above.

Automated Upgrade Procedure

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

>>

If you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below.

Changed:

<<

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing
TWiki installation because it leaves that untouched.

>>

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.

UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with

UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:

Clearly you need to point it to a location where there is enough space

If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed

Changed:

<<

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation

If you have done tricky stuff with $OS in your existing TWiki.cfg file, then you will need to manually examine the new TWiki.cfg file and possibly put your tricky changes in there manually

>>

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation.

Changed:

<<

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

>>

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTWiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Changed:

<<

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user

Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory

Verify installation:

Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address any potential problems

Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users

Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

>>

Manual Upgrade Procedure

Changed:

<<

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.

>>

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.

Known Issues

Follow the installation instructions, and install the new release in a new directory.

Copy your local webs over to the data and pub directories of the new install

You could also use softlinks to link the web directories in data and pub to the old installation area

Unlock the rcs files in data and pub directories from the old installation using the following shell commands:

find data -name '*,v' -exec rcs -r -u -M '{}' \;

find pub -name '*,v' -exec rcs -r -u -M '{}' \;

Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the configure interface for the new install.

If you can't use configure, then copy the newTWiki.cfg to LocalSite.cfg, and edit LocalSite.cfg. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your old TWiki.cfg.

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 the following procedure may help:

Install a copy of the original TWiki release you were using in a temporary directory

Use 'diff' to find changed files, and transfer the changes into the new Dakar install.

And many more enhancements, see the complete change log at TWikiHistory

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing
TWiki installation because it leaves that untouched.

Assuming all goes well, UpgradeTwiki will give you the final instructions.

There are a few points worth noting:

UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with

UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:

Clearly you need to point it to a location where there is enough space

If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed

UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation

If you have done tricky stuff with $OS in your existing TWiki.cfg file, then you will need to manually examine the new TWiki.cfg file and possibly put your tricky changes in there manually

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user

Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory

Verify installation:

Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; address any potential problems

Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users

Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.