Merge for BranchManager for DOORSŪ

BranchManager for DOORS enables merging across branches by detecting changes in content, structure, and location of the same objects. Merging is performed using a three-way-merge leveraging a common base. The common base is either the common parent from the branch or a specified previous integration point of the two branches. Non-conflicting changes (no changes to the same object in two branches) can be automatically merged. Conflicting changes require the user to guide the merged result.

Understanding Merges

In BranchManager, a merge defines the process of  transferring changes from a module in one branch to the same module in a different branch. This section describes the concept behind merging in BranchManager.

Three-Way-Merge (Integration) and Conflicts

BranchManager implements a three-way-merge to account for conflict detection.

Three-Way-Merge

The above picture shows the general situation on a three-way-merge: two modules which have a common base (see Branch History), i.e. there was a point in time, where both modules where equal (after branching). Since that point in time, changes have been applied to both modules. These changes may be conflicting, which means the same object on the source side has been changed in one way and on the target side it has been changed in another way.  Example:

When Branched'
(Common Base)
Source Side Target Side
Object Text The unit shall have a red button. The control unit shall have a red button. The unit shall have a red push button labeled with a solid red circle with 5mm diameter

In the above example, the requirement text of a requirement on the source side has been changed in a different way then on the target side. It is clear that BranchManager cannot know if the change on the source side applies to the target side and how it can be integrated. Even if there are changes in different attributes to the same object, BranchManager cannot know if the two changes are compatible:

When Branched'
(Common Base)
Source Side Target Side
Object Text
The weight of the unit must not exceed 5kg.  The weight of the unit must not exceed 5kg.  The weight of the unit must not exceed 5kg 4kg.
Review Comment In work In workAccepted In work

The two changes in the above table, although not the same attribute is affected, can conflict. Maybe the review comment "Accepted" does not apply anymore if the max weight is changed from 5kg to 4kg. The same applies to changes to links and attributes. A new link might not be satisfied anymore when the requirement text changes. Therefore, BranchManager considers the following cases as conflicting:


Attribute Change Link Change Movement
Attribute Change Conflict Conflict
Link Change Conflict Conflict
Movement

Conflict

The above table shows that a movement does not conflict with an attribute change or a link change. This probably fits to most practical cases, since the position of a requirement in a document should not be relevant for its content.

Repeated Integration, the integration base and base conflicts

When two branches, like variants of the same product, exist in parallel, multiple integrations will be performed over time. BranchManager supports this scenario by ensuring that each change that has been made on the source side, must be reviewed only once and either be merged or not. The following picture shows the situation:

Repeated Merges: Each change must be reviewed only once

Branch B is created from branch A by branching. In both modules, a baseline is created which forms the common base for both branches. Then changes are applied to both sides. When the first integration is performed, there might be conflicts due to changes in Branch A. When the integration is finished, BranchManager forces a baseline in both branches. This way, on the second integration, only those changes that happened in branch B after the first integration baseline will be considered for merge. The baseline that was created on the first integration serves now as the integration base for the second integration.

While this is efficient for the merge efforts, it brings another complication: On the first integration, each change in branch B can either be merged or not. After the second integration, the modules are therefore not equal anymore. This leaves BranchManager with the following situation on the second integration:

Four-Way-Merge

Since the source base and the target base are now different, the situation can occur that a change in the source happens for an object that was not changed in the target, but for which the source base and the target base are different. This is called base-conflict in BranchManager and is an additional source for conflicts. Example:



Source Side Target Side
After Branching The weight of the unit must not exceed 5kg.  The weight of the unit must not exceed 5kg. 

Source Side Target Side
First Change The weight of the unit must not exceed 5kg 4kg. The weight of the unit must not exceed 5kg. 


Source Side Target Side
First Integration Baseline
The weight of the unit must not exceed 4kg.  The weight of the unit must not exceed 5kg.
Note: In the above integration the change was NOT merged to the other side.

Source Side Target Side
Second Change The weight of the control unit including cables to the actuator must not exceed 4kg.  The weight of the unit must not exceed 5kg.
Note:Although there was no change on the target side, the change cannot be integrated , since the source base (First Integration Baseline) and the target base are different. 

As it can be seen from the above table, the "Second Change" cannot be integrated to the target, since the first change has not been integrated. In this situation the user must decide if the target should receive the change or not. Eventually the user has to resolve the conflict manually for the requirement text to read: The weight of the control unit including cables to the actuator must not exceed 5kg.

Understanding Object Merges and Merge Conflicts

In the previous sections we saw how BranchManager determines change conflicts and base conflicts. Unfortunately these are not the only conflicts that can occur during a merge operation. Since BranchManager operates on DOORS modules which consists of a hierarchy of objects that can be linked to other modules, a couple of other problems can arise when trying to merge changes from the source module to the target module.

When trying, for example, to merge a hierarchy change to BranchManager which was either performed by creating, deleting or moving DOORS objects on the source side, BranchManager can usually correctly integrate the most common cases. While we have expanded the types of cases, BranchManager cannot in all cases automatically merge a change to the target side. Example:

Conflict due to Hierarchy Creation

In the above picture, on the source side, there was a hierarchy created consisting of two new objects, object 5 and object 6 - object 5 being the parent of object 6. From the picture you can see that you cannot merge object 6 before you merge object 5. Therefore the two changes of creating object 5 and object 6 are dependent and must be merged in the correct order. Another example:

Merge Conflict due to deletion

