I have migrated several sites from Plone 4.1 to Plone 4.3.3 this week. I am in the fortunate position where I help maintain many Plone sites, most of them being more than 6 years old. Fortunate because it helps learn a lot, over the years, on the good and the bad in terms of content management practices.

One of the things I like is that, nowadays, with the right methodology, you can always upgrade your Plone site with confidence.

Here is the general routine, that you can adapt to your particular situation:

1. As a preparation, make sure you do some cleaning on the old Zope instance, removing contents and configuration objects that may cause trouble during the upgrade. Of course that requires some experience of how things work on old Plone sites and new ones, and doing some analysis of what's in your site. Then, confronting the result of that analysis to the list of potential pitfalls.

   Let's face it! This generally does not happen because of time constraints in projects and the difficulty for the webmasters to do that analysis themselves. That said, it could/should be done within an audit phase before the upgrade work is planned.

2. Set up the new Zope instance with the right buildout configuration, making sure that most of the needed add-on packages are installed.

3. Copy over the data files (mainly var/filestorage/Data.fs and var/blogstorage) to the new instance.

4. Start the Zope server instance in foreground mode, i.e. using bin/instance fg, and see how it goes.

5. If the Zope server instance script throws an error and stops, most of the time, at this point, you have something to fix at the buildout level (i.e. the software installation, not the database or the application configuration).

   What you do here is analyze the error messages to quickly get a clue of add-on packages or Python libs that may be missing. If needed, look for how others have solved the issue (Google is your friend).

   Then fix your buildout configuration, update the installation, and start the Zope server instance again with fg. And so on...

   If you get an error related to an add-on or dependency package you just added to the buildout, you probably need to get a compatible version of the package. If possible, check the configuration of the old instance to get the version number, or just bet on an older version and try it. Pin that version in your buildout.

   For example, you might need to adapt your buildout configuration as follows, by adding an old version of the collective.easyslider package:

    ...
   
    [instance]
    ...
   
    eggs +=
        collective.easyslider
   
    [versions] 
    collective.easyslider = 1.2.0
   

6. Now, let's suppose Zope is starting without error. You can see the state of the objects stored in the persistent store aka the ZODB, using the Zope Management Interface, by pointing your browser to the right URL (i.e. /your-plone-site/manage). Here you may still get nasty errors making the instance unusable (related to the registered Zope interfaces or utilities), or discover that some objects are broken (i.e. there is no code behind the object, or the code does not provide what's needed, to make it work with its complete state).

   So back to verifying the buildout! Check the error messages in the Zope console to find out what's missing, and make sure it gets installed via buildout or in the Python environment (for Python libs).

7. The next thing you have to do is run the upgrade script on the Plone site(s) hosted on that Zope instance.

   • Run it first with the "dry run" option, i.e. for testing purpose. Do not worry, you may still have surprises, which is good for the hacker in you. Would not be interesting if it was too easy, right?

   • The upgrade script may stop its course because it ends up executing something that has a dependency on some package, Zope interface, or persistent configuration data. In which case, you first go back and fix the buildout with the right version of the missing package, or you manually fix the site's configuration by analyzing things in the ZMI.

   • Once the "dry run" or test mode has confirmed that the Plone site can be upgraded successfully, you re-run the upgrade script in the normal mode. As a result, the script's modifications will now be written to the database, and without risk since you have now fixed 95% to 99% of the potential issues (well, I hope for you :)).

8. After the site is upgraded, it needs some manual cleanup and adjustments, while you proceed with the initial user tests.

   Generally, what I happen to do:

   • Go to portal_setup, on the Upgrades tab, and run the upgrade steps for the Products.TinyMCE add-on. This fixes the issue where the TinyMCE widget is not enabled when trying to edit content.

   • Get the old "TTW customizations" out of the way, until I have tested the site and made sure it is technically working: Just create a portal_skins/custom/OLD folder and move there all existing stuff in portal_skins/custom. Later, I may move back the customized code that still makes sense, and adjust or refactor them to file system code. Same for the portal_view_customizations-based customization code, disable stuff there unless they are really needed, and encourage we move to file system-based packages for the needed customizations from now on.

Additionally, some problematic migrations may require rebuilding the catalog. Also sites with multilingual contents (LinguaPlone) may bring new difficulties, and in this case, you might have to rework things using the plone.app.multilingual framework.

For more information:

• Some upgrade tips
• Plone upgrade guide