Comment 7 for bug 1352550

Another idea, how about a step-program here.

1. Update docs & examples (code and otherwise) to ensure it shows upgrade() occurring.
2. Create prepare method() - have upgrade() call prepare() - mark upgrade() as deprecated (doing something like being done in https://review.openstack.org/#/c/102091/12/taskflow/utils/deprecation.py)
3. In version N + 1, remove upgrade() and adjust docs and examples again to reflect prepare().