This guide has been shamelessly copied from the Ubuntu Wiki. Please improve and adapt it for Gentoo!
With KDEPIM-4.6 and later, KDE's Personal Information Management suite, Kontact, has seen a major move to the new Akonadi system. This will mean any users of previous versions of of the PIM software will need to have their data migrated to the new system. This includes contacts from KAddressBook, events from KOrganizer, and email messages and accounts from KMail. Unfortunately, this process does not work automatically at this time, and may not be 100% successful when it is performed manually.
On the initial startup of the new KDE PIM suite, the address book and calendar data will be migrated automatically.
Note that the new akonadi backend does not absorb the raw e-mail data. So if the database gets corrupted, you will not lose all of your precious e-mails. (It does, however, contain the disconnected imap cache.) See this KDE Akonadi blog post for more details.
If you plan to upgrade, please set your akonadi backend to mysql beforehand, since that is the best-supported backend (and since some people claim it's the only one that really works with kmail-4.10).
The move to KMail2 means that email accounts and information are now also using Akonadi's storage and data system. The migration process for this will occur when KMail or Kontact is first run, and can be skipped for those who prefer to create their accounts manually. Unfortunately, at this time, the migration tool does not properly run when you select the Migrate option, see Launchpad bug #857828
For this reason, it is highly advised that users back up their PIM data before running KMail after upgrading. It also may be advisable for some to skip the migration process and recreate their accounts from scratch.
To back up your data, make copies of these files and folders:
- ~/.kde4/share/apps/kmail - This is where your emails are stored.
- ~/Mail - Used by (very) old Kmail versions. (Still used when found).
- ~/.kde4/share/apps/korganizer - Your calendar data is here.
- ~/.kde4/share/apps/kabc - Contacts are kept here.
With these saved folders, it will be possible to import the data into Kontact should the need arise.
These are the basic config files for the various Kontact applications.
More information on what you may want to back up can be found here, but with the folders listed above, you will be able to import things back into Kontact if necessary.
If you have already attempted to run the migrator and it failed, you can re-run it manually by first deleting your ~/.kde4/share/config/kmail-migratorrc file and your ~/.kde4/share/config/kmail2rc file. Then you will need to run the migrator manually by hitting Alt + F2, and entering the following:
The program will run, and all your accounts and mails will be moved over to the Akonadi system.
When KMail2 opens, you will notice a few things:
- Your accounts will no longer have the personalized names you have assigned to them. You can edit these from KMail's accounts section under Settings → Configure Kmail.
- Email filters are not transferred.
- Spam Filtering does not automatically move mail to the selected spam folder.
- On some disconnected (cached) IMAP accounts, many error popups may occur, though the mail is updated properly. Switching off disconnected mode does not fix the issue, but deleting the account and recreating it as a normal IMAP account should clear the error messages. (Launchpad bug #872478).
- Mail in your Local Folders (and others) may not appear initially. You may have to right-click on the Local Folders icon and select Update folder and its subfolders, or wait until Kmail refreshes itself.
Importing Email Manually
If you choose to skip the migration and enter your account information manually, it is very easy to import your saved KMail folders.
Go to File → Import Messages. In the dialog that opens, select Import KMail Maildirs and Folder Structure, and browse to where you backed up your ~/.kde4/share/apps/kmail folder. Follow the prompts to finish the process. If you have mail folders in a different format than the standard Kmail Maildir, choose the appropriate option in the Import dialog.
If you need to import your calendar, you would go to Kontact's Calendar section, select File → Import → Import calendar, and browse to where you saved your ~/.kde4/share/apps/korganizer and select the std.ics file there, as well as any others you may have.
For contacts, the process is similar: go to Contacts, then File → Import → Import vcard , and browse to where you saved ~/.kde4/share/apps/kabc, and select std.vcf, as well as any other .vcf file you may have.
- Akonadi Troubleshooting
- kmail terminates during startup with “Failed to fetch the resource collection”
Downgrading to 4.4 again
In general, version downgrades are not supported (both by upstream KDE and by Gentoo) and can lead to arbitrary chaos. Here is a procedure that works, however, it just deletes all your local (mail, calendar, address book, ...) data. If you only use server-side (e.g. Google calendar, IMAP mail folders) data, that may be fine, but please be extra careful in any case.
If you have tried out KDEPIM-4.7 and decide that you'd rather go back to KDEPIM-4.4, well, here's what I (dilfridge) did. Basically you have to delete the entire KDEPIM configuration and application data and start from scratch.
- Quit all KDEPIM applications
- Stop akonadi:
- Get the mask file and place it in your /etc/portage/package.mask
- Remove all KDEPIM applications the brutal way:
emerge -aC akonadiconsole akregator blogilo kabcclient kaddressbook kalarm kdepim-common-libs kdepim-icons kdepim-l10n kdepim-kresources kdepim-meta kdepim-strigi-analyzer kdepim-runtime kdepim-wizards kjots kleopatra kmail knode knotes konsolekalendar kontact korganizer ktimetracker
- Remove all your KDEPIM files (configuration, mail data, akonadi database) (either delete it or move it out of the way to import it later again, warning: loss of data):
- Re-emerge all KDEPIM applications, now in version 4.4
emerge -a kdepim-meta
- Better log out of KDE and back in again to make sure all traces of the old, new version are gone
- Start reconfiguring your stuff...
Migrate to alternative Calendar/Addressbook
As an alternative, one can migrate to Thunderbird/Lightning for PIM needs. (Single app solution without the Akonadi/Nepomuk mess, modern and sufficiently robust)
- Export your addressbook as a LDIF file from KAddressbook
(If you are already hosed, take your previously backed up .vcf file(s) and convert them to LDIFs using http://labs.brotherli.ch/vcfconvert/ ; install php and run the script locally).
- Export your Calendars as .ics files from KOrganizer (or copy from ~/.kde4/share/apps/korganizer/*.ics)
emerge --ask mail-client/thunderbird
- Import your ics and ldifs to Thunderbird and be happy again.