Upgrading Plone from version 2 to version 3

First, a little bit of background.  I run a production Plone server installed on a Debian testing box (the one serving this webpage).  The Debian Plone package jumped from 2.5.2 to 3.0.3.  I tried to do an initial migration and ran into a bunch of error messages.  By the time I finally got around to triaging them Plone 3.0.5 was in unstable, so I grabbed it.

The initial error message that I received looked something like this:

    * Module ZPublisher.Publish, line 119, in publish
    * Module ZPublisher.mapply, line 88, in mapply
    * Module ZPublisher.Publish, line 42, in call_object
    * Module Shared.DC.Scripts.Bindings, line 313, in __call__
    * Module Shared.DC.Scripts.Bindings, line 350, in _bindAndExec
    * Module Products.CMFCore.FSPageTemplate, line 216, in _exec
    * Module Products.CMFCore.FSPageTemplate, line 155, in pt_render
    * Module Products.PageTemplates.PageTemplate, line 89, in pt_render
    * Module zope.pagetemplate.pagetemplate, line 117, in pt_render
    * Module zope.tal.talinterpreter, line 271, in __call__
    * Module zope.tal.talinterpreter, line 346, in interpret
    * Module zope.tal.talinterpreter, line 891, in do_useMacro
    * Module zope.tal.talinterpreter, line 346, in interpret
    * Module zope.tal.talinterpreter, line 536, in do_optTag_tal
    * Module zope.tal.talinterpreter, line 521, in do_optTag
    * Module zope.tal.talinterpreter, line 516, in no_tag
    * Module zope.tal.talinterpreter, line 346, in interpret
    * Module zope.tal.talinterpreter, line 891, in do_useMacro
    * Module zope.tal.talinterpreter, line 346, in interpret
    * Module zope.tal.talinterpreter, line 586, in do_setLocal_tal
    * Module zope.tales.tales, line 696, in evaluate
      URL: file:C:\Program Files\Plone 3\Data\Products\CMFPlone\skins\plone_templates\global_defines.pt
      Line 8, Column 0
      Expression: <PathExpr standard:u'plone_view/globalize'>
      Names:

      {'container': <PloneSite at /Plone>,
       'context': <ATDocument at /Plone/front-page>,
       'default': <object object at 0x0060A528>,
       'here': <ATDocument at /Plone/front-page>,
       'loop': {},
       'nothing': None,
       'options': {'args': ()},
       'repeat': <Products.PageTemplates.Expressions.SafeMapping object at 0x06F1AF08>,
       'request': <HTTPRequest, URL=http://localhost/front-page/document_view>,
       'root': <Application at >,
       'template': <FSPageTemplate at /Plone/document_view used for /Plone/front-page>,
       'traverse_subpath': [],
       'user': <UnrestrictedUser 'admin'>}

    * Module zope.tales.expressions, line 217, in __call__
    * Module Products.PageTemplates.Expressions, line 161, in _eval
    * Module Products.PageTemplates.Expressions, line 123, in render
    * Module Products.CMFPlone.browser.ploneview, line 68, in globalize
    * Module Products.CMFPlone.browser.ploneview, line 133, in _initializeData
    * Module Products.CMFPlone.browser.ploneview, line 520, in have_portlets
    * Module plone.portlets.manager, line 49, in visible
    * Module plone.portlets.manager, line 65, in portletsToShow
    * Module plone.memoize.view, line 55, in memogetter
    * Module plone.portlets.manager, line 102, in _lazyLoadPortlets
    * Module plone.portlets.retriever, line 55, in getPortlets
    * Module plone.app.portlets.portletcontext, line 45, in globalPortletCategories
    * Module plone.app.portlets.portletcontext, line 81, in _getGroupIds
    * Module Products.PlonePAS.pas, line 183, in getGroups
    * Module Products.CMFCore.utils, line 123, in getToolByName 

AttributeError: portal_groups

My exact error text was different.  But searching for it led me to the site linked above, from which I copied the text.  After upgrading to 3.0.5 my errors now say:

Starting the migration from version: 2.5.2 
 Attempting to upgrade from: 2.5.2 
 Upgrade aborted 
 Error type: exceptions.AttributeError 
 Error value: mimetypes_registry 
 File "/var/lib/zope2.10/instance/plone-site/Products/CMFPlone/MigrationTool.py", line 210, in upgrade newv, msgs = self._upgrade(newv) 
 File "/var/lib/zope2.10/instance/plone-site/Products/CMFPlone/MigrationTool.py", line 321, in _upgrade res = function(self.aq_parent) 
 File "/var/lib/zope2.10/instance/plone-site/Products/CMFPlone/migrations/v2_5/two52_two53.py", line 8, in two52_two53 addMissingMimeTypes(portal, out) 
 File "/var/lib/zope2.10/instance/plone-site/Products/CMFPlone/migrations/v2_5/two52_two53.py", line 19, in addMissingMimeTypes portal.mimetypes_registry.manage_addMimeType('text/x-web-markdown', \ 
 End of upgrade path, migration has finished 
 The upgrade path did NOT reach current version 
 Migration has failed

I figured part of my problem was caused because I was trying to jump too far.  Luckily, I have a Windows box sitting around that I could use as my migration stepping tool.  Windows makes it easy because you can get prepackaged environments for each Plone release and install several at a time.  You can do it in Linux but it's just more work.

My first goal was to migrate to the latest in the 2.5 series, which currently is 2.5.5.  I exported each Plone site at a .zexp and tried to import it into Plone 2.5.5.  However, when I tried that I got an error mentioning something about x-web-markdown.  A quick Google search pointed me to several websites describing the problem.  To fix the problem, log back into the 2.5.2 Zope Management Interface, click on the portal you are trying to migrate, click on "mimetypes_registry," then click the "Add a new MIME type" button in the upper right.  Create the following three mime types

text/x-web-markdown

text/x-web-textile

text/x-web-intelligent

For each one make the name and the MIME type identical and leave the other fields blank.  (Text/x-web-intelligent isn't listed in the website referenced above, but I discovered it became a problem later on when migrating to version 3, so I added it here.)

Once you import the .zexp into Plone 2.5.5, there are three steps remaining to complete the migration.  First, log into the Zope Management Interface and click on the portal.  Click on "portal_migration," "migrate," and then "Upgrade."  Second, go back to the portal and click "portal_atct," click on the "Version Migration" tab, then "Upgrade."  Third, go back to the portal and click the "View" tab.  Once the site loads click "Site Setup," "Add/Remove Products," and reinstall each product that has been upgraded.  If CMFPlacefulWorkflow gives you problems you can uninstall it and reinstall it.  I didn't have any errors with any of the other steps on the five portals that I migrated.

Export the portal into a .zexp file and import it into Plone 3.0.5 (or whatever is currently available).  Versions of Plone earlier than 3.0.4 don't know how to import from 2.5.5.  One of my portals didn't want to import into Plone 3.0.5 running on Debian, but did in Windows.  Go figure.  Once it is imported, there are a few steps left to complete the migration.  Log into the Zope Management Interface and click on the portal.  Click on "portal_migration" then "Upgrade."  Go back to the portal and click the "View" tab.  Once the site loads click "Site Setup," "Add/Remove Products," and reinstall each product that has been upgraded.  If CMFPlacefulWorkflow gives you problems you can uninstall it and reinstall it.

That should be it.  If you have any questions, feel free to drop me an email.