Tags:
upgrade1Add my vote for this tag create new tag
, view all tags
ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Upgrading TWiki 4.X and Maintaining Current Tailoring

Introduction

TWiki 4.X is a lot easier to install compared with TWiki Cairo (3). But upgrading can still be quite a pain. The reason for this is that TWiki contains a lot of user settings in TWiki topics and not one but many config files. And it does not help that you will find old wrong information that was true for Cairo but wrong for TWiki 4.

With a little planning and this step by step guide it is actually not that difficult and an upgrade can be done in 1-2 hours.

This topic is mainly for the admin that has installed 4.0.0 or 4.0.1 and feels it is difficult to upgrade to the subsequent patch releases like from 4.0.2 and later.

It is also relevant when upgrading from 4.0 to 4.1

It is important that you follow all the steps.

Preparation

With a little planning your upgrade should take less than an hour unless you have done major tailorings of the Pattern Skin.

For revision 4.0.2 this is the advice.

  • Download the complete zip or tgz and unpack it in a temporary place.
  • Make a tar.gz or zip of your current installation. You will goof up something and you will love to have this backup handy.
  • Read through this document step by step and delete the files from the new directory that you do not want overwritten in your working installation
  • And as you step though copy all the old files that you need for copying old snips to the new topics to a safe place.
  • When you believe all is clean copy the all the files from the temporary directory to the current TWiki directory.
  • Delete all the files listed in the list of removed files which you find on the TWiki:Codev.DownloadTWiki page where you also downloaded the zip file.

For updating from revision 4.0.2 to 4.0.4 this is the advice.

We upgrade in two steps. First we upgrade to 4.0.3. And then to 4.0.4.

  • Download the TWiki-4.0.3-changed.zip and unpack it in a temporary place
  • Make a tar.gz or zip of your current installation. You will goof up something and you will love to have this backup handy.
  • Remove these files from the unpacked TWiki-4.0.3-changed tree. These files were changed but the changes are not making any difference so there is no reason to upgrade them. The WebLeftBar was changed to work around a bug in 4.0.2. However the original bug was also fixed so the WebLeftBar does not have to be fixed anyway. So if you tailored them - no worries. The CommentPlugin topic just had a date changed in a signature.
    • data/_default/WebLeftBar.txt has been removed from updated TWiki-4.0.3-changed.zip
    • data/Main/WebLeftBar.txt has been removed from updated TWiki-4.0.3-changed.zip
    • data/Sandbox/WebLeftBar.txt has been removed from updated TWiki-4.0.3-changed.zip
    • data/TWiki/WebLeftBar.txt
    • data/TWiki/CommentPlugin.txt
  • Read through this document step by step and delete the files from the new directory that you do not want overwritten in your working installation from 4.0.2 to 4.0.3 they are few.
    • data/TWiki/TWikiRegistration.txt was changed so that the password field is no longer mandatory
    • data/TWiki/WebHome.txt had one link changed that points to the release note html file which has been renamed
    • data/Sandbox/WebHome.txt has some small cosmetic changes. If your users have changed the Sandbox homepage you should not update this page. The changes are purely cosmetic.
    • data/TWiki/NewUserTemplate.txt and all new user's homepages now have an additional "My Personal Data" section which shows the user his own email address - in case it is hidden. If you do not need this you can skip upgrading this file.
    • index.html had one link changed that points to the release note html file which has been renamed. If you replaced this file with your own index.html make sure not to overwrite it and delete the file from the temporary TWiki-4.0.3-changed tree.
  • PatternSkin has been bugfixed and some small enhancements have been added. If you tailored some of the templates and style sheets you will want to keep the original files in a safe place and prepare yourself for some reconstruction of your tailorings. But you should replace all these files and then tailor them again to make sure you get all the bug fixes.
    • All the files in the templates directory
    • All .css files in =pub/TWiki/PatternSkin
    • All .js files in pub/TWiki/TWikiJavaScripts
  • When you believe all is clean copy the all the files from the temporary directory to the current TWiki directory.
  • ALERT! Because the -changed package is a zip file it contains no access rights. Before you continue - run the script in the next section "File Access Rights" so that all the ownership and access rights are correct.
  • Reapply any tailorings of the PatternSkin files
  • If you have your own style sheets check that the styles are not altered in the improved PatternSkin.
  • Next step is to upgrade from 4.0.3 to 4.0.4.

For upgrading from 4.0.3 to 4.0.4 this is the advice

