Conflict Merge Guide

overview we have made some major enhancements to managing package upgrades in v8 v8 has several new features which help with detecting and resolving package differences this article is a deep dive into how it works and how to use it effectively this article expects a basic knowledge of version control and merging, here is some suggested reading https //blog git init com/the magic of 3 way merge/ glossary site an activate install, e g dev, uat or prod are sites parameter owner parameters have an owner, an owner is a site that last modified the value system install package (this is the 'out of the box' value) local this is the local site, when a parameter is edited the owner becomes the local site master site the master site is the site that the local site promotes to assuming a structure of dev > uat > prod, the master site of dev is uat and the master site of uat is prod when a parameter is promoted to master, the site of the parameter (locally) becomes the master site (note on the master site the owner of the parameter is the site that the parameter was promoted from) system package the entire set of system parameters that are updated on upgrade (or fresh install) system vs local parameters a parameter owned by the system site are parameters that have the out of the box value unchanged parameters that have been modified have their owner changed to the local site the relevance of this is that when a parameter has been modified away from the system value and that parameter is then modified on an upgrade then that parameter needs to be reviewed to ensure it works with the upgraded version as activate net libraries and the incorporated functions will have changed in new versions auto merge in v8 there have been enhancements to the process of applying package updates in v7 any parameters owned by the local site that have updates in the new system package would have just had a system parametername created for them, the administrator of activate then had to review each of the modified parameters and manually merge the changes in v8 activate will attempt to auto merge, which when successful, upgrades the parameter with the new changes in the system package this means that no intervention is required by the administrator of activate on upgrade for that parameter if the auto merge is totally or partially unsuccessful because of conflict(s) then a conflict parameter is created that can be used to launch winmerge to examine and resolve the changes 2 way merge a 2 way merge is used when the common ancestor value can't be found this can happen when a system parameter is deleted, or the history of a parameter is lost (this can happen when a parameter is copied and pasted and the original deleted) a 2 way merge will only have two panes, left is the system value, the right is the current value 3 way merge this is a merge between common ancestor (this is the system value in parameter history or system parameter) current value system package value what is a conflict? a merge conflict is an event that takes place when activate is unable to automatically resolve differences in parameter values (usually local and system values) example walkthroughs these steps use 3 different versions of the script on the delegate task to demonstrate how merges work setup unzip the attached files to a temp folder in the file system open activate studio on a test v8 environment create a new task in called "conflict merge examples" right click the new task and select all tasks > import from the menu click browse and select v6 activate and tick the merge option (very important) and click ok under the task you'll now have a new task called "conflict merge example" with a script parameter on it this will act as our baseline task case 1 parameter is owned by system site repeat the import steps in the setup, but instead select v7 activate, this is simulating an upgrade to v7 what you'll see is the script updated to the v7 version with no conflict, this is because the original owner of the parameter before upgrade was system (i e not customised) and the new v7 version is also system the parameter value is just replaced case 2 parameter has been customised (local) and has changed in the system package in this example we will modify a system parameter to simulate customisation of a script at a customer and see what happens on upgrade steps delete "conflict merge example" and reimport v6 activate open the script parameter and modify the job logaudit line in the script as shown below and save ignore the script errors on save you'll now see the owner of the parameter has changed to the local site as it has been modified now repeat the import steps again, importing v7 activate to simulate the upgrade to v7 the result is an admin task created to resolve the conflict a conflict parameter has been created on the task double click the conflict parameter, we will use winmerge to resolve the conflict winmerge will open and a dialog will show stating how many changes were unable to be automatically merged in the case of a 3 way merge you will see 3 panels, the panels in order are system package value > merge result of the left and right panels > current parameter value in this example, there were big changes to this script upgrading from 7 to 8 most of the script has changed, so there are a few conflicts to resolve between the new and current values activate has done it's best to try and automatically resolve the changes, but it has resulted in a conflict which we need to resolve manually we need to look at the intent of the customisation and determine the next step, the three options are keep the current value revert the value to system and reapply the customisation if possible revert the parameter to system option 1 is not a viable option as functions in the current value are no longer supported and the script will fail to compile option 2 is viable, but it should be considered whether the customisation is still required and adds value option 3 will mean on the next upgrade, assuming no more customisations, that the parameter will be automatically upgraded and no intervention will be necessary this is how you achieve each option via the winmerge ui option 1 keep the current value click the right panel (current value) and click the copy all to left button, this will replace the entire merge result (middle panel) with the current value click the save button then close winmerge the conflict script and system script parameters will be gone and the admin task automatically resolved the system script parameter has been removed because it has been added to the history of the script parameter instead of being a separate parameter you can see this in the parameter history dialog, the top change is the current value we have reverted to, the second value is the upgrade package value this is kept for future merges on upgrade option 2 revert to system and reapply customisations click the left pane (current value) and click the copy all to right button, this will replace the entire merge result (middle pane) with the new value cherry pick the customisations from the current value and merge them line by line by right clicking the line, right clicking and copy selected line(s) to middle you can also manually copy and paste, or edit, the middle pane click the save button then close winmerge option 3 revert to system click the left pane (current value) and click the copy all to right button, this will replace the entire merge result (middle pane) with the new value click the save button then close winmerge