In the above picture, one has created a new object (5) on the source side, but the parent object on the target side (2) is deleted. Since you cannot create an object below a deleted object, the change cannot be merged. Since DOORS has a complex data model, there are several other possibilities that will make the merge attempt by BranchManager fail. Here is a list of the most obvious:
In the above cases, BranchManager will not always be able to detect these conditions beforehand, so the user might get an error message from BranchManager indicating the merge operation failed.

How BranchManager handles links during Merge

Comparing and Merging links is a complex problem, especially when complex link and baseline scenarios are considered. As described in the compare section, the Integration and Quick Merge will allow the user to merge either link creations or link deletions to the target module. For this BranchManager has to decide
a) which is the right target module version
b) which is the right target object
c) which link module to use for creating a link

These questions can be answered as follows:

Which Module and Baseline will be used?

The following pictures answers question a). If a link change is detected in the source, BranchManager will first check if the link points to a module inside the source branch (internal link target) or to a link outside the source branch (external link target). If the link points to an external target, then the same module will be considered as a target for for the merged link. If the link points to an internal target, then BranchManager will try to locate the target module in the target branch. If the module does not exist, then the link change cannot be merged.  Then as described in the compare section, the baseline to use as a target will be determined by checking to which baseline of the link target most links in the target module point. If no links are present, then the current version of the module will be used as a target.
Link Merges

Which is right target object?

Then the right object is located in the target module. For an internal module, objects are matched up by the Branch Reference Identifier. For an external module, the object with the same Absolute Number is used. Note that the source Branch and the Target branch can use different baselines of an external link target. If a matching object does not exist in the link target, then the link change cannot be merged.

Which link module to use for creating a link?

BranchManager allows each branch to have a separate link configuration. Therefore, BranchManager will use whatever link module is configured to be used in the target module to be used for the links to the determined link target module. If linking to that module is not allowed, then merging a link creation might fail. In this case, the user has to adapt the link configuration to allow links to the target module. The reason that BranchManager will not automatically adapt the link configuration is the same reason that BranchManager does not create attributes or makes any changes to the data model in the modules. BranchManager assumes that the configuration of the modules have been done on purpose. So if the links to a module are not allowed, BranchManager will maintain that rule. In the future, a tool to synchronize the configuration and data model of two modules is planned.

Equal changes and changes that will not be considered for merge

BranchManager has been designed for being able to work with variants. One important aspect of variants is that whole chapters of documents might only be applicable for one branch. In this case it can be assumed that if chapter X is only applicable for variant A but not for variant B, then changes to chapter X in variant A will not be shown on an integration if:
The logic here is that when chapter X was created on the source side and an integration took place, someone decided (hopefully consciously) NOT to merge chapter X to the target side, or someone decided (also hopefully consciously) to delete chapter X after it has been branched to the target side. BranchManager assumes that in this case, any changes to these objects also do not matter for the target side. If these objects should be merged to the target side at a later time, then the user can start an integration that goes back to the common base which will allow him to merge the creation of the objects.

The second case where a change will NOT be displayed by the integration GUI is when the same change has been manually applied in the target, i.e. the source and the target objects are equal. In this case there is nothing to merge, so therefore the change will not be displayed on the merge GUI. This is useful, especially if changes are merged manually or if the quick merge is employed to merge changes. Note however that if an additional change is made on the source side, after another change has been merged, BranchManager will see a conflict since the target side is different from the source side and both sides have been changed.

Understanding the two-way-merge (Quick-Merge)

two-way-merge

The two-way-merge works by directly comparing two modules with each other. For this, BranchManager supplies the Quick-Merge tool. This means that no conflict detection is possible. There is no base that is taken into account, therefore it cannot be determined if the source or the target module has been changed, just that there is a difference. Therefore the quick merge always shows ALL differences between two modules. Merging an object on the two way merge means, making the two objects equal (at least all the change types that were selected for comparison).

Note that the two-way-merge is a special case for the three-way-merge, if for the source-base and the target base the target module is chosen. In fact internally, BranchManager handles the Quick Merge internally with the same algorithm as the three-way-merge. The following picture shows the equality:

Two-Way vs. Three Way merge

Since on the target side the target module is used as target base and target module, there are no differences that could lead to a conflict. Also for the base modules, in both cases the target module is used, therefore there are no base differences. On the source side, the target module is used as the source base (before change). Therefore the changes that are shown consider the source module to be newer than the target module. 

Effectively using Quick Merge and Integration

The Quick Merge of BranchManager has a different use case in mind than the integration. The first difference to the Integration is that it works in a "push" fashion. That means, the user works from the source module and transfers objects to one or more target branches. Since both the Quick Merge tool and the Integration tool let the user choose if attributes, links or hierarchy shall be merged and additionally which attributes shall be merged, it can make sense to use the integration for some kinds of changes and the Quick Merge for other kinds of changes.

If for example it shall be ensured that the links of two branches are in sync, then one could use the Quick Merge for synchronizing the links between the branches, while the Integration would be used for synchronizing the objects and attributes. Also for attributes it could be desired to keep them in Sync between the branches, therefore these special attributes can be synchronized by using the Quick Merge on those attributes only.

In any case it has to be considered which attributes shall be merged between two branches. Process attributes like review attributes might not be wanted for merge, since process requirements might force a separate review in both branches. For this, BranchManager allows to configure 'common' attributes, which are preselected in the Merge and Compare dialogs.

Merge Metadata

During a merge, BranchManager creates a couple of attributes to store meta data about the Integration / Quick Merge. This is necessary so that the integration can be resumed later. For the attributes that are created and their content, refer to the Attribute Meta Data section of the Branch Concept Page.