Branching and merging

Introduction to branching and merging

When multiple developers or teams work on different features of an application, branches of a project version can be made for these features via the Project overview screen. Each feature can be further developed separately and, as soon as a feature is completed, it can be combined (merged) with the main project version (trunk) via the Merging screen. This way, a new feature can be developed and tested entirely independently from the rest of the project.

Creating a branch

menu Projects > Project overview > tab Projects

1. Create a branch using the Create Branch task.

In the pop-up:

2. Indicate for which Project and Project version the branch has to be created.
3. Enter the name of the Branch project.
4. Select a location for the project and the database (fields Branch project folder and Branch database name).
5. For more information on Use as origin, see Snapshots.

Pop-up for creating a branch

When the branch is created, you can develop it like a regular project by selecting the project and the associated project version in the Project ribbon in the Software Factory.

note

Only the creator of the branch has access to the active runtime configuration. All other users can activate the runtime configuration for this branch in the menu Maintenance > Users. Select the user, open tab Runtime configurations, and find the corresponding runtime configuration.

To further fine-tune your development workflow, it is also possible to create branches for a branch project:

Branching example containing two feature branches, a hotfix branch, and a sub-feature branch

Snapshots

When creating a branch, a snapshot of the trunk is created and will be used as the origin version. The origin version is used internally when merging to determine the changes in both the branch and the trunk.

If multiple branches need to be created from the same trunk version, the snapshot can be reused. This is done by selecting an existing origin version as the trunk version to branch from.

Creating a merge session

menu Projects > Merging > tab Merging

When the branch project is completed and tested, it can merged back to the trunk. This is done using the Create merge session task in the Merging screen.

Pop-up for creating a merge session

Select the trunk and branch project version to merge. Any conflicts are identified so that a solution strategy can be defined in the following step. In this situation, only a comparison is made. Because no modifications have yet taken place, you can always return to the previous step.

As long as a merge session is not completed, a merging indication will be added to the project version to indicate that a merge session is pending. Modifications in a project version with the status merging may be lost when the merge is executed.

Merging indicator with project version

It is also possible to merge modifications from the trunk into a branch. This way, the merged modifications can be tested in the branch before merging all changes back to the trunk.

Conflicts

menu Projects > Merging > tab Actions > tab Conflicts

Conflicts are presented in the Conflicts tab. When the merge session is started, all actions done in the trunk and the branch compared to the origin version are analyzed.

Conflicts will occur when:

1. An entity has been inserted in both trunk and branch
2. The same property of an entity has been updated in both trunk and branch
3. An entity has been updated in the trunk and deleted in the branch (or vice-versa)
4. An entity has been deleted in the trunk and a new or changed entity in the branch depends on this entity (or vice-versa)

Overview of the conflicts

Resolving conflicts

After the conflicts are detected, they can be resolved one-by-one. It is also possible to resolve several conflicts simultaneously with the help of the Resolve conflict task.

This enables the modifications from the branch or from the trunk to be carried out. There are four options available:

1. Only carry out the trunk action - The action of the trunk will be executed. The action of the branch and any dependent actions of the branch will not be executed.

   

2. Only carry out the branch action - The action of the branch will be executed. The action of the trunk and any dependent actions of the trunk will not be executed.

   

3. Carry out trunk action but keep dependent branch actions - The action of the trunk will be executed. The action of the branch will not be executed. However, the dependent actions of the branch will still be executed.

   

4. Carry out branch action but keep dependent trunk actions - The action of the branch will be executed. The action of the trunk will not be executed. However, the dependent actions of the trunk will still be executed.

   

note

Options 3 and 4 can lead to new conflicts between the dependent actions of the trunk and the branch. These will then have to be resolved.

Comparing code

With the task Compare code, it is possible to compare and merge the different values of a column for the conflicts Dual change and Dual addition with an external comparison table (WinMerge or KDiff3). After saving the file in the comparison tool, the merged text is transferred to the pop-up. By clicking on OK, the value is stored with the branch and the processing set to Only carry out branch.

A conflict comparison during a merge session

Executing a merge session

menu Projects > Merging > tab Merging

Only when all conflicts have been resolved:

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. Enter the Update status (Development, Test, Acceptance, Production or Inactive). This is the new status of the original target project version.
3. Enter a New project version for the target project.
4. By default, the branch will be deactivated after the merge. However, if you wish to continue working in the branch, uncheck the Deactivate branch box and enter a new version for the branch project. After merging, this new version will be created in the branch as a copy of the new target project version.

After the merge, a new project version is created in the target project and the merged project versions are deactivated.

Undo a merge session

When a merge session has been completed, but the result is undesired, you can undo a merge session. For example, when resolved conflicts do not turn out as intended.

There are some limitations because undoing a merge session deletes created project and base versions. You can't undo a merge session if any of the project or base versions created by the merge session are in use.

menu Projects > Merging > tab Merging

1. Select the task Undo merge session .

2. The following options are available:

   • Merge to trunk - Deactivate branch: deletes the created project version in the trunk. The merge session is reopened.
   • Merge to trunk - Keep branch active: deletes the created project version in the trunk, the base version, and the branch. The merge session is reopened.
   • Merge to branch: deletes the created project version in the branch. The merge session is reopened. The created base project version is not deleted, since it is in use by the merge session.