Upgrading from 4.0.3 and on is really simple. It is a simple matter of replacing files.

  • Download the TWiki-4.0.4-changed.zip which only contains the files that have changed since release 4.0.3.
  • This time it is really simple because 4.0.4 only contains files that are normally never tailored. Just copy all the files from the TWiki-4.0.4-changed.zip package on top of the current TWiki directory replacing all the files.
  • Read carefully the release topic TWikiRelease04x00x04 and pay attention to the security related changes. You should take care and update your Apache configuration as described in SecurityAlertSecureFileUploads. You may already have done this when the advice came out as it is relevant to all versions of TWiki. But better check again.
  • Now you have TWiki upgraded to 4.0.4.
  • On the TWikiRelease04x00x04 you will find a link to the latest hotfix release. Download the latest hotfix and copy all the files in the package on top of your TWiki installation. Again the hotfix package does not contain any settings files or files you normally tailor so you can safely install it.

For upgrading from 4.0.4 to 4.0.5

Hotfix release 4.0.4-4 is the last incremental release called hotfix. From 4.0.5 the TWiki patch releases (version number changes on the last decimal) are incremental releases that only contain the most important fixes. Patch releases will be released as full release packages, and in addition patch releases will also contain accumulated upgrade packages containing changed files relative to the last major or minor release (except for 4.0.X the upgrade package will be relative to 4.0.4). And the upgrade packages will not contain changes that affects tailoring and settings.

As this is written 4.0.5 is not yet released. But when it is upgrading from 4.0.4 to 4.0.5 will be a simple matter of downloading the file called upgrade-4.0.5.zip or upgrade-4.0.5.tgz and copy all files in this package on top of your 4.0.4. Patch release 4.0.5 will contain also the changes from the four 4.0.4 hotfixes.

File Access Rights on Unix and Linux

One of the most common problems people ask about it how to set-up the file access rights in Linux/Unix.

This small topic answers this question by giving you the exact shell commands that sets the access rights correctly for your entire TWiki directory tree.

This topic covers TWiki 4.0, 4.1 and 4.2. The two scripts sets the same rights but 4.0 and 4.1 has some small differences in directory structure related to Wysiwyg.

The script below does 2 things

  • It changes the owner of the entire directory tree to the user that apache is run as. Apache is normally started as root and then forks out a number of child processes that do all the work. These child processes run as a user with very few priviledges on the system. The name of the user is given by the directives User and Group in httpd.conf. Each distribution has its own idea what this user should be. In Redhat/Fedora/Centos the user name is apache and the group is also apache. SuSE uses wwwrun as the user and www for the group. Other distributions uses nobody or www-data.
  • It changes the access rights to all the files in the twiki tree to the same as it is shipped in the tgz. When you upgrade using the TWiki-VERSION-changed.zip you run into the problem that zip files contain no user rights so the default right are used. The script below takes care of this.
In the script below I assume your TWiki tree is /var/www/twiki and the apache user/group is apache.

First we move to the right directory and change ownership

cd /var/www
chown -R apache:apache twiki
cd twiki

Make sure your current working directory is the bottom of the twiki tree (./core if svn co directory) The next step changes the access rights. You can copy one line at a time or copy the entire next block of text and paste it to a command line.

  • Pointing hand The script prints everything it does so expect to see a lot of output. If you do not want that, or if -v is not supported on your platform, simply remove all the -v.

For TWiki 5.1.X

Here's a faster (tcsh) script to fix the permissions and ownership.
#! /bin/tcsh -f
set VERBOSE=-v
# Uncomment the following line to silence the output.
# set VERBOSE=

# These are the settings for Ubuntu.
set APACHE_RUN_USER=www-data
set APACHE_RUN_GROUP=www-data

chown -R ${VERBOSE} ${APACHE_RUN_USER}.${APACHE_RUN_GROUP} .
find . -type d -print0 | xargs -0 chmod ${VERBOSE} 755
find data -name '*.txt' -type f -print0 | xargs -0 chmod ${VERBOSE} 644
find data pub -name '*,v' -type f -print0 | xargs -0 chmod ${VERBOSE} 444
find lib locale -type f -print0 | xargs -0 chmod ${VERBOSE} 444
find pub -type f -print0 | xargs -0 chmod ${VERBOSE} 644
find bin -type f -print0 | xargs -0 chmod ${VERBOSE} 555
find templates bin/logos -type f -print0 | xargs -0 chmod ${VERBOSE} 444
find tools -type f -print0 | xargs -0 chmod ${VERBOSE} 555
chmod ${VERBOSE} 644 lib/LocalSite.cfg
chmod ${VERBOSE} 644 data/.htpasswd
chmod ${VERBOSE} 644 data/mime.types
chmod ${VERBOSE} 644 bin/LocalLib.cfg.txt bin/.htaccess.txt
chmod ${VERBOSE} 444 bin/setlib.cfg
chmod ${VERBOSE} 444 tools/extender.pl
chmod ${VERBOSE} 444 working/tmp/README working/README working/registration_approvals/README working/work_areas/README
chmod ${VERBOSE} 660 working/.htaccess
foreach file (AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt twiki_httpd_conf.txt)
    if (-e $file) chmod ${VERBOSE} 444 $file
end

For TWiki 5.0.X

