The intension is to make upgrades backwards compatible. But sometimes you may experience changes that affect your website. Normally the change is small, but always backup the database and files before an upgrade and possibly also test the upgrade on another server first.
If you conform to the recommended database-structures and don't use custom tables.php-files, it should be quite easy to upgrade.
Normally months passes by between new TYPO3 versions are out. But in between there are often a lot of previews, every week sometimes! Or you can upgrade your source on a development server continuously from CVS.
So what's the difference and what can you expect from them?
A “new version” is a new set of “official” packages including the source as tgz/zip, the testsite as tgz/zip, the dummy-tgz, the quickstart-zip etc. Such packages will be announced on TYPO3.org and found for download at http://www.typo3.org/download/.You can expect a “new version” to be tested good enough for production sites. (Still, make sure to read the changelog for “!!!” marked lines and make a test upgrade on a separate server first to make sure no changes affects your site negatively!)
A “preview” is simply a tgz-snapshot of todays work on TYPO3! You can normally expect these to work perfectly, but their completeness is not guaranteed to the same degree as with the “new versions”. The “previews” are recommended to download and test and give feedback from. Please see the section below for how to handle the installation of the previews!
When new versions of TYPO3 arrive, you should always follow any additional upgrade information carefully. You might also need to skim the included changelog to see if any features affects the way your site works (look for lines prepended with “!!!” - those are the really important!)
Basically these steps are involved in updating your TYPO3 site:
Make a backup of both uploads/ folder and database. Also you may prefer to upgrade a copy of your site first if there has been a lot of changes and some of them seems to interfere with your site. See the changelog.
Upgrade the distributed source files to the new version.
.tgz:
If you're using the source-distribution in the .tgz file, please see right above where details on symlinking is explained and replace your source directory with the new one.
.zip:
If you're using the .zip distribution, then download the zip source package and copy (and overwrite) it into your TYPO3 folder.
Enter the Install Tool at '.../typo3/install/' on your TYPO3 site.
(If you have password/access problems, please see the section about the Install Tool later in this document).
Go to the “Database Analyser” section, check that the database configuration is correct.
Then click “COMPARE” at the “Update required tables” header:
Now all tables.sql files from core and extensions are read and compared to your current database tables and fields. Any discrepancies will be shown and you'll be able to execute queries sufficient to upgrade you database so it corresponds to the structure required for the new TYPO3 version.
Notice: Be aware if you have deliberately added fields and/or tables to your TYPO3 database for your own purposes! Those tables and fields are removed only if you mark them to be deleted of course, but please be alert that you don't overlook them!
Remove unused fields (and tables) if you wish and click “Write to database”
On the next screen you'll see that all add and changed fields are done properly since they don't show up again. However the fields and tables we chose to drop were renamed first. Now you can consider to let them be and delete them lateron when you're sure you're not going to need them. Or you can just go on drop them finally.
Finally, you should see this:
You may have added your own fields to the database tables or you may have added tables on your own. Don't delete those (of course)!
If you're smart, you name user defined tables and fields prefixed “user_”. Then they'll show up with a little warning icon, so you can easier distinguish them from fields and tables which should be dropped. (see Figure 11)
Tables that are defined in extensions will automatically be managed and you don't have to care about them. They are respected fully.
The table 'static_template' (and some other “static_” tables) contains information that you should never alter yourself. The point is that this tables contains static information distributed with TYPO3 releases. Follow these steps to upgrade the table with the newest information.
Go to the “Database Analyser” section.
Then click “IMPORT” at the “Dump static data” header:
Then tick the check box “Import the whole file...” and click “Write to database”:
... and you should see (something like) this without errors:
You should always clear the cache-tables.
You might also consider clearing the backend user preferences if something in the upgrade requires this. Everything can be done from the Install Tool.
In typo3conf/ you will most likely find cached files for ext_localconf.php and ext_tables.php files from extensions. These must be removed as well.
So all files in typo3conf/ directory which is named “temp_CACHED_*_ext_localconf.php” or “temp_CACHED_*_ext_tables.php” must be removed!
An easy way to clear these files are pressing this link in the backend when logged in as admin user (it's on the top right side):
However, if you see more than two of these “temp_CACHED_” files in typo3conf/ only two of them will be remove by this method and you must remove the rest with either the superadmin.php script, “extdeveval” extension or manually!
Look through the changelog. It's a good place to get an idea about new functions you might need or be interested in.
Especially pay attention to the lines starting with “!!!”. They are important because they are about changes that may affect some websites.
The changelog is found in the root of the source distribution or it is for download with the source-achives.
In the folder “misc/” of the core you will find “superadmin.php” script. You can read inside how to use it. I will just mention it here because it is an indispensable tool when you want to upgrade many sites located in subfolders on the same level in the file system and which all shared the same source.
As the screenshot below shows you enter the “UPDATE” section of the tool. This will show you a list in the left frame of the sites that has been found on your server. Then you simply click all the links there from top-down and they will take you directly to the 4-5 mandatory steps involved in upgrading:
Clearing the extension cache files of typo3conf/
Upgrading database tables structure
Importing static table data (that might have been updated)
Clearing cache tables
Possibly, logging in in the backend.
The “superadmin.php” tool also features statistics that are nice for administrators including shortcuts to admin logins.
However it is a highly dangerous tool if you leave it unprotected on the server!!! Don't mess with the security of this baby! Protect it good, preferably insert an “exit;” statement in the top when not used and put a .htaccess password on its folder!
