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
A branch can be created in the Project overview screen using the Create Branch task.
This task opens the following pop-up.
Pop-up for creating a branch
It must be indicated for which project and project version a branch has to be created. The name of the branch project can then be entered and a location selected for the project and the database.
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
When the branch is created, it can be developed like a regular project. To do this, select the correct project and the associated project version on the project screen.
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.
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:
- An entity has been inserted in both trunk and branch
- The same property of an entity has been updated in both trunk and branch
- An entity has been updated in the trunk and deleted in the branch (or vice-versa)
- 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
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:
- 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.
- 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.
- 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.
- 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.
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.
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:
- 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.
- Enter the Update status (Development, Test, Acceptance, Production or Inactive). This is the new status of the original target project version.
- Enter a New project version for the target project.
- 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.