diff options
Diffstat (limited to 'TWiki')
| -rw-r--r-- | TWiki/TWikiUpgradeGuide.mdwn | 243 |
1 files changed, 186 insertions, 57 deletions
diff --git a/TWiki/TWikiUpgradeGuide.mdwn b/TWiki/TWikiUpgradeGuide.mdwn index 10438183..83f4a915 100644 --- a/TWiki/TWikiUpgradeGuide.mdwn +++ b/TWiki/TWikiUpgradeGuide.mdwn @@ -35,73 +35,204 @@ The 01 Sep 2001 release includes the following new features and enhancements: * **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="TWiki_Directory_Structure_and_Fi"> TWiki Directory Structure and File Names </a> + +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: + +<table border="1" cellpadding="1" cellspacing="0"> + <tr> + <th bgcolor="#99CCCC"><strong>From TWiki 01-Dec-2000:</strong></th> + <th bgcolor="#99CCCC"><strong>To TWiki 01-Sep-2001:</strong></th> + </tr> + <tr> + <td><code>twiki/bin/wikicfg.pm</code></td> + <td><code>twiki/lib/TWiki.cfg</code></td> + </tr> + <tr> + <td><code>twiki/bin/wiki.pm</code></td> + <td><code>twiki/lib/TWiki.pm</code></td> + </tr> + <tr> + <td><code>twiki/bin/wikiaccess.pm</code></td> + <td><code>twiki/lib/TWiki/Access.pm</code></td> + </tr> + <tr> + <td><code>twiki/bin/wikiprefs.pm</code></td> + <td><code>twiki/lib/TWiki/Prefs.pm</code></td> + </tr> + <tr> + <td><code>twiki/bin/wikisearch.pm</code></td> + <td><code>twiki/lib/TWiki/Search.pm</code></td> + </tr> + <tr> + <td><code>twiki/bin/wikistore.pm</code></td> + <td><code>twiki/lib/TWiki/Store.pm</code></td> + </tr> +</table> + +A new `twiki/lib/TWiki/Plugins` directory contains the new Plugin modules. ## <a name="Standard_Upgrade_Procedure"> Standard Upgrade Procedure </a> +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. + +<table border="1" cellpadding="1" cellspacing="0"> + <tr> + <th bgcolor="#99CCCC" colspan="2"><strong>Before Switch:</strong></th> + <th bgcolor="#99CCCC" colspan="2"><strong>After Switch:</strong></th> + </tr> + <tr> + <th bgcolor="#99CCCC"><strong>Current 01-Dec-2000:</strong></th> + <th bgcolor="#99CCCC"><strong>New 01-Sep-2001:</strong></th> + <th bgcolor="#99CCCC"><strong>Obsolete 01-Dec-2000:</strong></th> + <th bgcolor="#99CCCC"><strong>New 01-Sep-2001:</strong></th> + </tr> + <tr> + <td><code>twiki/templates/</code></td> + <td><code>twiki/templates2/</code></td> + <td><code>twiki/templates1/</code></td> + <td><code>twiki/templates/</code></td> + </tr> + <tr> + <td><code>twiki/bin/</code></td> + <td><code>twiki/bin/2/</code></td> + <td> (overwritten) </td> + <td><code>twiki/bin/</code></td> + </tr> + <tr> + <td> (N/A) </td> + <td><code>twiki/bin/lib/</code></td> + <td> (N/A) </td> + <td><code>twiki/lib/</code></td> + </tr> + <tr> + <td><code>twiki/data/TWiki</code></td> + <td><code>twiki/data/TWiki2</code></td> + <td><code>twiki/data/TWiki1</code></td> + <td><code>twiki/data/TWiki</code></td> + </tr> + <tr> + <td colspan="4"> (other directories do not change) </td> + </tr> +</table> + +Alternatively you could move the existing installation away, install the 01-Sep-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-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! +The following steps describe the upgrade on Unix. Windows setup is very similar. We assume `$TWIKIROOT` to be the root of your current 01-Dec-2000 release, i.e. `export TWIKIROOT=/some/dir/` + ### <a name="Step_1_Backup_amp_Unpack"> Step 1: Backup & 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` +1. Back up all existing TWiki directories `twiki/bin`, `twiki/pub`, `twiki/data`, `twiki/templates`. +2. Create a temporary directory and unpack the ZIP file there: <br />`mkdir -p ~/tmp/`<br />`cp -p ~/downloads/TWiki20010901.zip ~/tmp/`<br />`cd ~/tmp/`<br />`unzip ~/tmp/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 +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_Install_new_template_file"> Step 3: Install new template files </a> + +1. Move & rename the template directory to a temporary `twiki/templates2` directory, ex: <br />`mv ~/tmp/templates $TWIKIROOT/templates2` +2. Pay attention to the file and directory permissions (security issue). Set file permissions, ex: <br />`chmod 644 *.cgi` + +### <a name="Step_4_Install_new_data_and_pub_"> Step 4: Install new data and pub files </a> + +1. Move the TWiki web to a temporary TWiki2 `twiki/data/TWiki2` directory. Do the same to files attached to this web, ex: <br />`mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2`<br />`mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2` +2. Move & rename the Know web to a temporary `twiki/data/Know2` directory, ex: <br />`mv ~/tmp/data/Know $TWIKIROOT/data/Know2`<br />`mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2` +3. Move the \_default and Trash web, ex: <br />`mv ~/tmp/data/_default $TWIKIROOT/data`<br />`mv ~/tmp/data/Trash $TWIKIROOT/data` +4. Move the MIME types file, ex: <br />`mv ~/tmp/data/mime.types $TWIKIROOT/data` +5. 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`). +6. 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 the user of your cgi-scripts, i.e. `www-data`. A simple way to switch the locker of the RCS files is to use sed: <br />`for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done` + +### <a name="Step_5_Install_new_CGI_scripts"> </a> Step 5: Install new CGI scripts + +1. Move & rename the CGI script directory to a temporary `twiki/bin/2` directory, ex: <br />`mv ~/tmp/bin $TWIKIROOT/bin/2` +2. If necessary, change the script names to include the required extension, ex: `.cgi` +3. Copy any additional scripts you might have from the 01-Dec-2000 release, ex: <br />`cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2` +4. In case you use basic authentication, rename `.htaccess.txt` to `.htaccess` and customize it, ex: <br />`cd $TWIKIROOT/bin/2`<br />`mv .htaccess.txt .htaccess`<br />`diff ../.htaccess .`<br /> and merge the content +5. Pay attention to the file and directory permissions (security issue). Set permissions, ex: <br />`chmod 755 *.cgi` + +### <a name="Step_6_Install_new_Perl_library_"> Step 6: Install new Perl library files </a> + +1. Move the lib directory to a temporary `twiki/bin/lib` directory, ex: <br />`mv ~/tmp/lib $TWIKIROOT/bin` +2. Pay attention to the file and directory permissions (security issue). Set permissions, ex: <br />`chmod 644 *.pm` + +### <a name="Step_7_Set_configurations_and_te"> Step 7: Set configurations and test installation </a> + +1. 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: <br />`cd $TWIKIROOT/bin/lib`<br />`diff ../wikicfg.pm TWiki.cfg` +2. Make sure to set the correct temporary location of templates and scripts, ex: <br />`$scriptUrlPath = "/twiki/bin/2";`<br />`$templateDir = "/home/httpd/twiki/templates2";` +3. 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` +4. 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: + * Old URL: `http://localhost/cgi-bin/view` + * New URL: `http://localhost/cgi-bin/2/view` + +### <a name="Step_8_Update_topics"> Step 8: Update topics </a> + +You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Sep-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended so that users don't get surprized by meta-data content showing up in topics. + +1. Remember that you have now two TWiki webs: + * The original `TWiki` web. + * The new `TWiki2` web, which gets renamed to `TWiki` when you switch over the installation. +2. In case you customized `TWiki.TWikiRegistration`, merge your changes back into `TWiki2.TWikiRegistration`. +3. Copy `TWiki.TWikiWebsTable` to `TWiki2.TWikiWebsTable`. + * Do the same for any other topics you might have created in the `TWiki` web. +4. In `TWiki2.TWikiPreferences`, merge the old `TWiki.TWikiPreferences` settings and customize it. + * Add your webs to WIKIWEBLIST + * Set the WIKIWEBMASTER + * Set the SMTPMAILHOST +5. 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: <br />`* Set NOSEARCHALL = on` + * Modify WEBTOPICLIST, ex: <br /><code>\* Set WEBTOPICLIST = [[%HOMETOPIC%]\[Home]] %SEP% [[WebChanges]\[Changes]] %SEP% [[WebIndex]\[Index]] %SEP% [[WebSearch]\[Search]] %SEP% Go <input type="text" name="topic" size="16" /></code> + * Add a these new preferences: <br />`* Set DENYWEBVIEW =`<br />`* Set ALLOWWEBVIEW =`<br />`* Set DENYWEBRENAME =`<br />`* Set ALLOWWEBRENAME =` + * Set FINALPREFERENCES: <br />`* Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME` +6. In `WebSearch` of all webs, replace content with this one line: <br /><code>%INCLUDE\{"%TWIKIWEB%.WebSearch"\}%</code> +7. In `WebChanges` of all webs, replace content with this one line: <br /><code>%INCLUDE\{"%TWIKIWEB%.WebChanges"\}%</code> + +### <a name="Step_9_Customize_template_files"> Step 9: Customize template files </a> + +**_Note:_** Skip this step in case you did not customize your template files. + +1. Remember that you have now two template directories: + * The original `twiki/templates`. + * The new `twiki/templates2`, which gets renamed to `twiki/templates` when you switch over the installation. +2. 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]]. +3. 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. +4. 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. + +### <a name="Step_10_Switch_over_to_new_insta"> Step 10: Switch over to new installation </a> + +In this step we relocate the working 01-Sep-2001 installation over the old 01-Dec-2000 installation, so that we don't need to change the URL. + +1. Test your new 01-Sep-2001 installation under `twiki/bin/2/view` to make sure everything works as expected. + * **_Note:_** Don't worry about the Plugins, they will work after the switch. +2. Edit `$TWIKIROOT/bin/2/TWiki.cfg` and remove the `/2` from `$scriptUrlPath` and `$templateDir`, ex: <br />`$scriptUrlPath = "/twiki/bin";`<br />`$templateDir = "/home/httpd/twiki/templates";` +3. Rename the `TWiki2` web to `TWiki`, including attachments, ex: <br />`cd $TWIKIROOT/data`<br />`mv TWiki TWiki1`<br />`mv TWiki2 TWiki`<br />`cd $TWIKIROOT/pub`<br />`mv TWiki TWiki1`<br />`mv TWiki2 TWiki` +4. Rename the `templates2` directory to `templates`, ex: <br />`cd $TWIKIROOT`<br />`mv templates templates1`<br />`mv templates2 templates` +5. Move the `lib` directory one level up from `$TWIKIROOT/bin/lib` to `$TWIKIROOT/lib`, ex: <br />`cd $TWIKIROOT`<br />`mv bin/lib .` +6. Copy content of `bin/2` to `bin`, ex: <br />`cd $TWIKIROOT/bin`<br />`cp -p bin/2/* .`<br />`cp -p bin/2/.htaccess .` +7. Point your browser to the original URL and make sure the relocated 01-Sep-2001 installation works as expected, i.e. check browsing, searching and user registration. +8. Clean up and remove obsolete directories: + * Remove directory `$TWIKIROOT/bin/2` + * Remove directory `$TWIKIROOT/templates1` + * Remove directory `$TWIKIROOT/data/TWiki1` + * Remove directory `$TWIKIROOT/pub/TWiki1` + * Remove temporary directory, ex: `~/tmp` + +### <a name="Step_11_Test_the_TWiki_Plugins"> Step 11: Test the TWiki Plugins </a> + +1. 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. +2. In case you have customized the functions `extendHandleCommonTags`, `extendGetRenderedVersionOutsidePRE` and `extendGetRenderedVersionInsidePRE` in `twiki/bin/wikicfg.pm`: + * Merge those changes back into `twiki/lib/TWiki/Plugins/Default.pm` ### <a name="General_Format_Changes"> General Format Changes </a> @@ -123,10 +254,8 @@ Two major areas of TWiki functionality - [[TWikiDocumentation]] and [[TWikiDocum * 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> +## <a name="Known_Issues_of_TWiki_01_Sep_200"> Known Issues of TWiki 01 Sep 2001 </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 /> +-- [[Main/JohnTalintyre]] - 18 Jul 2001 <br /> -- [[Main/PeterThoeny]] - 12 Sep 2001 <br /> |