Philip Bauer: How to upgrade sites to Plone 5

published Oct 15, 2015

Talk by Philip Bauer at the Plone Conference 2015 in Bucharest.

This is part two of a talk I did in the Brazil conference two years ago. Recap:

  • Every non-trivial upgrade should be approached as a relaunch. Look at content, site structure, design, underlying packages, different languages to use in the site.
  • The primary challenge is not development, but communication and project management. It is not just a new version number.
  • Bring time. And space. You need to do all steps multiple times. Get lots of disk space. Keep several copies of the database so you do not have to start over at point 1 again.
  • Expect everything to break. Templates, python files, add-ons, etc.
  • Don't experiment, document. Write every problem and solution down. It is not done, you have just done it on a test migration on your laptop, you will have to do it later on the live site again.
  • Write your code as if your own kids will inherit the code one day. You don't want them to hate you. You need to understand what it does one year from now.
  • Write upgrade-steps in your add-ons, so you can just run it and not have to do all kinds of stuff manually.
  • Divide and conquer. Once one step works, commit the changes and make a copy so you can worry about the next step without worrying about the old steps.
  • Don't try more than two new technologies at once.
  • Use the help. Use plone.api. Use ftw.upgrades, several nice helper steps.

Now upgrades from Plone 4 to 5.

Why would you want to migrate? Why would the client want it? Do you simply want to play with shiny new tools? If the site is running just fine, they can stay on Plone 4. Are there any new things in Plone 5 that they really need or want?

  • Great responsive design out of the box. But they may already have it in Plone 4.
  • Newer TinyMCE? The editor just always has some problems, no matter which Plone version.
  • Security? Hard to sell.
  • Prototyping can be easier, say for dexterity, but how often to you prototype on a live site?
  • New folder contents, new UI: yes, many will like this.

So do not force your client.

Demo of upgrade of small site. Includes optional upgrade from Archetypes to Dexterity content types.

You lose one thing: the content history, so the CMFEditions revisions. That is really hard to do.

Demo worked fine. It can't be that easy, right? When the old site has lots of configuration and installed add-ons, it gets trickier. Many add-ons still need changes.

  • LinguaPlone is hard to get rid of. You need to migrate this to 1.x in Plone 4 already.
  • Theming is tricky. I got an error when trying rendering anything. I saw I had to install manually.

Use PDBDebugMode to debug tracebacks.

Please work on problems like this, document problems, fix problems, report them.

Read the upgrade guide and work on it during this sprint: We will upload this to a Google doc so more people can work on it this weekend and get it properly integrated later.

Disable your custom theme before migrating, otherwise it will break. Use the new Barceloneta diazo theme as basis and work from there.

Archetypes content types will still work just fine, maybe some less nice widgets in editing. You should migrate to dexterity.

Move everything to the portal registry. All settings are there. So no longer set something in for example the portal_properties.

Before you work on your custome code:

  • Figure out if you still need it, maybe the problem it tried to solve is already gone.
  • Use plone.api for anything you write new or that you change.
  • Formlib is kind-of gone. Custom forms should be done with z3c.form.
  • Portlets are also moved to z3c.form.
  • Check any templates that you override, take over changes, or remove the override.
  • For custom migrations from Archetypes to Dexterity, look at these views: pac_installer, atct_migrator, migrate_from_atct, custom_migration.