What is this about?

Currently I'm in the process of updating a fairly simple website from the now outdated "Long Time Version" 4.5 to it's successor, 6.2.
Since I consider myself as not-the-top-notch-but-not-so-dumb kind of TYPO3 maintainer, and I ran in some issues that surprised me (and I didn't find answers right away), maybe someone will find this useful. I try to document my plans, how it went and what errors on my or other sides occurred

1. Going local

Since the update is announced as non-trivial, I thought it best to create a local test version. I tar-ed the live server's directory with all things concerning TYPO3, and created a directory on my local machine, set up MAMP to serve from there, imported the DB-dump from the live-DB to the local DB, and visited the local install using localhost:8888. Everything looked fine, I now had the current 4.5 version on my machine.

As I found out much much later -- and with a little external help -- , here was my first mistake: My local machine is a Mac OS X 10.9.5, and the local file system is "Mac OS Extended (journaled)". This is a Case-Insensitive (ci) filesystem. The files that I brought local from the live server and that are used on the site are things like "PortraitFounder.JPG". Note the spelling, this will be fun later on.

2. Up-up- and away -dating

As recommended, I checked all installed extension for their newest, 4.5 compatible versions. I removed all extensions that weren't needed, so luckily this installation ended up with only one necessary extension: Formhandler. While in housekeeping mode, I flushed all caches, removed temporary files, all the while checking if the site runs fine (on my local machine). All's good so far.

I downloaded the current stable 6.2.9, and un-tar-ed it in my local test-directory. Switched the typo3_src symlink from typo3_src-4.5 to typo3_src-6.2.9. As expected, the FE was blank. I visited the the backend and the install-tool was waiting for me. I ran all the update steps as prompted and in a relatively short time the update process was finished.

FE was blank, still. I visited the backend, which worked, and suspecting the only extension out of the ordinary, I disabled it. Flush cache, and the FE is there. Yay! Some content images looked funny, others didn't show up at all, but I choose to ignore this for the moment -- I expected problems with the images, since the file handling had been completely rewritten and a File Abstraction Layer had been introduced.

The core functionality of the site depends on the Formhandler forms, so this needed to be dealt with, first.

In the extension manager, I tried to update Formhandler to its newest version which is 6.2 compatible. Didn't work. Okay, so I downloaded it manually and tried to install the t3x file via the extension manager Didn't work, throwing a nondescript "server error" alert.

As I again learned later, I made the second mistake: I didn't use the "presets" that the TYPO3 install tool now provides: i.e. you can preset a "development" or a "production" environment -- which changes what errors and warnings will be logged or displayed And logged warnings would have helped here, I think :-)

Since the site's FE looked more or less intact (ignoring content images), all links were working and the backend worked, too, I wondered if it would be smarter to actually have the test-version on the server, in its later native environment (a thought that was triggered by this extension update error: I suspected that may be a local curl-or-else command was not available or that some local firewall was acting up).

3. Live is Live

So I created a subdomain, and put the tar archive of my local test-directory there. Unpacked it, changed the db-credentials in the config file, visited the subdomain and was one more time greeted with a blank page. Hm. Okay, so again using the install-tool, again running the tasks and tests, basically doing all the things I had already done locally. Finally deleting all temporary files and caches -- and boom, the FE is visible. Yeah.
This time the extension update for the Formhandler worked, and my tests of the formhandler forms in the FE worked out as well. So the only minor thing left was the problem with the images. For the record: This is roughly after two hours of starting the update project - not too bad. Since this site uses only standard content records and nothing fancy is modified with Typoscript, I was fairly optimistic that this update was now in its last steps and that it would finish within my 4hrs timeframe (this is what I expected for the update, since the site was so "clean" extension- and content-wise).

So first I had a look at the images that did not display at all. It turned out that TYPO3 tried to use "fileadmin/_migrated/portraitfounder.jpg" and was greeted with a "image not found". Looking inside "fileadmin/_migrated_" via the console, I had "PortraitFounder.JPG" there. Huh? So TYPO3 has referenced the files in lowercase, but actually the files are mixed case. Hm. since only few images were affected, I opted for the pragmatic way and changed the filenames to lowercase. Bingo, the images were now displayed - but in their full original size, not resized as the had been before, in the 4.5 version. The strange thing was, some images were resized, others not.

I rechecked in the install tool if the image modification functions were working properly; yes. Hm.

I visited the constants editor to see if the styles.content.imagetext.maxW was still set to "420" - yes. But apparently not working. D'oh.

I edited one of the text/image records and set the image width to 420. Bam, works. I looked for a similarity between the image records that were not resized in the FE and discovered that they all had a "height" set in the CE. Aha, I thought, maybe something to do with the newly added responsive image rendering was interfering. So I looked at the css-styled-content docs and settings, I read about the new image rendering, I browsed forum thread after thread, I asked colleagues on twitter, but I found no solution. Literally hours went by.

During the trial-and-error attempts I tried to visit the fileadmin/_migrated/ directory via the "file list" section in the backend, and there an error occurred - TYPO3 couldn't access the directory because one file inside wasn't there. Unfortunately I cannot remember the exact error, but there was a link that led me to a wiki entry which stated that the error may have occurred because a Case Sensitive / Insensitive filesystem conflict, alongside with an explanation on how to set the "file mount" (for the fileadmin in my case) to case sensitive. I did that and after that I was able to browse the files via the "file list" tool. All images looked okay, thumbnails were generated and displayed, so still no hint on why the images were not resized in the front end.

In my despair to get this site production-ready I counted the images affected and reasoned that I could set their width in one go with the list tool - only 50 images, ok. I set the table view in the list view to display the with and height field and there I noticed for the first time, that every entry that had no width or height set, displayed a zero. "0". "0"px? I browsed the web and asked my timeline if that's correct, and luckily after a while, Mathias Schreiber (@mattLefaux), the Product Manager TYPO3 CMS, replied and after a short dialog he told me that maybe my problems were solved if I used the 6.2.10RC release - something may be wrong with the handling of "0" dimensions, resulting in those non-resized images.

I installed the 6.2.10, restored all with/height settings to their pre-update settings, and surely enough, finally everything looked as before.

I rushed a bit through the last parts of the journey, but all in all I spend 9 hours for this simple site's update, and the majority of that with what now seems to be a bug in the latest stable release, trying to encircle the cause, creating theories, testing, failing, starting over again. I reorganized the complete TS by the way, changed and re-uploaded image after image to find a clue and lastly created workarounds to get to the desired result that I had to remove after the 6.2.10RC installation.

My learnings

It doesn't make sense to have a local test environment if it is not mirroring the exact environment of the live server. Especially if ci/cs filesystems are in the mix. Since I usually have front-end related things going on on my local machine, I didn't bother too much about testing environments, but I will have a look at a separate case sensitive partition and Vagrant, should I decide to do this again locally.

My pragmatic approach for the next update will be: Make the test environment on the live server. Had I done this directly, the whole filesystem ci/cs issue wouldn't have occurred, since TYPO3 "detects" during the update/install if the filesystem is ci or cs and makes the settings accordingly.

If you're stuck with image-rendering errors, it is not helpful that the css-styled-content setting in the extension manager has an option that states that positions like "in text, right" are considered obsolete. Yes, surely a fairly modern web site would create such positions with css, but if you're "just" upgrading an older installation to make sure it'll continue to receive support, you don't want to make changes to image placements, especially if you have thousands of records (not in this sample site). Interestingly no one I contacted had any issues with image resizing and the position modes, so maybe that's rather exotic, but chewed a great deal on my nerves.

In the install tool there is a option

[FE][activateContentAdapter] = 0
Boolean: TYPO3 Front end can transform tt_content and pages records using FAL back to into a format like DB records have been in pre 6.x, so legacy Typoscript can work with it. WARNING: THIS IS SLOW!

which is set to "1" if you're updating from a 4.5 install. Keep an eye on that - if your site does nothing fancy with TS and IMAGE records, set this to "0".

The first attempt to solving the render issues was to include not the "css-styled-content" static TS in my root TS-template, but the legacy "css-styled-content (4.5)". This resulted in a very funny effect: suddenly the first image found on the site (happened to be the logo) was displayed everywhere a image should be displayed.

So that's it for the moment -- if you plan to update your TYPO3 4.5LTS install to 6.2LTS, maybe this helps a little. If you encountered similar or totally different problems or have tips to share: I'm looking forward to your comments :-)

