This updating process was not strict in XOOPS2 and XOOPS2 JP. But, Legacy 2.1 made it strict. I'll write the design of smart-update here. Module developers don't need to learn it, but if you try to use custom-installer, you may need to learn it.
When users try to update the module, the module has two informations --- DB (current) and xoops_version (latest). Updating is the process which changes DB with xoops_version without losing DB values.
Smart-update recognizes a difference between the current module's configrations and the latest module's configrations. For that, many classes are defined. But, you can understand them easily, because all of them are common patterns.
Legacy_BlockInfomation and Legacy_PreferenceInformation are simple structure which keeps values to compare values with other structures. isEqual() compares values with another structure. update() merges values of another structure.
There are collection classes for every information structure classes. Collection classes keep plural structures and compares them with another collection. add() adds the specified structure to the collection list with sorting. update() compares and merges structures with another collection.
These informations structures and these collection classes don't tie up with any stored-resources. In other words, they never reference both of DB and xoops_version. Doing it is reader classes. Reader classes build instances of collection classes with loading stored-resources which are DB or xoops_version. In the future, if new format shows up, we may add a new reader class for that.