%TOC% %STARTINCLUDE%

# <a name="TWiki_Upgrade_Guide"> TWiki Upgrade Guide </a>

_Upgrade from TWiki 01-Dec-2000 to TWiki 01-Sep-2001 (previous to new full release)_

## <a name="Overview"> Overview </a>

The latest version of TWiki (01-Sep-2001) involves several major new features and numerous enhancements to 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.

## <a name="Upgrade_Requirements"> Upgrade Requirements </a>

* 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 %TWIKIWEB%.TWikiUpgradeTo01Dec2000.

* To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.

## <a name="Major_Changes_from_TWiki_01_Dec_"> Major Changes from TWiki 01-Dec-2000 </a>

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

* **[[TWikiDocumentation]]** - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the [[TWikiPlugins]].
  * [[TWikiDocumentation]] (preinstalled) - Link to external sites with text aliases, `SiteAlias:Page`; rules are defined in [[InterWikis]]. (Get more Plugins from the TWiki:Plugins web.)
* **[[TWikiDocumentation]]** - New, more flexible template system.
* **[[TWikiDocumentation]]** - Overwrite template headers and footers; page content is unaffected.
* **[[TWikiDocumentation]]** - New data format
* **[[TWikiDocumentation]]** - Create multiple input forms per web; data is rendered in HTML tables.
* **[[TWikiDocumentation]]** Individual pages can be managed through the browser. Deleted topics are stored in a common Trash web.
* **[[TWikiDocumentation]]** Change and reset passwords using forms.
* **[[TWIKIWEBTWikiVariables]]** - <code>%TOC%</code> variable generates a hierarchical table of contents from topic headings: &lt;HI&gt;...&lt;H6&gt;. Set depth.
* **[[TWIKIWEBTWikiVariables]]** - Text formatting rules to generate automatic links from any combination of words and spaces.
* **[[TWIKIWEBFileAttachment]]** Changes made to files attached to topics are now saved under revision control (RCS).
* **Convert to XHTML** - Templates and HTML page rendering are in XHTML 1.0 as far as possible without breaking HTML 3.2 compliance.
* **HierarchicalNavigation** uses new Meta Data variables to link hierarchically.
* **SuperAdministrator Group** allows you to give one user group - by default, TWikiAdminGroup - superpowers: the ability to overwrite locked topics from the browser interface. (This gets around a potential problem where mistyping topic access definition could result in locking everyone out.)

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

## <a name="Standard_Upgrade_Procedure"> Standard Upgrade Procedure </a>

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

### <a name="Pre_Upgrade_Preparation"> Pre-Upgrade Preparation </a>

Two major areas of TWiki functionality - [[TWikiDocumentation]] and [[TWikiDocumentation]] (input forms associated with a topic)- are entirely different in the new TWiki. Therefore, if you've customized your templates or use Category Tables, you should read those sections _before_ starting your upgrade. That way, converting old templates and pages to new will be flow along smoothly!

### <a name="Step_1_Backup_amp_Unpack"> Step 1: Backup &amp; Unpack </a>

