ftw.upgrade

HomePage: https://github.com/4teamwork/ftw.upgrade

Author: 4teamwork GmbH

Download: https://pypi.python.org/packages/source/f/ftw.upgrade/ftw.upgrade-1.7.3.zip

        Introduction
============

This product aims to simplify running and writing third-party Generic Setup
upgrade steps in Plone.

It provides a control panel for running multiple upgrades
at once, based on the upgrade mechanism of Generic Setup (portal_setup).

Further a base class for writing upgrade steps with a variety of
helpers for common tasks is provided.

.. contents:: Table of Contents

.. figure:: http://onegov.ch/approved.png/image
   :align: right
   :target: http://onegov.ch/community/zertifizierte-module/ftw.upgrade

   Certified: 01/2013


Features
========

* **Managing upgrades**: Provides an advanced view for upgrading
  third-party Plone packages using Generic Setup.
  It allows to upgrade multiple packages at once with an easy to use user
  interface.
  By resolving the dependency graph it is able to optimize the upgrade
  step order so that the upgrade is hassle free.

* **Import profile upgrade steps**: Some times an upgrade step does simply
  import an upgrade step generic setup profile, especially made for this
  upgrade step. A new ZCML directive makes this much simpler.

* **Writing upgrades**: The package provides a base upgrade class with
  various helpers for tasks often done in upgrades.


Installation
============

- Install ``ftw.upgrade`` by adding it to the list of eggs in your buildout.
  Then run buildout and restart your instance:

.. code:: ini

    [instance]
    eggs +=
        ftw.upgrade


- Go to Site Setup of your Plone site and activate the ``ftw.upgrade`` add-on.


Compatibility
-------------

Plone 4.1

.. image:: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.1.x.cfg/badge/icon
   :target: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.1.x.cfg

Plone 4.2

.. image:: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.2.x.cfg/badge/icon
   :target: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.2.x.cfg

Plone 4.3

.. image:: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.3.x.cfg/badge/icon
   :target: https://jenkins.4teamwork.ch/job/ftw.upgrade-master-test-plone-4.3.x.cfg



Manage upgrades
===============

The ``@@manage-upgrades`` view allows to upgrade multiple packages at once:

.. image:: https://github.com/4teamwork/ftw.upgrade/raw/master/docs/manage-upgrades.png



Import-Profile Upgrade Steps
============================

Sometimes an upgrade simply imports a little generic setup profile, which is only
made for this upgrade step. Doing such upgrade steps are often much simpler than doing
the change in python, because one can simply copy the necessary parts of the new
default generic setup profile into the upgrade step profile.

Normally, for doing this, one has to register an upgrade step and a generic setup
profile and write an upgrade step handler importing the profile.

ftw.upgrade makes this much simpler by providing an ``importProfile`` ZCML direvtive
especially for this specific use case.

Example ``configure.zcml`` meant to be placed in your ``upgrades`` sub-package:

.. code:: xml

    <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:upgrade-step="http://namespaces.zope.org/ftw.upgrade"
        i18n_domain="my.package">

        <include package="ftw.upgrade" file="meta.zcml" />

        <upgrade-step:importProfile
            title="Update email_from_address"
            profile="my.package:default"
            source="1007"
            destination="1008"
            directory="profiles/1008"
            />

    </configure>

This example upgrade steps updates the ``email_from_address`` property.

A generic setup profile is automatically registered and hooked up with the
generated upgrade step handler.

Simply put a ``properties.xml`` in the folder ``profiles/1008`` relative to the
above ``configure.zcml`` and the upgrade step is ready for deployment.



Upgrade step helpers
====================

The ``UpgradeStep`` base class provides various tools and helpers useful
when writing upgrade steps.
It can be used by registering the classmethod directly.
B