find . -type d -print -exec chmod -v 755 {} \;
find data -name '*.txt' -type f -exec chmod -v 644 {} \;
find data pub -name '*,v' -type f -exec chmod -v 444 {} \;
find lib -type f -exec chmod -v 444 {} \;
find locale -type f -exec chmod -v 444 {} \;
find pub -type f -exec chmod -v 644 {} \;
find bin -type f -exec chmod -v 555 {} \;
find bin/logos -type f -exec chmod -v 444 {} \;
find templates -type f -exec chmod -v 444 {} \;
find tools -type f -exec chmod -v 555 {} \;
chmod -v 644 lib/LocalSite.cfg
chmod -v 644 data/.htpasswd
chmod -v 644 data/mime.types
chmod -v 644 bin/LocalLib.cfg.txt bin/.htaccess.txt
chmod -v 444 bin/setlib.cfg
chmod -v 444 tools/extender.pl
chmod -v 444 working/tmp/README working/README working/registration_approvals/README working/work_areas/README
chmod -v 660 working/.htaccess
chmod -v 444 AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt twiki_httpd_conf.txt

For TWiki 4.2.X

find . -type d -print -exec chmod -v 755 {} \;
find data -name '*.txt' -type f -exec chmod -v 644 {} \;
find data pub -name '*,v' -type f -exec chmod -v 444 {} \;
find lib -type f -exec chmod -v 444 {} \;
find locale -type f -exec chmod -v 444 {} \;
find pub -type f -exec chmod -v 644 {} \;
find bin -type f -exec chmod -v 555 {} \;
find bin/logos -type f -exec chmod -v 444 {} \;
find templates -type f -exec chmod -v 444 {} \;
find tools -type f -exec chmod -v 555 {} \;
chmod -v 644 lib/LocalSite.cfg
chmod -v 644 data/.htpasswd
chmod -v 644 data/mime.types
chmod -v 644 bin/LocalLib.cfg.txt bin/.htaccess.txt
chmod -v 444 bin/setlib.cfg
chmod -v 444 tools/extender.pl
chmod -v 444 working/tmp/README working/README working/registration_approvals/README working/work_areas/README
chmod -v 660 working/.htaccess
chmod -v 444 AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt TWikiHistory.html twiki_httpd_conf.txt TWikiReleaseNotes04x02.html 

For TWiki 4.1.X

find . -type d -print -exec chmod -v 755 {} \;
find data -name '*.txt' -type f -exec chmod -v 644 {} \;
find data pub -name '*,v' -type f -exec chmod -v 444 {} \;
find lib -name '*.pm' -type f -exec chmod -v 444 {} \;
find locale -type f -exec chmod -v 444 {} \;
find pub -type f -exec chmod -v 644 {} \;
find pub/TWiki/KupuContrib -type f -exec chmod -v 444 {} \;
find bin -type f -exec chmod -v 555 {} \;
find bin/logos -type f -exec chmod -v 444 {} \;
find templates -type f -exec chmod -v 444 {} \;
find tools -type f -exec chmod -v 555 {} \;
chmod -v 644 lib/LocalSite.cfg
chmod -v 644 data/.htpasswd
chmod -v 644 data/mime.types
chmod -v 444 bin/LocalLib.cfg.txt
chmod -v 444 bin/.htaccess.txt
chmod -v 444 pub/_work_areas/.htaccess
chmod -v 444 pub/_work_areas/README
chmod -v 444 AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt TWikiHistory.html twiki_httpd_conf.txt TWikiReleaseNotes04x01.html 

For TWiki 4.0.X

find . -type d -print -exec chmod -v 755 {} \;
find data -name '*.txt' -type f -exec chmod -v 644 {} \;
find data pub -name '*,v' -type f -exec chmod -v 444 {} \;
find lib -name '*.pm' -type f -exec chmod -v 444 {} \;
find locale -type f -exec chmod -v 444 {} \;
find pub -type f -exec chmod -v 644 {} \;
find pub/TWiki/WysiwygPlugin/_kupu -type f -exec chmod -v 444 {} \;
find bin -type f -exec chmod -v 555 {} \;
find bin/logos -type f -exec chmod -v 444 {} \;
find templates -type f -exec chmod -v 444 {} \;
find tools -type f -exec chmod -v 555 {} \;
chmod -v 644 lib/LocalSite.cfg
chmod -v 644 data/.htpasswd
chmod -v 644 data/mime.types
chmod -v 444 bin/LocalLib.cfg.txt
chmod -v 444 bin/.htaccess.txt
chmod -v 444 pub/_work_areas/.htaccess
chmod -v 444 pub/_work_areas/README 
chmod -v 444 AUTHORS COPYING COPYRIGHT index.html INSTALL.html LICENSE pub-htaccess.txt readme.txt robots.txt root-htaccess.txt subdir-htaccess.txt TWikiHistory.html twiki_httpd_conf.txt TWikiReleaseNotes04x00.html 
chmod -v 555 UpgradeTwiki