Article update - 17.2.2015

I just stumbled over an issue with language and the formhandler extension. The site is set up to use German as the "default" FE language and an English translation. This is reflected in TypoScript

config {  
 linkVars = L
 uniqueLinkVars = 1
 sys_language_uid = 0
 language = de
 locale_all = de_DE
}
[globalVar = GP:L=1]
config {
 sys_language_uid = 1
 language = en
 locale_all = gb_UK
 htmlTag_setParams = lang="en"
}
[GLOBAL]

Formhandler encourages usage of a language.xml file somewhere outside of the extension directory, so that the texts are not overwritten by an update of the extension.

As it turned out, I had an error in my language.xml that had no consequences prior to the update to 6.2, but gave me some head-scratching: Assuming from the above TypoScript setup I wrongly reasoned that now my "default" language is - german.

So I put all my german texts under the language key "default" in the language.xml, and the english texts under the key "en".
In 4.5, everything worked as expected, L=0 showed the german form, L=1 the english. In 6.2 however, the english texts wouldn't show - only the german texts were displayed, in either language. The language switch by itself worked, I put some debugging in the TypoScript and yes, where I expected the english form to be seen, but the german one showed, the language was correctly switched to "en".
Hm. Ok, so I changed the language keys in the language.xml, from "en" to "default" and from "default" to "de", and -- tadaadaa -- it worked. Of course it took me quite some time before I opted for this approach. Sigh.

Finally I changed the TypoScript to

[globalVar = GP:L=1]
config {
 sys_language_uid = 1
 language = default
 locale_all = gb_UK
 htmlTag_setParams = lang="en"
}
[GLOBAL]

although it already worked, but since "default" works as a fallback if the desired language key has no entry and I now don't have a "en" key in the language.xml, this might reduce some unneccessary overhead.

Seems like the 6.2 version is more strict about the handling of "en" language keys, maybe ignoring them because by convention "default" _is_ english?

Slightly related, due to formhandler being a not-so-recent extension, it uses the old way for language handling, a language.xml file with several language/translations inside. As I was reminded by Joshi Kuphal (@jkphl), there is another way of handling translations, via XLIFF files, but this currently has an issue that could make keeping update-safe translations quite challenging.