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

[Maurits van Rees]

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?


Warning: I am quite lengthy below in describing my (mis)understanding
of upgradeSteps.  Do not continue reading if you are already
sleepy. ;-)

I am testing it in a fresh Plone 3.0 site.  So that makes it CMF-2.1.0
and GenericSetup-1.3.1.


Expectation
-----------

The way I expect/hope to use upgradeSteps in add-on products is:

- Have one default GS profile for first time installs.

- Have one or more upgradeSteps to go from an old to a new version.

Perhaps a new version of portal_quickinstaller (or a clever
Extensions/install.py of a product) could then apply the default
profile when installing the product and could apply the correct
upgradeSteps when _re_installing.


Example
-------

- I release version 1.0 of my testupgrade product.  In
  profiles/default it has this catalog.xml (some lines omitted for
  clarity):

 <index name="goodName" meta_type="FieldIndex" />
 <index name="wrongName" meta_type="FieldIndex" />

- Alex installs version 1.0 of testupgrade by applying the GS profile.

- I spot an error in my product: one of the indexes it adds is wrong.
  In profiles/default I fix this:

 <index name="goodName" meta_type="FieldIndex" />
 <index name="betterName" meta_type="FieldIndex" />

- For people like Alex I supply an upgradeStep to fix this in their
  site.  This step consists of a profile in profiles/upgrade_10-15/
  with this catalog.xml:

 <index name="secondField" meta_type="FieldIndex" remove="True"/>
 <index name="thirdField" meta_type="FieldIndex" />

- With these fixes I release version 1.5 of testupgrade.

- Alex fixes his catalog by applying the upgradeStep.

- Betty is a first time user and installs version 1.5 by applying the
  install profile.

Is something like this possible with the new upgradeSteps?


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.

   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.

   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?


I hope someone can shed some light on my clouded vision of how the
upgradeSteps are supposed to work.  Examples would be great. :)

-- 
Maurits van Rees | http://maurits.vanrees.org/ [NL]
            Work | http://zestsoftware.nl/
"Do not worry about your difficulties in computers,
 I can assure you mine are still greater."