This page summarizes not-so-obvious tips around VersionHandlers. In case you already knew - great! Else glad we could clarify 

Porting fixes to other branches in combination with VersionHandling

Let's consider the case of  MGNLUI-3053 - Getting issue details... STATUS  - basically a simple adaption to configuration. It's to be applied to (at that time) latest 5.2.7-SNAPSHOT and latest 5.3.1-SNAPSHOT version.

As there's changes to bootstrap files, we obviously have to add sections to the VersionHandler (SecurityModuleVersionHandler). Let's assume the fix on the feature branch was created from the 5.2.x branch:

        register(DeltaBuilder.update("5.2.7", "")
                ...
                .addTask(new SetWritePermissionForActionsTask("/modules/security-app/apps/security/subApps/users/actions", new String[] { "activate", "deactivate" }))
				...
        );

Approach one: straight forward

A straight forward approach to forward port it to master would be, to cherry-pick commits. In case there's no merge conflicts, the changes to bootstrap files should be pretty easy to port.

Now the VersionHandler on master (5.3.1-SNAPSHOT) would have the SetWritePermissionForActionsTask added to the 5.2.7 DeltaBuilder as well:

		register(DeltaBuilder.update("5.2.7", "")
                ...
                .addTask(new SetWritePermissionForActionsTask("/modules/security-app/apps/security/subApps/users/actions", new String[] { "activate", "deactivate" }))
				...
        );


		register(DeltaBuilder.update("5.3.1", "")
				...
        );

 works fine when updating from 5.2.6 to 5.3.1

 easy to see it's aligned with 5.2.x branch

 doesn't work when updating from 5.2.6 to 5.3 (doesn't contain the new task in versionHandling) and only in a next step to 5.3.1 (contains it but in the section for 5.2.7 so it won't be applied)

 doesn't work when updating from 5.3 to 5.3.1

Approach one: smart forward

A smarter option is to port the adding of that task to the 5.3.1 DeltaBuilder section in 5.3.x:

		register(DeltaBuilder.update("5.3.1", "")
                ...
                .addTask(new SetWritePermissionForActionsTask("/modules/security-app/apps/security/subApps/users/actions", new String[] { "activate", "deactivate" }))
				...
        );

 slightly more sophisticated (not obvious)

 works when updating from 5.2.6 to 5.3.1

 works when updating from 5.2.6 to 5.3 and later to 5.3.1

 works when updating form 5.3 to 5.3.1

 can cause probs in case someone updates from 5.2.6 to 5.2.7 and later to 5.3.1 (the task will be executed in 5.2.7 DeltaBuilder of the VersionHandler in 5.2.7 jar, then again in 5.3.1 DeltaBuilder of the VersionHandler in 5.3.1 jar)

Note:

the last  would be obsolete, if DeltaBuilders are written in a way, that they can be executed multiple times without failure (e.g. always first check whether a certain node is around, else e.g. create it, rather than failing in case it is already)

Lesson learned

• we should consistently use the smart forward approach
• DeltaBuilders (so the used tasks as well) have to be re-executable (can easily be verified by VersionHandler-UnitTests)
  • we have many cases where stuff in versionHandler has to be fixed e.g. for 5.2.6 and 5.3.2
    
    • this fix has to go into 5.2.6 deltaHandling of 5.2.6 and in 5.3.2 deltaHandling of 5.3.2
    • if a client first updates to 5.2.6, later (for whatever reason) to 5.3 and only then to 5.3.2 these install tasks will be executed twice!
  • simplifies development: you can set back version for a certain module and hence force re-execution of a delta
    
    
• because of the above, we might have 5.3 to 5.3.1 migration differences that we cannot spot with a 5.2.x to 5.3.1 migration branch