summary for the impatient

• don't rely on kmail-migrator to migrate old ~/Mail directories
• export archives of every folder with kmail1 before the upgrade
• import the archives into kmail2 after the upgrade

en detail

i've been using kmail since KDE 1.x, so i can only guess that it was the format of my mail folder which caused these troubles. to spare you these, do yourselves a favour and follow these precautions:

before upgrading to kmail2

1. look at your current mail folder. if it's still ~/Mail and you find things like ".folder_name.index" and ".folder_name.index.ids" in there, but no "cur", "new" and "tmp" folders, you might really want to go on following these steps.
2. backup your mail folder (tar cjvf Mail_backup_$(date --rfc-3339=date).tar.bz2 Mail). this is the just-in-case backup, you can lock it away, we won't use it for the migration. i've tried to import this folder directly and ended up with the correct folder structure, but each folder contained exactly one huge "e-mail" with all correspondence that was in there.
3. open kmail and create an archive from each folder (look for it in the folder context menu). this is the backup we'll be feeding to kmail2. archiving a folder will automatically transform its content into a maildir structure that kmail2 understands. you might also backup other kontact related config files, but i didn't need that

upgrade and (failing) migration

now you can do the upgrade. when you launch kmail2 for the first time it will invite you to migrate your data. go ahead an try it, maybe you're lucky. for me that failed immediately, telling me i could call kmail-migrator --interactive manually. so i did. what it didn't tell me was that i had to get rid of $(kde4-config --localprefix)/share/config/kmail-migratorrc first, otherwise the tool believes it already succeeded and just won't run again. thank you.

the good news is that at least for me all my account information and mail filters were migrated correctly (for as far as i see). but as i said before, the imported kmail folders turned out to be useless, bombarding me with error messages until pulse audio gave up on the dongs and i had to kill knotify4 repeatedly after it froze and ate up all CPU time. so here comes the real work:

after upgrading to kmail2

1. shut down kmail, in case it's running.
2. look for akonadi in your control bar and open it for configuration. find the "kmail folders" akonadi resource and delete it again. that will not delete the actual mails, but only let akonadi forget they exist, hence kmail won't remember them either.
3. start kmail. it will probably complain about the removed resources because your mail accounts were configured to deliver fetched mails there. but it will also inform you it'll be using the local inbox now, i.e. you can hit "ok".
4. open "file" → "import messages", choose to import kmail archive files.
5. set the local folders as destination, hit "next" and open the first of the folder archives you created earlier. and then wait. i.e., i had a backup folder with about 60.000 old mails, it took kmail several hours to finish the import.
6. repeat the last step for each archive (after each import, you can go back and import the next one). be careful if you also archived folders with special names like "inbox" or "drafts", don't import them to the root of local folders but a subdirectory. also be aware that, depending on the archive size, this import can use up vast amounts of memory -- for the 60.000 mails archive it swapped 2GB when my 4GB of physical RAM ran full.

even after the import seems finished, it might take akonadi and nepomuk some more ages to digest (btw, if nepomuk crashes all the time, try to rename/remove $(kde4-config --localprefix)/share/apps/nepomuk/). i also had to mark most of the imported messages as read again (hint: folder context menu), and of course check all mail filter rules, since their destination folders have now changed.

however

it seems mail filters don't apply to POP3 accounts. that's great, more quality time with sorting my correspondence. and from what i can tell nepomuk is still a massive drain on resources. i consider this not only a pitty and at times depressingly annoying, because what used to feel like a fluid deskop experience turned into a stop-and-go patience test over night. but also i'm asking myself if this is the free software community's "f**k you" message to green IT propaganda... anyway, i still hope this helps a little, so you can all see for yourself.

update [2011-10-17]

to my knowledge the whole akonadi/nepomuk voodoo was initiated partly because kmail1 couldn't handle huge amounts of mail anymore. let's forget about the fact that it was significantly quicker at accessing the 60.000 old mails than kmail2 (which actually goes to sleep from time to time, saying it's fetching folder contents, and forgets to come back). so right now i wanted to see if at least a fulltext mail search has improved noticeably. what can i say... it doesn't work at all anymore! well, that was really worth it.