Phased Upgrade (1)

Description

Legacy module implemented a new spec for module upgrade. In XOOPS2 JP, module developers can't upgrade their module freely, because the update-script spec isn't enough for upgrade step. On module's history, many things are changed. Add a field to DB table, add a new block to the module, rename the callback function and remove resources... XOOPS2 JP have tried to update these information automatically without strict definations. In other words, there are not strict rules. By that, module developers had to explore XOOPS2 JP to get how XOOPS2 JP updates modules.

In Beta 3, Legacy System module introduced the phased upgrade mode like vBulletin. Under this mode, upgrade is limited to the milestone version. For example, there is a module having the following diabolic changelog.

• v0.10 first version. (DB table has 'value' field as varchar(255).)
• v0.20 add a new integer field 'value2' to DB table.
• v0.30 drop a existed field 'value' from DB table.
• v0.35 rename 'value2' to 'value'.

How do you write a callback function for this diabolic changelog? It's not impossible but very difficult. Most programmers don't want to take times to fight XOOPS2 JP bad spec, so drastic changes of modules will be lost.

The Phased Upgrade makes it possible to divide upgrade into plural processes. In this example,

1) v1.0 -> v2.0 upgrade
2) v2.0 -> v3.0 upgrade
3) v3.0 -> v3.5 upgrade

By this way, users can upgrade correctly to the latest version from every versions. And, module developers can prevent automatic uncorrect upgrade feature of Legacy System module.

The Module Update function has used Legacy_PhasedUpgrader class since Beta 3. In the case where a module developer hope to use the phased upgrade, he has to define the sub-class of Legacy_PhasedUpgrader. He can override all methods of the class, but Legacy_PhasedUpgrader has been designed so that module developers can realize the phased upgrade easily. Therefore, he may define milestone version numbers and callback methods for these versions.

Example Module "upgradeTest":

1. At first, install upgradeTest-0.10.
   
2. Next, upload upgradeTest-0.35, and then do update this module.
   
3. You will have to upgrade for three phases.

The changelog of this example is the upper diabolic changelog. But, you will complete upgrade correctly as the following steps:

(1) upgradeTest 0.10 -> upgradeTest 0.20 (Phased Upgrade) -> (2)
(2) upgradeTest 0.20 -> upgradeTest 0.30 (Phased Upgrade) -> (3)
(3) upgradeTest 0.30 -> upgradeTest 0.35

upgradeTest-0.35 is a good sample for module developers.