SELinux Systems

SELinux users and roles are not related to the actual system users and roles. For every current user or process, SELinux assigns a three string context consisting of a role, user name, and domain (or type).

Simply append this line to the end of whichever of the above scripts most suited your needs, or manually type it into the command line yourself:

chcon -Rt httpd_sys_content_t .

-- Contributors: KennethLavrsen, PeterThoeny

Upgrading from 4.0.X to 4.1.1

The upgrade is a minor release and most files that you would tailor have been updated. The advice here is to Install a fresh 4.1.1 and copy your old webs into 4.1.1 - both data directories and pub directories. Be careful when copying the TWiki web from 4.0.X to 4.1.2. This can lead to display problems. In this case use the new Twiki web in both pub and data.

Follow the TWikiUpgradeGuide and continue reading this topic for details about how to maintain your tailoring.

Upgrading from 4.1.0 to 4.1.1

Release 4.1.1 contains quite a lot of important bug fixes and you are very much encouraged to upgrade.

The upgrade zip and tgz from TWikiRelease04x01x01 contains all the changed files and great care has been taken not to include any files that you would normally tailor. You can safely copy the upgrade-4.1.1.zip or upgrade-4.1.1.tgz on top of your 4.1.0.

Overview of configs in TWiki4

When you install TWiki4 the first time the very first thing you are asked to do is this:

  • Copy LocalLib.cfg.txt to LocalLib.cfg
  • Edit the LocalLib.cfg and change the $twikiLibPath to the absolute path of your TWiki lib directory.

There are no more config files in TWiki itself that you need to manually edit. Everything else is done by the configure script!! Do not manually create any other config files. Configure does it all for you.

  • You do not need to edit or save bin/setlib.cfg. That is a small program - not a config file.

When you run configure the first time after an install it gives you many errors and warnings. And this is normal. This is what happens when you run configure the first time.

  • Configure reads the bin/LocalLib.cfg
  • Configure reads the lib/TWiki.spec (changed from TWiki.cfg to TWiki.spec in 4.1.0 and forward)
  • Configure tries to read lib/LocalSite.cfg which is not there.
  • Configure guesses your "General Path Settings" and normally does that well. You will rarely need to edit these. But you should check them and change them if it guessed wrong.
  • At this stage you should not attempt to change anything else in configure. You click next at the bottom of the page and save the setting by giving configure a special configure password.
  • Configure now creates the file lib/LocalSite.cfg and writes the General Path Settings in this file.
  • When you return from this first save you will normally find that all or most of the other warnings and errors are gone.

So the way TWiki 4 configs work are

  • bin/LocalLib.cfg simply tells the executable scripts in the bin directory where to find the lib directory.
  • bin/setlib.cfg is not a config file but a small script
  • lib/TWiki.spec contains all the default settings. Never edit this file. (changed from TWiki.cfg to TWiki.spec in 4.1.0 and forward)
  • lib/LocalSite.cfg contains all the settings that you have changed in configure.

So in an upgrade situation you should not need to worry about configs.

  • bin/LocalLib.cfg is distrubuted as bin/LocalLib.cfg.txt and will not be overwritten when you upgrade
  • lib/TWiki.spec should be overwritten if there is a new version in the upgrade because it may contain new values. (changed from TWiki.cfg to TWiki.spec in 4.1.0 and forward)
  • lib/LocalSite.cfg is not in the distribution and will not be overwritten.

If you ever get in the situation that something is goofed up and you want to start the configure process over from scratch you simply delete the lib/LocalSite.cfg file.

The Apache Config Files

In general - if your Apache config worked before - it will still work - as long as TWiki is placed in the same directory.

However pay attention to any changes in the new default config files that are relevant to security.

From 4.0.0/4.0.1 to 4.0.2 the thing to look for is the file twiki_httpd_conf.txt in the twiki root.

There are some improvements related to safety that hopefully you already implemented when you saw the security advice.

The anonymous_spider thing is what is new. And a couple of more directories have been added as deny from all

BrowserMatchNoCase ^$ anonymous_spider

<Directory "/home/httpd/twiki/bin">
    Options +ExecCGI FollowSymLinks
    SetHandler cgi-script
    Order Allow,Deny
    Allow from all
    Deny from env=anonymous_spider
</Directory>

Nothing changed from 4.0.2 to 4.0.3

In version 4.0.4 the Apache config were further improved. See SecurityAlertSecureFileUploads. Read this security advice carefully and make sure your Apache configuration is up to date. You can always generate a fresh Apache config file using the ApacheConfigGenerator which is always kept up to date with the latest security updates.

TWikiPreferences

An important detail that many are not aware of!!

  • There are two files called TWikiPreferences. One is in the TWiki web and one is in the Main web.
  • Any configs defined in Main.TWikiPreferences overrides the ones defined in TWiki.TWikiPreferences

