[Zope-CMF] Re: GenericSetup: How to use upgradeStep?

[Rob Miller]

Maurits van Rees wrote:
> Hi,
> 
> I am having problems understanding how the new upgradeStep
> functionality of GenericSetup works.   Maybe the most important
> question: is there a product that already uses this, so I can look at
> its code as an example?

don't think so, except for CPS, from which the upgradeStep directive was ported.

<--- SNIP --->

> Problems
> --------
> 
> In a zcml file my upgrade step would like this:
> 
>   <genericsetup:upgradeStep
>       title="Cleanup catalog"
>       description="Remove secondField and add thirdField to portal_catalog"
>       source="1.0"
>       destination="1.5"
>       handler="Products.testupgrade.upgrades.from_10_to_15"
>       sortkey="1"
>       profile="Products.testupgrade:testupgrade-15" />
> 
> If I do not supply a handler, on Zope startup I get:
> 
>     ConfigurationError: ('Missing parameter:', 'handler')
> 
> If I do not supply a profile, on Zope startup I get:
> 
>     ConfigurationError: ('Missing parameter:', 'profile')
> 
> I have two problems here:
> 
> 1. Since this upgradeStep needs a profile I also need to register that
>    profile with another zcml snippet.  I had hoped that I would not
>    need that profile.  Or rather: I had hoped that the upgradeStep
>    snippet would automatically register a profile (maybe by using a
>    name attribute).
 >
>    In the ZMI there is now a notable difference between base and
>    extension profiles.  I had also hoped for such a distinction with
>    respect to "upgrade profiles".  As it is now, the upgradeStep
>    itself is nicely visible on the Upgrades tab, but it needs a base
>    or extension profile as well, which clutters those two lists.

okay, here's where things get off track.  in GenericSetup, there is no such 
thing (yet, perhaps) as an "upgrade profile".  it's possible to define an 
extension profile and to USE it as part of an upgrade process (Plone has been 
doing this), but there's no special profile type that GS knows about.

upgrade steps are not meant to represent simple profile edits.  for those, 
you'd just change the profile and up the profile version number, no need for 
an upgrade step at all.  upgrade steps are needed for more complex situations, 
which cannot be represented as profile edits, and which require custom python 
code.

imagine i have a product, SomethingRad, which has a default GS profile.  this 
GS profile defines a DoesSomethingRad content type; applying this to my site 
creates the new type.

SomethingRad works well, so i release SomethingRad 2.0.  version 2.0 of the 
profile introduces a DoesSomethingElseRad content type.  ideally, the 
GenericSetup and QuickInstaller interfaces would both indicate to me that the 
profile needs to be reimported, b/c the profile version number has been 
incremented since the last import.  no upgradeStep directives are necessary. 
neither is the definition of a new extension profile to represent the upgrade.

now it's time for SomethingRad 3.0.  during this revision i realized that i 
didn't need different content types.  instead, i could just use different 
adapters for regular Document content types.  so when i upgrade from v2.0 to 
v3.0, i need to a) remove the two content types and b) find all existing 
instances of the obsolete content types and convert them into Document objects 
which support the new adapters.  step a) can be accomplished w/ a profile 
edit, but step b) cannot.  so i register an upgradeStep that looks like this:

   <genericsetup:upgradeStep
       title="Remove SomethingRad types"
       description="Removes DoesSomethingRad and DoesSomethingElseRad content 
types"
       source="2.0"
       destination="3.0"
       handler="somethingrad.upgrades.removeSomethingRadTypes"
       sortkey="1"
       profile="somethingrad:default"/>

performing a full upgrade, then, would require reapplying the profile 
configuration and running the upgrade steps.  reasonably the quickinstaller 
(or even the GS interface) could do this all as one step.

>    The current Plone 3.0 already registers four extension profiles
>    using its own upgrade profiles (which I think were meant as
>    temporary measure before the GS upgradeSteps were in place).  I
>    want to avoid that the list of extension profiles gets cluttered
>    with upgrade profiles from every add-on product.

indeed.  ideally there is only one profile per product, which is associated w/ 
a versioned configuration and some set of upgrade steps.

>    But maybe I am missing the correct meaning of the profile in
>    relation to the upgradeStep, as I see a second problem.
> 
> 2. I am a bit surprised that I need both a handler and a profile.  As
>    I understand it, we are supposed to move away from setuphandlers in
>    python code as far as possible and instead do everything with
>    profiles.  In fact, I have hopes that the upgradeSteps make this
>    better possible than in the past.
> 
>    As it is, I see that the code of the python handler correctly gets
>    called.  The profile is not applied though.  I guess I could put
>    code in the handler that actually applies the profile.  But I would
>    hope that the upgradeStep would handle that for me.  So: is the
>    profile attribute of an upgradeStep meant for something else?

hopefully my above explanation helps clarify the intent of the upgradeSteps 
directive.

-r