Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)

This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.

The latest version of TWiki (01-Dec-2001) is a small incremental release over the 01-Sep-2001 version.

The 01-Sep-2001 version involves several major new features and numerous enhancements to the last full version (01-Dec-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.

SuperAdministrator Group - Lets you to make the members of one user group - by default, TWikiAdminGroup - into TWiki superusers, with the ability to overwrite locked topics from the browser interface. (This gets around the problem of topic lockouts, caused by typos in access privilege definitions.)

The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:

From TWiki 01-Dec-2000:

To TWiki 01-Dec-2001:

twiki/bin/wikicfg.pm

twiki/lib/TWiki.cfg

twiki/bin/wiki.pm

twiki/lib/TWiki.pm

twiki/bin/wikiaccess.pm

twiki/lib/TWiki/Access.pm

twiki/bin/wikiprefs.pm

twiki/lib/TWiki/Prefs.pm

twiki/bin/wikisearch.pm

twiki/lib/TWiki/Search.pm

twiki/bin/wikistore.pm

twiki/lib/TWiki/Store.pm

A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.

Back up and prepare:

Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.

Create a temporary directory and unpack the ZIP file there.

Update files in TWiki root:

Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.

Update template files:

Overwrite all template files in $TWIKIROOT/templates with the new ones.

Update script files:

Overwrite all script files in $TWIKIROOT/bin with the new ones.

Update library files:

Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.

Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.

Update data/TWiki files: (in case you want the updated docs)

Using your browser, merge the new TWiki.TWikiRegistration topic (or TWiki.TWikiRegistrationPub in case you used that one) into your existing TWiki.TWikiRegistration topic.

In the temporary twiki/data/TWiki directory where you unzipped the installation package:

Remove the files you do not want to upgrade: TWikiPreferences.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.

In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g., www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.

Update pub/TWiki files:

Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.

The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.

Before Switch:

After Switch:

Current 01-Dec-2000:

New 01-Dec-2001:

Obsolete 01-Dec-2000:

New 01-Dec-2001:

twiki/templates/

twiki/templates2/

twiki/templates1/

twiki/templates/

twiki/bin/

twiki/bin/2/

(overwritten)

twiki/bin/

(N/A)

twiki/bin/lib/

(N/A)

twiki/lib/

twiki/data/TWiki

twiki/data/TWiki2

twiki/data/TWiki1

twiki/data/TWiki

(other directories do not change)

Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.

Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:

Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.

The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/

Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).

In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g., www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done

Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
cd $TWIKIROOT/bin/libdiff ../wikicfg.pm TWiki.cfg

Make sure to set the correct temporary location of templates and scripts, ex:
$scriptUrlPath = "/twiki/bin/2";$templateDir = "/home/httpd/twiki/templates2";

Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm

Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:

You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.

Remember that you now have two TWiki webs:

The original TWiki web.

The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.

In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.

Copy to TWiki2 any topics that you created in the TWiki web.

Do the same for

In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.

Add your webs to WIKIWEBLIST

Set the WIKIWEBMASTER

Set the SMTPMAILHOST

In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)

Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
* Set NOSEARCHALL = on

The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.

Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:

Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.

Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.

Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.

Example: List all topics in the Know web that have a TopicClassification of PublicFAQ: %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}% (The [T] and [P] is done so that search does not find the topic where this search string is located in!)

Example: Create a link that lists all topics in the Know web with a TopicClassification of PublicFAQ: [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text&search=%5BT%5DopicClassification.*%3F%28td..td%7Cvalue%5C%3D%29.*%3F%5BP%5DublicFAQ&regex=on][All Public FAQ]]All Public FAQ

For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.

Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.

Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.

Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.

A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.