When you want to change a config in TWikiPreferences it is a good idea to copy the lines from TWiki.TWikiPreferences to Main.TWikiPreferences and change their value there.

This way you can safely overwrite the file data/TWiki/TWikiPreferences when you upgrade and just keep your existing data/Main/TWikiPreferences file.

If you have not done this, it is a good idea to do this before you upgrade. It takes a few minutes and it is a good investment.

Warning. For some odd reason the almost empty data/Main/TWikiPreferences file is included in the TWiki-4.0.2-changed zip/tgz file. Make sure you do not overwrite it when you upgrade. In the TWiki-4.0.3-changed.zip the file is not includes so it will not alter your Main.TWikiPreferences

WebPreferences

In each web you find the important topic WebPreferences.

This is a preference topic that you are very likely to tailor and tailor differently in each web. So these are also files you do not want to overwrite without checking what has changed in the new version first. The distribution zip contains these

  • data/TWiki/WebPreferences - You may have edited a little in this file. Check for your own changes
  • data/Main/WebPreferences - You may have edited a little in this file. Check for your own changes
  • data/_default/WebPreferences - The default WebPreferences when you create a new web. Check for your own changes
  • data/Sandbox/WebPreferences - You may have edited a little in this file. Check for your own changes
  • data/Trash/WebPreferences - Not very likely that you changed anything but check anyway.
  • data/_empty/WebPreferences - You should be able to safely overwrite this at any time

Between TWiki 4.0.0/4.0.1 and 4.0.2 these files have not changed content at all! The format of the files have changed from using tabs to using spaces. It was a mistake that there were tabs in them in 4.0.0 and 4.0.1. So if you edited them yourself there is no reason to overwrite them with the new files if you upgrade to 4.0.2

The images in the pub/webname/WebPreferences have not changed from 4.0.0 to 4.0.2 so you can safely overwrite them when you upgrade.

From 4.0.2 to 4.0.3/4.0.4 none of these have changed.

PatternSkin completely rewritten in 4.0.2

When Twiki 4.0.0 was released the Pattern Skin had been given a most needed facelift and many new nice usability features had been added.

Unfortunately part of the implementation was to change the main topic area into a table cell. This had the consequences that if you put a large image on the page the table cell would adjust to the width of the image and so would all the text. This meant that if a person put an image that was OK on their 19" monitor noone could read the topic on a laptop computer without side scrolling for each line. Also printing was close to impossible in 4.0.0/4.0.1. But ArthurClemens has done a wonderful job re-defining the PatternSkin back to a pure style sheet defined layout and all the problems with widths are resolved.

This very needed change also meant that the pattern templates had to be completely rewritten. And to avoid further non-compatible changes in the future patch releases Arthur very rightfully decided to also implement some changes that makes tailoring easier.

For most of you these PatternSkin changes will solve many problems for you and hardly cause any new problems. But if you have spent a lot of time tailoring the templates for your site - you will need some hours of work making 4.0.2 look the same. The good news is that there are no new major changes waiting and it should be easier to tailor the skin now because the different page components are now devided into smaller manageable chunks. Arthur has documented is all well. Look at the PatternSkin (TWiki.PatternSkin) topic on your local installation.

If you have made many changes to the pattern templates in 4.0.0/4.0.1 you should copy them to a safe place, overwrite them all with the new templates from 4.0.2 or later and get it all up running with the defaults first. And then implement your tailoring. But read the PatternSkin documentation first before you tailor.

In 4.0.3 there has been some bug fixes and also some small enhancements, if if you tailored templates or style sheets you will have to check/re-apply them after the upgrade.

Nothing changed from 4.0.3 to 4.0.4.

WebTopBar

One of the most obvious and easy tailorings is the WebTopBar.

In contrast to its name it is a site wide topic that defines the top bar for all Webs. It is located in the TWiki web: data/TWiki/WebTopBar.txt).

If you had changed the WebTopBar in 4.0.0/4.0.1 it is a good idea to save the file.

The new PatternSkin in 4.0.2 actually makes it a little easier to make WebTopBar work. It is probably a good idea to copy the contents of the old WebTopBar topic to another topic before you upgrade, overwrite the data/TWiki/WebTopBar.txt with the one from the 4.0.2+ zip and change the WebTopBar topic in TWiki once it is running.

Again the PatternSkin documentation is your friend.

In 4.0.2 the WebTopBar now has the jump, search and language feature built in per default. This is for most a good enhancement and a better usage of the top bar screen space. If this does not suit you it take 10 seconds to edit the TWiki.WebTopBar topic and remove it.

From 4.0.2 to 4.0.3/4.0.4 nothing changed.

WebLeftBar

In contrast to WebTopBar the WebLeftBar is defined uniquely for each web.

