5 Tips for a Successful Plone 5 Upgrade

Here are our top 5 tips and advice for a successful Plone 5 upgrade:

1. Check for Add-on Compatibility

The trickiest part of any Plone 5 migration has to do with making sure that the add-ons that were installed and used in the previous site are available in Plone 5. If they're not, one option is to upgrade the add-on. Another option is to remove that content and uninstall the product before performing the migration.

2. Pay Attention to the Order of your Template Migration Steps

It's better to upgrade your theme to Diazo before trying to upgrade your site to Plone 5. We don't recommend trying to do this at the same time.

If the site's theme had previous overrides on templates, you'll have to go piece together what the original version of that template looked like in the version of Plone that you were coming from and then look at the new template in Plone 5, and see how to merge those together so you can retain your customizations and have everything working. In some cases, that can get a little hairy depending on the changes that happened in Plone in the intervening time.

Last but not least: continue to move away from using portal skins, as they will be removed from Plone in the future.

3. Leverage Existing Tools for Custom Content Types

Good news: if you are still using Archetype-based content types on Plone 4, the automatic migration of the existing Plone content types over to the Dexterity equivalents is very smooth. We didn't have to do a lot of work manually to get that to work well.

Another cool thing is that the collective.contentleadimage is an out-of-the-box available behavior in Plone 5 and if you were using it on Plone 4, that migration also works well. Make sure that the XML for the types that are using it have it enabled as a behavior before migrating to Dexterity.

We have found that it can be helpful to install plone.app.contenttypes in the legacy Plone 4 site before going to Plone 5 so as to help with the migration. This is another project you might want to undertake separately before upgrading to Plone 5, but if you have minimal custom content types, it would probably be okay to do it at the same time.

Be sure to use the form provided by plone.app.contenttypes, @@custom_migration, that tells you whether a type has been extended or not and allows you to choose which types to migrate to Dexterity if you are not ready to do them all.

4. Run Checks Before Running the Upgrade

Before running the migration, you may have to update the portal catalog, do a clear and rebuild, and even do an update on the reference catalog.

Also, keep in mind that, if you are having trouble doing the whole migration in an upgrade step, you may have to do it manually through the web interface.

The Plone API also helps with upgrade steps but making it easier than ever to script necessary changes to the portal or content. Plone API is your friend.

5. Get Help

Finally, it is recommended to consult the Upgrade Guide on plone.org. It offers lots of good information about items you might need to be aware of before you go down the upgrade path, such as backing up your instance and testing the upgrade on a staging instance.