Developer's Guide
As noted, your migration code will subclass migrate.Migrate.Step. You can stub your migration file out like this:
__doc__='''My migration code'''
from Acquisition import aq_base
import Migrate
class MyMigrateCode(Migrate.Step):
version = Migrate.Version(1, 1, 0)
# The above needs to be updated to the appropriate version
# ie a version above the previously-released version of Zenoss
def cutover(self, dmd):
pass
MyMigrateCode()
You will need to do the following to this code:
Fill in the doc string
Update the version passed to Migrate.Version
Update the
cutover()method with actual codeAdd any supporting code you might need that doesn't strictly belong in
cutover()
Implementation is very straight-forward: you get the dmd object passed into the cutover() method, thus giving you access to nearly every part of Zenoss. The only thing you don't have direct access to is the portal object. But you can easily get that by calling dmd.getPhysicalRoot().
Implementation details are 100% dependent upon what part of Zenoss you are migrating -- if you look at the current migration scripts (in trunk), you will get a good sense of the diversity as well as many examples from which to work.
Changes made to the ZODB database (dmd and associated objects hierarchies) are committed back to the database unless the --dont-commit flag is passed to zenmigrate. The --dont-commit lets the developer repeatedly run a script and debug without making permanent changes to the database. If your migrate script makes changes outside of the Zope database it should probably implement Step.revert() to undo any changes it has made.
Supporting code is just modularization. If you're going to be using a function (or method) more than once, just break it out of the cutover() method. This will make maintenance easier and will allow those who come after you to see the intent of the migration code more quickly.
Once your code meets with your approval (and that of the Zenoss development team), you are free to name it something appropriate and save it to Products/ZenModel/migrate. Upon adding your migration module, you must now edit Products/ZenModel/migrate/__init__.py so that it gets imported when zenmigrate.py is run.
After adding your script (and after every change you make to your new script), be sure to run zenmigrate run. Here are some things you can do to help ensure quality:
Load Zenoss in a web browser, and navigate to the part of the application that was impacted by your migration script
Look at the log files for error output
Load up zendmd from the command line and make sure that no errors are generated when using the part of the API impacted by the change
After someone reviews the changes, your migration code is ready for deployment.