WebLeftBar topics will still be compatible. Even WebLeftBars from Cairo work reasonably well in 4.0.2+

There is a WebLeftBar.txt in all the webs distributed with TWiki.

Between 4.0.0/4.0.1 the only change made to WebLeftBar in all the webs is that the jump and search fields have been removed (because they are now per default in the top bar).

%INCLUDE{ "%TWIKIWEB%.WebLeftBarSearch" }%

The WebLeftBarSearch topic is still distributed with 4.0.2.

So now your choices are

  • You like the jump and search in the top bar instead of left bar and you have no other tailorings: Overwrite all the WebLeftBat.txt files with the new in the data/webname directories.
  • You like the jump and search in the top bar and you have tailored the web left bars. Overwrite only the ones you did not tailor. In the tailored left bars remove the include of WebLeftBarSearch.
  • You like to keep the jump and search in the left bar. Do not overwrite any of the WebLeftBar.txt files. Instead remove the jump and search from the top bar (previous section in this topic)

When a user create his personal WebLeftBar the default look is defined in WebLeftBarPersonalTemplate ( data/TWiki/WebLeftBarPersonalTemplate.txt ). If you have modified this you do not want to overwrite this either when you upgrade.

In 4.0.3 the files have changed. A fix was implemented to work around a bug with INCLUDE. However the INCLUDE bug was also fixed so there is no need to update the WebLeftBar when you upgrade from 4.0.2. The current TWiki-4.0.3-changed.zip file have had the WebLeftBar topics removed from Main, _default and Sandbox webs so they do not get overwritten.

Style Sheets

All the PatternSkin style sheets must be replaced by the new 4.0.2+ style sheets. If you have modified the existing style sheets you will need to manually reapply the changes. But before you do let us look a little at how the style sheets are loaded.

The PatternSkin loads a total of 4 style sheets

PatternSkin uses 4 stylesheets:

  • layout.css: positioning of block elements on the page
  • style.css: margins, paddings, borders, font sizes
  • colors.css: text colors, background colors, border colors
  • print.css: optimalizations for printed page

You are adviced to avoid changing these default sheets as you will run into trouble each time you upgrade.

If you completely rewrite the style sheets you should attach them to a topic you create yourself which will not be overwritten when you later upgrade and then add these to your Main.TWikiPreferences (TWIKILAYOUTURL, TWIKISTYLEURL, TWIKICOLORURL).

In most cases you can do what you want by redefining existing styles in one single style sheet file and add it with this line in Main.TWikiPreferences.

* Set USERSTYLEURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/style.css

Again the PatternSkin documentation is your friend. Look for PatternSkinCssCookbook and TWiki/PatternSkinCustomization

From 4.0.2 to 4.0.3 some changes were made to the style sheets. You will need to check that your own tailorings are still valid.

templates

When you upgrade you need to replace ALL the templates. Both the classic skin templates and pattern skin templates have changed.

Any customizations - see the Pattern Skin section above.

From 4.0.2 to 4.0.3 many templates were changed.

Nothing changed from 4.0.3 to 4.0.4 that should affect your tailorings.

Normal Customizations

There are a number of topics in the TWiki web that you probably customized and do not want to overwrite or at least remember to edit it again.

