Merging

Introduction to merging

When multiple developers or teams work on different features of an application, additional branches can be made within a model for these features. Each feature can be developed separately and, as soon as it is completed, be combined (merged) with the model's origin branch. This way, a new feature can be developed and tested independently from the rest of the model.

Branches

For extensive information, see the Models and branches manual.

1. Create a merge session

When a branch is completed and tested, it can be merged into its origin branch, for example, the MAIN branch.

When you create a merge session, changes (delta actions) are determined by comparing the situation at the origin point in time vs. the current point in time (i.e., the moment when the merge session started). Data migration mappings are included in a merge, see Include data migration mappings during merge.

To create a merge session:

menu Models > Merging > tab Merging

1. Execute the Create merge session task.

   tip

   In the Merge from and Merge into fields you will initially only see active branches that have been marked as 'My branches', and their origin branch. This can make it easier to choose the correct branch to merge from and into. To merge from or into another branch, you can disable the prefilter My branches in the look-up popup.

   Pop-up for creating a merge session

2. Select the Model.

3. Select which branch (Merge from) needs to be merged into another branch (Merge into).

Now, a comparison is made. Any conflicts will be identified, so you can define a solution strategy in the next step. Nothing has been modified yet, you can still return to the previous step.

As long as a merge session is not completed, the branch will get the status 'merging' to indicate that a merge session is pending. This will be visible in both the Model overview screen and the Switch branch task. Modifications in a branch with the status 'merging' may be lost when the merge is executed.

2. Resolve conflicts

menu Models > Merging > tab Conflicts

When the merge session is started, all actions done in the branch that is being merged compared to the origin model version are analyzed. Conflicts will occur when:

1. An entity has been inserted in both the origin and the branch.
2. An entity has been deleted or updated in both the origin and the branch, or deleted in one and updated in the other branch.

After the conflicts are detected, they can be resolved one by one. It is also possible to resolve several conflicts simultaneously with the the Resolve conflict task. This implements the modifications from the branch or the origin.

To resolve a conflict:

1. For conflicts of the type "Inserted in origin and branch", you can choose not only what to do with the conflict actions but also with the dependent actions.

   Resolution	Description
   - Carry out the branch action, including dependent origin actions - Carry out the origin action, including dependent branch actions	Applies dependent actions and results in (new) conflicts if they are conflicted.
   - Only carry out branch actions - Only carry out origin actions	Only applies the dependent action of the selected branch but not the dependent actions of the other branch.

2. For other types of conflicts:

   Resolution	Description
   - Only carry out the branch action - Only carry out the origin action	Only choose what to do with the conflict action (not necessary for the dependent action). For example, when the delete action of a table is chosen, the table is no longer available, so column insert or update actions cannot be executed.

Overview of the conflicts

Compare code in an external tool

menu Models > Merging > tab Conflicts

In code conflicts, choosing the branch or the origin is not always possible. Sometimes part of both need to be used. The task Compare code becomes available if the code has been changed in both the branch and origin.

Use it to compare and merge changes from both the branch and origin with an external comparison tool (WinMerge or KDiff3). After saving the file in the comparison tool, the merged text is transferred to the pop-up.

By clicking OK, the value is stored with the branch.

A conflict comparison during a merge session

3. Use prefilters to view pending delta actions

You can use the following prefilters for viewing your pending delta actions in the Models > Merge > Actions tab:

• Actions with branch impact - Displays the delta actions that will affect the target branch when the merge session is executed. This provides insight into delta actions that may require additional checking to know if it is legitimate to apply them.
• Actions that will be ignored - Displays the delta actions that will not be applied when the merge session is executed. This may be because they are the same in the origin and branch due to manual selection. This provides insight into delta actions that may require additional checking to know if it is legitimate for them not to be applied.

4. Execute a merge session

When all conflicts have been resolved, you can execute a merge session. In this step, only the required changes will be executed:

• Changes in the source ('merge into') will be reversed if they do not need to be merged according to your choice of conflict resolution (if available).
• Then, the changes in the origin ('merge from') will be added.

menu Models > Merging > tab Merging

1. Start the Execute merge session task to perform the actual merge. Or: use the Schedule execute merge session task. This can be useful, for example, if you want to merge outside working hours.
2. When a branch is merged into the origin, this branch will be deactivated after the merge. If you wish to continue working in that branch, uncheck the Deactivate branch box.

After the merge, the branch you merged into will be updated according to the conflict resolution you selected.

Include data migration mappings during merge

When merging a source branch into a target branch, the mappings from the source branch, along with all the intermediate mappings up to the current state of the source branch, will be combined and applied to the new model version created in the target branch after the merge.

Here is how it works:

• When merging an origin branch (like DEVELOP) into a target branch (like FEATURE), any mappings made in the origin branch since creating the target will also apply to the target branch.
• When merging a branch (like FEATURE) back into its origin (like DEVELOP), any mappings made in the branch since it branched from the origin will also apply to the origin branch.

This ensures that the mappings done in the branch will be re-applied when configuring an upgrade in the origin and vice versa.

note

You may need to use the Re-apply intermediate mappings task to see the effect when configuring the database upgrade of the target branch after the merge. See also Re-apply intermediate mappings.

Suppose there are mappings from upgrades of model versions done outside of the source branch (for example, upgrading from MAIN to your FEATURE branch, even though FEATURE was branched from DEVELOP). In that case, those mappings will also be copied to be applied to the target branch of the merge session (in this case, from MAIN to DEVELOP).

Undo a merge session

See chapter Revert a branch in the Models and branches manual.