1. 1. Move all existing TWiki directories ( `bin`, `pub`, `data`, `templates` ) to a temporary directory (it's a good idea to do a full back-up first): <br />`mkdir -p ~/tmp/`<br />`mv $TWIKIROOT/* ~/tmp/`
  2. Unpack the zip file into your newly empty working directory: <br />`cd $TWIKIROOT`<br />`unzip ~/TWiki20010901.zip`

### <a name="Step_2_Upgrade_TWiki_document_fi"> Step 2: Upgrade TWiki document files </a>

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

### <a name="Step_3_Upgrade_CGI_scripts"> </a> Step 3: Upgrade CGI scripts

1. 1. If necessary, change the script names to include the required extension, ex: `.cgi`
  2. Restore any additional scripts you might have from the `tmp` directory, ex: <br />`mv ~/tmp/bin/somescript $TWIKIROOT/bin/`
  3. Set permissions, ex: <br />`chmod 755 *.cgi`
  4. Restore any additional scripts you might have from the `tmp` directory, ex: <br />`mv ~/tmp/bin/somescript $TWIKIROOT/bin/`
  5. Test your TWiki installation to see if you can view topics.

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

### <a name="Step_4_Set_configurations_in_TWi"> Step 4: Set configurations in `TWiki.cfg` </a>

1. 1. Customize the new `lib/TWiki.cfg` configuration file, which replaces the `wikicfg.pm` file. New settings to watch for:
    * SuperAdminCanConfig
    *
  2. Test your TWiki installation to see if you can view topics.
  3. Test the new [[TWikiDocumentation]] by checking the Plugins settings in [[TWikiPreferences]].
    * The <code>EmptyPlugin</code>, <code>DefaultPlugin</code>, and <code>InterwikiPlugin</code> should be preinstalled. To check the %TWIKIWEB%.InterwikiPlugin, go to its page.

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

### <a name="Step_5_Upgrade_template_files"> Step 5: Upgrade template files </a>

1. 1. Customized templates and skins need to be upgraded to the new [[TWikiDocumentation]]. 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 [[TWikiDocumentation]], but you have to escape unwanted ones. Also, remove empty lines unless you want a `=<p />` tag added.
    * Added [[TWikiDocumentation]].
  2. Form Templates replace the TWikiCategoryTables:
    * [[TWikiDocumentation]] based on `twikicatitems.tmpl` in each web that used a Category Table.
    * Searches need to be adjusted to deal with format change - if all topics are upgrades, a more specific search can be done.
  3. For each web that has a custom <code>**notedited.tmpl**</code> template, create a [[WebTopicEditTemplate]] to conform with the new [[TWikiDocumentation]] feature. Retired `notedited.tmpl`, `notext.tmpl` and `notwiki.tmpl` templates.
  4. Test your TWiki installation to see if you can view topics.

### <a name="Step_6_Upgrade_public_files"> Step 6: Upgrade public files </a>

1. 1. Move your own public data files and sub-directories from the original `pub` directory to the new installation: ( `$TWIKIROOT/pub` ) <br />`mv ~/tmp/pub/TWiki/somefiles.ext $TWIKIROOT/pub/`<br />`mv ~/tmp/pub/TWiki/somedirectory $TWIKIROOT/pub/`

### <a name="Step_7_Upgrade_data_files"> Step 7: Upgrade data files </a>

1. 1. Move the `tmp/data/TWiki` directory to your installation: ( `twiki/data` ) <br />`mv ~/tmp/data/TWiki $TWIKIROOT/data/`<br /> 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. `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*`.
  3. `TWikiPreferences` into `TWiki.TWikiPreferences`.
  4. Merge your changes to the `WebPreferences` topics in all your webs into `WebPreferences`
  5. Modify the `WebPreferences` topics in all your webs to reflect the following:
    *
    * In case you want to exclude a web from a `web="all"` search: Set this new preference <br />`Set NOSEARCHALL = on`
  6. 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.
  7. **_Change the `WebHome` topics in all your webs to reflect these changes:_**
  8. If you are using <code>**.htaccess**</code>, add the `rename` script \* You may want to add `[ALLOW|DENY][WEB|TOPIC]RENAME` in some places, like %TWIKIWEB%.TWikiPreferences, [[WebPreferences]] and %MAINWEB%.TWikiUsers

### <a name="General_Format_Changes"> General Format Changes </a>

* Format changed of <code>**%GMTIME\{"..."\}%**</code> and <code>**%SERVERTIME\{"..."\}%**</code> variables. Format is now <code>**"$hour:$min"**</code> instead of <code>**"hour:min"**</code>. More in %TWIKIWEB%.TWikiVariables.

* [[TWIKIWEBTWikiVariables]]: Enhanced table syntax might have unwanted side effect: <code>**| \*bold\* |**</code> cells, <code>**|  center aligned  |**</code> and <code>**|   right aligned |**</code> cells, span multiple columns using <code>**| empty cells |||**</code>. More in %TWIKIWEB%.TextFormattingRules.

* Use <code>**Net::SMTP**</code> module instead of <code>**sendmail**</code> if installed.

* Use <code>**&lt;verbatim&gt; ... &lt;/verbatim&gt;**</code> tags instead of <code>**&lt;pre&gt; ... &lt;/pre&gt;**</code> tags where appropriate. More in %TWIKIWEB%.TextFormattingRules.

* New variable <code>**%STARTINCLUDE%**</code> and <code>**%STOPINCLUDE%**</code> variables to control what gets included of a topic. More in %TWIKIWEB%.TWikiVariables.

* [[FileAttachment]] info is now stored as [[TWikiDocumentation]].
  * 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 [[TWikiDocumentation]] )

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

## <a name="Known_Upgrade_Issues"> Known Upgrade Issues </a>

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

* * **_Upgrading requires extensive changes be made to topics in the TWiki web._**

-- [[Main/JohnTalintyre]] - 18 Jul 2001 <br />