Main.TWikiUsers
This file contains all the users that are registered on your TWiki. You do not want to loose this file. You can safely keep the old file from version 4.0.0/4.0.1/4.0.2. Nothing has changed. If you upgrade from Cairo you should manually merge the new and old file. Use the old file and add the missing new system users to the list of users.
data/.htpasswd
Keep this safe. You do not want to loose all your users and their passwords and email addresses.
Main.TWikiAdminGroup
No reason to overwrite this when you upgrade
TWiki.TWikiRegistration
In 4.0.2 this file has been heavily updated and should be replaced with the new. All you normally need to do is remove the note to the administrator at the bottom of the topic (the text with the yellow background). If you tailored your TWikiRegistration by adding or removing fields you need to do the same again and should save your old version. In from 4.0.2 to 4.0.3 the password field was changed to be not mandatory.
TWiki.ChangePassword
This file has been updated since 4.0.0/4.0.1 and should be replaced with the new. All you normally need to do is remove the note to the administrator at the bottom of the topic (the text with the yellow background). If you do not store email addresses in the .htpasswd file you probably want to replace this entire topic with a custom topic that guides your user to change their password. From 4.0.2 to 4.0.3 nothing changed.
TWiki.ResetPassword
This file has been updated since 4.0.0/4.0.1 and should be replaced with the new. All you normally need to do is remove the note to the administrator at the bottom of the topic (the text with the yellow background). If you do not store email addresses in the .htpasswd file you probably want to replace this entire topic with a custom topic that guides your user to change their password. From 4.0.2 to 4.0.3 nothing changed.
TWiki.ChangeEmailAddress
This file has been heavily updated and should be replaced with the new. All you normally need to do is remove the note to the administrator at the bottom of the topic (the text with the yellow background). If you do not store email addresses in the .htpasswd file you probably want to replace this entire topic with a custom topic that guides your user to simply change the email address which is visible in their own user page in the Main web. From 4.0.2 to 4.0.3 nothing changed.
Main.WebNotify
The topic did not change since 4.0.0/4.0.1. If you have added additional names to this topic you should not overwrite it when upgrading. From 4.0.2 to 4.0.3 nothing changed.
TWiki.WebNotify
Same as above.
Sandbox.WebNotify
Same as above
Main.WebHome
You may very well have changed this default WebHome topic to introduce your own TWiki based site. So take care not to overwrite this when upgrading.
TWiki.WebHome
This is more rarely tailored but in case you did take care not to overwrite it. From 4.0.2 to 4.0.3 a link to the release note was changed.
Sandbox.WebHome
This is more rarely tailored but in case you did take care not to overwrite it. From 4.0.2 to 4.0.3 a purely cosmetic update was made and if your users have already edited the Sandbox home there is no need to upgrade this topic.
TWiki.NewUserTemplate
This is the template documents that defines how a new users homepage looks like. If you tailored this you should keep your old one. There has been no changes between 4.0.0/4.0.1 and 4.0.2. From 4.0.2 to 4.0.3 the topic was enhanced by an additional "My Personal Data" section which shows the user his own email address - in case it is hidden. If you do not need this you can skip upgrading this file.
TWiki.WikiSyntaxSummary
Is the help text hidden behind a twisty at the top when you edit a page. There are probably not many that tailor this but the author of this document does extend it a bit to help his users with the things his users ask about most often so it is relevant to list as a typical tailored topic to watch out for. This topic did not change at all lately.
index.html
Maybe you have your own default entry page leading to your TWiki site. Take care not to overwrite this with the default from the distribution when you upgrade.

Plugins

On each plugin topic you can often alter some settings that globally affects the plugin.

The advice is to do a quick walkthrough of the topics of all your installed plugins and see if you have made any updates to them and write down what they are.

Some typical things you may have altered:

  • CommentPlugin - Set DEFAULT_TYPE
  • EditTablePlugin - Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
  • InterwikiPlugin - Set RULESTOPIC
  • InterWikis - If you added your own rules you should save this topic and not overwrite it.
  • SlideShowPlugin - Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
  • SmiliesPlugin - Did you add your own smileys? No smileys were added 4.0.0 and 4.0.2 so you can just leave this topic as it is.
  • TablePlugin - Set TABLEATTRIBUTES

Files in the bin directory

All the files in the bin directory can be overwriten with the files from the distribution.

If you installed TWiki in an installation where the perl binary is not in the standard location /usr/bin/perl you may have had to alter the "shebang" lines in the scripts in the bin directory.

