Document Actions
4.1.2.
Writing migrations
Up one level
Migrations take the form of global functions, collected in files created for each version to which migration would be expected. At the time of writing, Plone is at 2.1 alpha 2, and so new migrations should go in CMFPlone/migrations/v2_1/betas.py. Make sure that you select the latest appropriate file when adding new migrations.
In this file, you will notice a method:
def alpha2_beta1(portal):
"""2.1-alpha2 -> 2.1-beta1
"""
out = []
#Make object paste action work with all default pages.
fixObjectPasteActionForDefaultPages(portal, out)
return out
This shows the alpha2-to-beta1 migration method with one migration. At the time of writing, this is the latest migration method, but there will be later ones added shortly, so make sure you use the right one!
The method fixObjectPasteActionForDefaultPages is defined later in the same file. By convention, all migration methods take two arguments, portal - the root portal object, and out - a list to which string trace messages should be appended.
You should make a point to look at existing migrations before writing a new one. As mentioned on the previous page, you cannot make any assumptions about an installed system - people do delete tools and replace them with their own versions (for example CMFMember replaces MembershipTool), customise templates and scripts and generally try as hard as they can to make the life of a poor migration writer hard.
General migration advice
- Unit test carefully (see next page)
- Never assume tools and objects are there.
Always use the third default argument to getToolByName and getattr, for example: portal_membership = getToolByName(portal, "portal_membership", None) or child = getattr(parent, "childId", None). Then, make sure that you test the returned value:
if portal_membership is not None:
...
Notice the explicit test for is not None - the shortcut if portal_membership: is not sufficient.
- Always err on the side of caution - make sure your migration tool is safe to run twice, safe to run when none of your assumptions hold, and will never, ever destroy a user's site!
