TWiki Upgrade Guide

Upgrading from the 01-Dec-2000 release to the new TWiki 01-Sep-2001

Overview

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

Upgrade Requirements

• To upgrade from a 01-Dec-2000 standard installation to the new, next generation 01-Sep-2001 TWiki Production Release, follow the instructions below.

• NOTE: To upgrade from a pre-01-Dec-2000 TWiki, start with TWikiUpgradeTo01Dec2000.

• To upgrade from a Beta of the new release, or if you've made custom modifications, read through the documentation and use the procedure below as a guideline.

Major Changes from TWiki 01-Dec-2000

The 01 Sep 2001 release includes the following new features and enhancements:

• TWiki Plugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
  • InterwikiPlugin (preinstalled) - Link to external sites with text aliases, SiteAlias:Page; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.)
• TWikiTemplateSystem^? - New, more flexible template system.
• TWikiSkins - Overwrite template headers and footers; page content is unaffected.
• TWikiMetaData - New data format
• TWikiFormTemplate^? - Create multiple input forms per web; data is rendered in HTML tables.
• Rename/move/delete topics Individual pages can be managed through the browser. Deleted topics are stored in a common Trash web.
• Change passwords Change and reset passwords using forms
• TOC (Table of Contents) - %TOC% variable generates a hierarchical table of contents from topic headings: <HI>...<H6>. Set depth.
• ArbitraryTextForWikiWordLinks - Text formatting rules to form links from any combination of words and spaces.
• AttachmentsUnderRevisionControl Changes to files attached to topics - FileAttachments - are now tracked under revision control (RCS).
• ConvertToXHTML10 - Templates and HTML page rendering are in XHTML 1.0 as far as possible without breaking HTML 3.2 compliance.
• HierarchicalNavigation

The TWiki directory structure remains the same, with one exception, the new lib/TWiki/Plugins directory tree to for the main configuration file, library, internal modules and the new Plugin modules. Pre-existing files were formerly in bin.

Standard Upgrade Procedure

Follow this step-by-step guide to upgrade the 01 Dec 2000 version to the 01 Sep 2001 release, and import your original page data:

Step 1: Backup & Unpack

1. 1. Backup all existing TWiki directories ( bin, pub, data, templates )

1. 1. Unpack the zip file into some working directory:
      mkdir -p ~/tmp/
cd ~/tmp
unzip ~/TWiki20001201.zip

Step 2: Upgrade TWiki document files

1. 1. Move the document files to your TWiki root ( twiki ):
      mv ~/tmp/TWiki*.html $TWIKIROOT
mv ~/tmp/index.html $TWIKIROOT
mv ~/tmp/readme.txt $TWIKIROOT
mv ~/tmp/license.txt $TWIKIROOT

Step 3: Upgrade CGI scripts

1. 1. Rename your original twiki/bin directory: ( twiki/bin )
      mv $TWIKIROOT/bin $TWIKIROOT/bin.old
   2. Move the new scripts to your original twiki/bin location, i.e.
      mv ~/tmp/bin $TWIKIROOT/bin
   3. Merge the changes in your current wikicfg.pm into the new wikicfg.pm. We suggest using diff -c to compare the two files if you have made heavy changes to the file:
      diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less
   4. Restore any additional scripts you might have from the old directory, ex:
      mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/
   5. Test your TWiki installation if you can view topics.

• • Pay attention to the file and directory permissions (security issue)

Step 4: Upgrade template files

1. 1. Rename your original twiki/templates directory: ( twiki/templates )
      mv $TWIKIROOT/templates $TWIKIROOT/templates.old
   2. Move the new templates to your original twiki/templates location:
      mv ~/tmp/templates $TWIKIROOT/templates
   3. __Merge the changes in your current template files into the new template files. To compare two files use
      =diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less=__
   4. Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
   5. Test your TWiki installation to see if you can view topics.

Step 5: Upgrade public files

1. 1. Move the new twiki/pub/TWiki directory to your installation: ( twiki/pub )
      mv ~/tmp/pub/TWiki $TWIKIROOT/pub/
   2. Move the new twiki/pub/twikilogo* image files to your installation:
      mv ~/tmp/pub/twikilogo* $TWIKIROOT/pub

• • Pay attention to the file permissions of the TWiki directory and its subdirectory and files. The files must be writable by the CGI scripts (usually user "nobody").

Step 6: Upgrade data files

1. 1. Move the new twiki/data/TWiki directory to your installation: ( twiki/data )
      mv ~/tmp/data/TWiki $TWIKIROOT/data/
      Pay attention to the file permissions of the TWiki directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
   2. Optionally move the new twiki/data/Test directory to your installation,
      mv ~/tmp/data/Test $TWIKIROOT/data/
      (Pay attention to the file permissions)
   3. TWikiRegistration moved from TWiki.Main to TWiki.TWiki. In case you customized TWikiRegistration , merge your changes back into TWiki.TWikiRegistration , then delete $TWIKIROOT/data/Main/TWikiRegistration*.
   4. TWikiPreferences into TWiki.TWikiPreferences.
   5. Merge your changes to the WebPreferences topics in all your webs into WebPreferences
   6. Modify the WebPreferences topics in all your webs to reflect the following:
      • WEBTOPICLIST should use WebChanges for "Changes", and WebIndex for "Index":
        | <a href="WebChanges">Changes</a>
| <a href="WebIndex">Index</a>
      • In case you want to exclude a web from a web="all" search: Set this new preference
        Set NOSEARCHALL = on
   7. The WebSearch topic has considerable changes. Copy the one from TWiki.TWiki into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
   8. Change the WebHome topics in all your webs to reflect these changes:

Known Upgrade Issues

• • Check http://TWiki.org/cgi-bin/view/Codev/KnownIssuesOfTWiki01Sep2001 for known issues of TWiki 01 Sep 2001 (production release)