The shebang line is a nickname for the very first line in a script running under Unix/Linux/*BSD which tells the operating system which interpreter to use to run the program. By default it looks like this.

#!/usr/bin/perl -wT

If your perl is located elsewhere simply change the path in the first line of each file.

There is a small tool in the TWiki distribution which can do it for you called tools/rewriteshebang.pl

The only files that actually have changed between 4.0.0/4.0.1 and 4.0.2 are the bin/configure which must be overwritten with the new version and the example bin/.htaccess.txt which has been improved.

List of files to check carefully before overwriting

data/Main/TWikiPreferences.txt

data/TWiki/WebPreferences.txt
data/Main/WebPreferences.txt
data/_default/WebPreferences.txt
data/Sandbox/WebPreferences.txt
data/Trash/WebPreferences.txt
data/_empty/WebPreferences.txt

data/TWiki/WebTopBar.txt
data/_default/WebLeftBar.txt
data/Main/WebLeftBar.txt
data/Sandbox/WebLeftBar.txt
data/TWiki/WebLeftBar.txt
data/TWiki/WebLeftBarPersonalTemplate.txt

data/Main/TWikiUsers.txt
data/.htpasswd
data/Main/TWikiAdminGroup.txt
data/TWiki/TWikiRegistration.txt
data/TWiki/ChangePassword.txt
data/TWiki/ResetPassword.txt
data/TWiki/ChangeEmailAddress.txt
data/Main/WebNotify.txt
data/TWiki/WebNotify.txt
data/Sandbox/WebNotify.txt
data/Main/WebHome.txt
data/TWiki/WebHome.txt
data/Sandbox/WebHome.txt
data/TWiki/NewUserTemplate.txt
data/TWiki/WikiSyntaxSummary.txt
index.html

data/TWiki/CommentPlugin.txt
data/TWiki/EditTablePlugin.txt
data/TWiki/InterwikiPlugin.txt
data/TWiki/InterWikis.txt
data/TWiki/SlideShowPlugin.txt
data/TWiki/SmiliesPlugin.txt
data/TWiki/TablePlugin.txt

All executables in the bin dir if you earlier had to alter the shebang line. Otherwise just overwrite them.


-- Contributors: KennethLavrsen



Comments & Questions about this Supplemental Document Topic

Thanks Kenneth for the very useful adn well layed out topic! I think a topic name like PatchUgradeOfTWiki04x00 or UpgradingTWiki04x00PatchReleases is more consistent and more descriptive.

-- PeterThoeny - 19 Apr 2006

This is an excellent guide and has completly dispelled all my fears of going from 4.0.0 to 4.0.2

Kenneth you are to be comended; excellent work from you and everyone else on the TWiki team that contributed to this document.

-- AlexTirdil - 24 Apr 2006

Yes, agreed, a very useful and customer focused document.

I renamed it from UpgradingAndMaintainingTailoring to UpgradingTWiki04x00PatchReleases to make it obvious to what releases this applies to. Kenneth corrected the spelling of the renaming ;-)

-- PeterThoeny - 28 Apr 2006

I'm not sure the information on TWikiPreferences above is accurate. On my Cairo install the Main.TWikiPreferences is mostly blank with just a pointer (written by PeterThoeny in 2003 so I know it came installed that way) to the TWiki.TWikiPreferences so that the TWiki web version is the site-wide definer and the Main web version non-existent. But the TWikiPreferences section above indicates the opposite. Can someone help clear up this confusion? Upgrading tomorrow morning! smile

-- AmandaSmith - 07 Jun 2006

Use of the Main.TWikiPreferences is just by convention. In Cairo, it was empty, and site configuration was done in TWiki.TWikiPreferences. In TWiki 4 release, it is recommneded not to change the TWiki.TWikiPreferences, and to overload site specific settings in the Main.TWikiPreferences.

-- PeterThoeny - 07 Jun 2006

Actually, that's not just a convention. Preferences are looked for in a variety of places, as described in AccessControlsVersusPreferences. Site-wide preferences are looked for in two places: TWiki.TWikiPreferences and Main.TWikiPreferences, but any setting that's in Main.TWikiPreferences will override the one in TWiki.TWikiPreferences. Most of the preferences specified in the TWiki topic won't have to be overridden, but a few of them are quite important, such as WIKIWEBMASTER, WIKITOOLNAME, WIKILOGOURL (assuming you want your own logo).

-- MeredithLesly - 08 Jun 2006

What I meant was that "where to set the site preferences is just by convention"; it can be done in the TWiki web or the Main web, it does not really matter where. The Main web's TWikiPreferences is preferred since it makes upgrade easier.

-- PeterThoeny - 09 Jun 2006

Ah, gotcha. It's still a bit awkward, since both topics are shipped but I still think it's a good idea not to mess with the topic in TWiki.

-- MeredithLesly - 09 Jun 2006

This note is just excellent. When I converted from Cairo to Dakar 4.0.0 last December 2005, and then to 4.0.1 in early March 2006, I had to really concentrate on the migration for several hours straight. The documentation at that time was not enough to make it understandable. This time, with the help of this document, it went like clockwork. Thanks!

-- DickWieland - 12 Jun 2006

Your file access rights script is the greatest invention since sliced bread. I find myself using it all the time. (The rest is also very useful.) But the script breaks BibtexPlugin since that plugin has a shell script attached. I therefore suggest adding

find pub -name *.sh -exec chmod -v 760 {} \;
to the script. Of course, that may not be safe, but I don't have a better idea. Is BibtexPlugin breaking any TWiki coding rules by doing things that way? If so, I'll file a bug.

-- ShaughanLavine - 28 Aug 2006

Any advice on upgrading to the new 4.1 release? Which customizations from 4.0.5 should we expect are going to break?

-- JohnDeStefano - 19 Jan 2007

At this point we have just the TWikiUpgradeGuide. Watch out for the topics you customized, such as Main.TWikiPreferences. Changes of system topics should be small, so it is pretty safe to use your customized 4.0 system topics in TWiki 4.1.

-- PeterThoeny - 20 Jan 2007

For the permissions lines under the For TWiki 4.1.X heading...

  • TWikiReleaseNotes04x00.html should be TWikiReleaseNotes04x01.html ?
  • UpgradeTWiki is not in the 4.1 distribution file, so does this line need to be here?

-- MarcusLeonard - 22 Jan 2007

For the permissions lines under the For TWiki 4.1.X heading...

  • should chmod -v 444 lib/LocalSite.cfg be chmod -v 644 lib/LocalSite.cfg ? configure script does not appear to work otherwise

-- MervinJohn - 22 Jan 2007

Thanks, I made those changes. Since this is a wiki, please feel free to do that directly in the documentation. smile

-- PeterThoeny - 24 Jan 2007

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r28 < r27 < r26 < r25 < r24 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r28 - 2007-03-19 - YogiParish
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.