(r16)TWikiUpgradeTo01Dec2001 < TWiki

Webs
Main
Sandbox
TWiki
You are here: FS > TWiki Web > TWikiUpgradeTo01Dec2001	r16 - 12 Sep 2001 - 06:51 - MikeMannix^?
View topic \| ~~EditAttach~~Printable
Start of topic | Skip to actions
%TOC%
%STARTINCLUDE%
---# TWiki Upgrade Guide

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

---++ Overview

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. 

---++ 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   %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.  

---++ Major Changes from TWiki 01-Dec-2000

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

   * *[[TWikiDocumentation#TWiki_Plugins][TWiki Plugins]]* - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the [[TWikiPlugins#PluginAPI][TWiki Plugin API]].
      * [[TWikiDocumentation#InterwikiPlugin][InterwikiPlugin]] (preinstalled) - Link to external sites with text aliases, =SiteAlias:Page=; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.) 
   * *[[TWikiDocumentation#TWiki_Template_System][TWikiTemplates]]* - New, more flexible template system.
   * *[[TWikiDocumentation#TWiki_Skins][TWikiSkins]]* - Overwrite template headers and footers; page content is unaffected. 
   * *[[TWikiDocumentation#TWiki_Meta_Data][TWikiMetaData]]* - New data format 
   * *[[TWikiDocumentation#TWiki_Form_Template][TWikiForms]]* - Create multiple input forms per web; data is rendered in HTML tables.
   * *[[TWikiDocumentation#Managing_Topics][Rename/move/delete topics]]* Individual pages can be managed  through the browser. Deleted topics are stored in a common Trash web.
   * *[[TWikiDocumentation#Changing_Passwords][Change passwords]]* Change and reset passwords using forms.
   * *[[%TWIKIWEB%.TWikiVariables][TOC (Table of Contents)]]* - =%<nop>TOC%= variable generates a hierarchical table of contents from topic headings: &lt;HI&gt;...&lt;H6&gt;. Set depth.
   * *[[%TWIKIWEB%.TWikiVariables][Arbitrary Text for <nop>WikiWord Links]]* - Text formatting rules to generate automatic links from any combination of words and spaces.
   * *[[%TWIKIWEB%.FileAttachment][Attachments Under Revision Control]]* 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.
   * *<nop>SuperAdministrator Group* allows you to give one user group - by default, <nop>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=.

---++ Standard Upgrade Procedure

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:

---+++ Pre-Upgrade Preparation

Two major areas of TWiki functionality - [[TWikiDocumentation#TWiki_Template_System][templates]] and [[TWikiDocumentation#TWiki_Form_Templates][Category Tables]] (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!

---+++ Step 1: Backup & Unpack

      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/=
      1. Unpack the zip file into your newly empty working directory:
     <br> =cd $TWIKIROOT=
     <br> =unzip ~/TWiki20010901.zip=

---+++ Step 2: Upgrade TWiki document files 

      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=

---+++ Step 3: Upgrade CGI scripts

      1. If necessary, change the script names to include the required extension, ex: =.cgi=
      1. Restore any additional scripts you might have from the =tmp= directory, ex:
        <br> =mv ~/tmp/bin/somescript $TWIKIROOT/bin/=
      1. Set permissions, ex:
        <br> =chmod 755 *.cgi=
      1. Restore any additional scripts you might have from the =tmp= directory, ex:
        <br> =mv ~/tmp/bin/somescript $TWIKIROOT/bin/=
      1. Test your TWiki installation to see if you can view topics.
        
      * Pay attention to the file and directory permissions (security issue)

---+++ Step 4: Set configurations in <code>TWiki.cfg</code>

      1. Customize the new =lib/TWiki.cfg= configuration file, which replaces the =wikicfg.pm= file. New settings to watch for:
         * <nop>SuperAdminCanConfig
         * 
      1. Test your TWiki installation to see if you can view topics.
      1. Test the new [[TWikiDocumentation#TWiki_Plugins][TWikiPlugins]] by checking the Plugins settings in TWikiPreferences.
         * The =<nop>EmptyPlugin=, =<nop>DefaultPlugin=, and =<nop>InterwikiPlugin= should be preinstalled. To check the %TWIKIWEB%.InterwikiPlugin, go to its page.
        
      * Pay attention to the file and directory permissions (security issue)

---+++ Step 5: Upgrade template files 

      1. Customized templates and skins need to be upgraded to the new [[TWikiDocumentation#TWiki_Template_System][TWiki Template System]]. 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#TextFormattingRules][TextFormattingRules]], but you have to escape unwanted ones. Also, remove empty lines unless you want a ==&lt;p /&gt;= tag added.
         * Added [[TWikiDocumentation#TWiki_Meta_Data][TWikiMetaData rendering]]. 
      1. Form Templates replace the <nop>TWikiCategoryTables:
         * [[TWikiDocumentation#FormsVsCategoryTables][Create a replacement Form Template]] 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.
      1. For each web that has a custom ==notedited.tmpl== template, create a WebTopicEditTemplate to conform with the new [[TWikiDocumentation#SelectableNewTopicTemplates][SelectableNewTopicTemplates]] feature. Retired =notedited.tmpl=, =notext.tmpl= and =notwiki.tmpl= templates.
      1. Test your TWiki installation to see if you can view topics.

---+++ Step 6: Upgrade public files

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

---+++ Step 7: Upgrade data files 

      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")
      1. =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*=.
      1. =TWikiPreferences= into =TWiki.TWikiPreferences=.
      1. Merge your changes to the =WebPreferences= topics in all your webs into =WebPreferences=
      1. 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=
      1. 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.
      1. __Change the =WebHome= topics in all your webs to reflect these changes:__
      1. If you are using ==.htaccess==, add the =rename= script
        * You may want to add =[ALLOW|DENY][WEB|TOPIC]RENAME= in some places, like  %TWIKIWEB%.TWikiPreferences, WebPreferences and %MAINWEB%.TWikiUsers
        
---+++ General Format Changes

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

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

   * Use ==Net::SMTP== module instead of ==sendmail== if installed. 

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

   * New variable ==%<nop>STARTINCLUDE%== and ==%<nop>STOPINCLUDE%== variables to control what gets included of a topic. More in %TWIKIWEB%.TWikiVariables.
   
   * FileAttachment info is now stored as [[TWikiDocumentation#TWiki_Meta_Data][TWiki Meta Data]].
      * 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#TWiki_Template_System][TWiki Template System]] )

   * 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.
   
---++ Known Upgrade Issues

      * 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>
End of topic
Skip to actions | Back to top
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding FS? Send feedback