Author: Ross Patterson



This package provides helpers for upgrading CMF portals, such as Plone
sites, supporting incremental commits, upgrading multiple portals at
once, and a command-line script for upgrading scripts outside the
browser with post-mortem debugging of errors.  Together, these
features greatly reduce the amount of time spent on each iteration of
developing your upgrade steps.

Also included are a number of upgrade steps for cleaning up messy
portals during upgrades including cleaning up broken objects,
components and registrations.

.. contents::


Use of this package will immediately commit changes to your ZODB.
There is no "dry run" option as that is contrary to it's purpose.  As
such, it should *never* be used on a ZODB that has not been backed up
along with the BLOBs *immediately before* use.  Neither should it be
used directly on production as a first attempt at upgrading portals.  

Quick Start

In a buildout with::

    recipe = plone.recipe.zope2instance
    eggs = ...

Add another part like so::

    parts =

    eggs = ...
    http-address = localhost:8080

    recipe = zc.recipe.egg
    eggs = ${instance1:eggs}
    scripts = upgrade-portals
    arguments = args=[
        '--zope-conf', '${instance1:location}/etc/zope.conf',
        '--log-file', '${buildout:directory}/var/log/upgrade.log']

Then, after running buildout, you can upgrade all Plone portals and
their add-ons and monitor the progress in ``var/log/upgrade.log`` with::

    $ bin/upgrade-portals

Alternatively, you can open the following URL in your browser to
upgrade all portals and the logs of progress will be streamed to
your browser::


Use the ``--help`` option for more details::

    $ bin/upgrade-portals --help
    usage: upgrade-portals [-h] [-l FILE] [-z FILE] [-d] [-U] [-G PROFILE_ID] [-A]
                           [PATH [PATH ...]]
    Upgrade CMF portals in a Zope 2 application using GenericSetup upgrade steps
    positional arguments:
      PATH                  Run upgrades for the portals at the given paths only
                            (default: upgrade all CMF portals in the Zope app)
    optional arguments:
      -h, --help            show this help message and exit
      -l FILE, --log-file FILE
                            Log upgrade messages, filtered for duplicates, to FILE
      -z FILE, --zope-conf FILE
                            The "zope.conf" FILE to use when starting the Zope2 app.
                            Can be omitted when used as a zopectl "run" script.
      -d, --disable-link-integrity
                            When upgrading a portal using,
                            disable it during the upgrade.
      -U, --skip-portal-upgrade
                            Skip running the upgrade steps for the core Plone
                            baseline profile.
      -G PROFILE_ID, --upgrade-profile PROFILE_ID
                            Run all upgrade steps for the given profile (default:
                            upgrade all installed extension profiles)
      -A, --skip-all-profiles-upgrade
                            Skip running all upgrade steps for all installed
                            extension profiles.

Incremental Commits

Since upgrades are often long running, restarting the upgrade on every
error can make troubleshooting and debugging extremely time
consuming.  It's also unsafe, however, to commit the results of an
upgrade that failed in the middle since there's no way to guarantee of
cleanup the partial execution of an upgrade step.

Fortunately, the upgrade step support for ``Products.GenericSetup``
profiles provides a good way to incrementally commit upgrade progress
in a way that much less risky and can save a lot of time in the
upgrade troubleshooting and debuggin