EMF Compare/Specifications/ModelMergeUI

Evolution Specification: Model merge UI

Current status is DRAFT

Preamble

Model merge UI.

_Relevant tickets_ (links to the Bugzilla tickets which are related to the change):

• Bug 398361 - Model merge UI

Introduction

The goal is to provide a graphical user interface that will guide the user through the merge and conflict resolution process and that will let him choose how to solve a conflict whenever possible.

Detailed Specification

When the user wants to merge a difference, he can be confused with the numerous other differences that may need to be merged. This is caused by the dependencies between differences. For instance, if the user tries to merge the addition of a state in an activity diagram, he also has to merge the addition the activity diagram first (if it did not previously exist).

Currently, EMF Compare displays the list of all detected differences that can be merged, but it does nothing to make the links between differences (requirements, equivalences...) explicit. We should offer a preview of the merge of each required difference and allow the user to merge the dependencies step by step. EMF Compare should also give the user the ability to choose how to merge independent conflicts.

We will provide a graphical user interface that will guide the user through the merge and conflict resolution process and that will let him choose how to solve a conflict whenever possible.

In the Base pack part, we will propose several alternatives for the different parts of the user interface and then make a proposal with some of these choices.

Base Pack

Global UI

The model merge UI will be split in two parts. The high part will allow to select the differences that will be merged. The low part will show the result of the merge, very similar to the existing content merge viewer of EMF Compare.

This document will propose two alternatives for both parts.

High Part

Alternative 1

The high part of the model merge UI is separate in two sub-parts. The left sub-part (1) : this part shows the difference that we want to merge. It's a reminder on which difference we are merging. This difference is highlighted. The right sub-part (2) : this part shows the differences that will be necessarily and optionally merge. The initial differences from each side are synchronized, it means when we click on the initial difference of the left side, then the right side focuses on the initial difference too. The initial difference is highlighted with a specific color, in order to remind to the user which initial difference is merging.

Alternative 2

The high part of the model merge UI contains only one sub-part, corresponding to the right sub-part (2) of the first alternative. The initial difference is highlighted with a specific color, in order to remind to the user which initial difference is merging.

Alternative 3

The high part of the model merge UI contains a dynamic number of sub-parts.

The left initial sub-part (1), contains the initial difference selected in the structure merge viewer of the EMF Compare UI.

The center sub-part (2), contains the differences that will be necessarily merge with selected differences in the previous sub-part (1), and the differences that could be optionally merged.

The right sub-part (3), contains the differences that will be necessarily merge with selected differences in the previous sub-part (2), and the differences that could be optionally merged. And so on...

Thus, the high part contains the needed numbers of sub-parts, which or added/deleted dynamically. At the launching of the model Merge UI, the right sub-part doesn't exists. It is only a user will select a difference in the center sub-part that the right sub-part will be potentially created.

The selection of a checked difference in a sub-part N is synchronized with the required and optional differences associated in the sub-part N+1.

Common behavior

The right sub-part (2) and the sub-parts of the alternative 3 shows the differences that will be necessarily and optionally merge, and the arborescence of these differences.

• The “mergeable” differences have a checkbox on their side.
• The checkboxes of differences that will be necessarily merge (the initial difference, and the required differences) are checked and can't be unchecked.
• If an optional difference is checked, then some new differences can appear and/or become “checkable” (and may be already checked).
• In case of merge a difference from a conflict, then the high part will show all the other differences that belongs to the same conflict (and their respective arbrorescence).
• The way of merge is displayed in the top right corner of the UI.

Low Part

Alternative 1

The low part of the model merge UI is separate in two parts. The behavior is the same as the existing content merge viewer of EMF Compare, it shows the versions of the compared models.

Alternative 2

The low part of the model merge UI contains only one part. The aim is to focus on what will become the targeted model. It is a preview panel. For example, if the merge is made from right to left, then the low part will display the left model after the merge. If the merge is made from left to right, then the low part will display the right model after the merge.

If a selected difference in the high part represents an addition in the target model, the difference label associated in the low part will be bold.

If a selected difference in the high part represents a deletion in the target model, the difference label associated in the low part will be cross out.

Common behavior

The result of merge will be effective only when the user will click on OK button.

The Cancel button cancels all actions made in the merge UI.

Proposal

The choices for the proposal are alternatives 2 for both high & low parts. For the high part, alternative 2 is more simple than alternative 1 because it has one panel less. Furthermore, information lost with alternative 1, are still here in alternative 2. The initial difference is highlighted with a specific color to remind to the user which difference was initially involved for the merge. For the low part, alternative 2 better allow to focus on the result after merge.

Integration with EMF Compare

This new graphical user interface is integrated with the buttons « Copy Current Change from Left to right » and « Copy Current Change from Right to Left ». When a user click on one of these buttons, then the interface is launched.

Examples

The following emf compare model will serve as example for the following use cases. It is a result of a 3-way comparison.

You can found the models use for comparison here : https://github.com/Obeo/emf.compare.acceptance.tests/blob/master/tests/emf.compare.q7.tests/resources/Library.zip

Merge of extlibrary \ Book → CirculatingItem \ TitledItem [eSuperTypes add]

From Left to Right

There are no further consequences about merging TitledItem [eSuperTypes add] of Book → CirculatingItem from left to right, because it goes to delete TitledItem from the list of eSuperTypes of Book. The item TitledItem [eSuperTypes add] is the initial difference we want to merge, so it is highlighted with a specific color. It is checked and locked. It is crossed out because the action of merge represents a deletion in the target model. The subtitle and title attributes of Book are not displayed because they are not involved in the merge of the initial difference.

From Right to Left

There is one consequence about merging TitledItem [eSuperTypes add] of Book → CirculatingItem from right to left. It goes to add TitledItem from the list of eSuperTypes of Book, so the eClassifier TitledItem will be necessarily merge too. The item TitledItem [eSuperTypes add] is the initial difference we want to merge, so it is highlighted with a specific color. It is checked and locked. It is bold because the action of merge represents an addition in the target model. The item TitledItem [eClassifiers add] is checked, locked and bold too. The title attribute of TitledItem [eClassifiers add] and EString type of title are displayed and available to check, because they are sub-differences of a checked difference. If the user checks EString, then title will be automatically checked and locked.

Merge of extlibrary \ Periodical -> Item [eClassifiers delete]

From Left to Right

There are several consequences about merging Periodical [eClassifiers delete] from left to right. It goes to delete Periodical from the list of eStructuralFeatures of extlibrary, and all of these sub-differences. The tree item Periodical [eClassifiers delete] is the initial difference we want to merge, so it is highlighted with a specific color. It is checked and locked. It is crossed out because the action of merge represents a deletion in the target model. All of these sub-differences are checked, locked and crossed out too. The tree item Periodical → Item, TitledItem [eSuperTypes add] is displayed and checked, because it is conflicting with the deletion of Periodical [eClassifiers delete]. You must delete Periodical → Item, TitledItem [eSuperTypes add] if you delete Periodical [eClassifiers delete].

From Right to Left

There are no further consequences about merging Periodical [eClassifiers delete] from right to left. It goes to add Periodical from the list of eStructuralFeatures of extlibrary. The tree item Periodical [eClassifiers delete] is the initial difference we want to merge, so it is highlighted with a specific color. It is checked and locked. It is bold because the action of merge represents an addition in the target model. All of these sub-differences are displayed and available to check. The tree item Periodical → Item, TitledItem [eSuperTypes add] is displayed, because it is in the same conflict group with Periodical [eClassifiers delete], but in this case there is no conflict between them.

Alternative 2

If you check the tree item Periodical → Item, TitledItem [eSuperTypes add], then the tree item Magazine → Periodical [eClassifiers add] will be checked and locked.

If you check the tree item TitledItem [eSuperTypes add], then the tree item TitledItem [eClassifiers add] will be displayed, checked and locked. Its sub-differences will be displayed too.

Alternative 3

The initial difference is selected in the left sub-part. The center sub-part contains the item Periodical → Item, TitledItem [eSuperTypes add] because it is a difference that belongs to the same conflict group than the initial difference. But it is not checked.

In the central sub-part, if you check the the item Periodical → Item, TitledItem [eSuperTypes add], then a new sub-part will be created at the right of the central sub-part. This right sub-part will contain the required differences associated with the item Periodical → Item, TitledItem [eSuperTypes add]. In this case the required difference is his parent difference.

Extensions

The following items are additional features that are not mandatory to make the user interface functional but will be helpful to improve the user experience. These extensions are sorted by priority level.

Multi-selection

With the base pack, it is only possible to select one element before launching the model merge UI. With the "multi-selection" feature, it will be possible to select several elements before launching the model merge UI. Then, in the model merge UI, there will be several initial differences selected.

Expert mode

With the base pack, the new model merge UI will be launched every time a user will click on the “Copy Current Change from Right to Left” button or the “Copy Current Change from Left to Right” button. With the “Expert Mode” feature, a new tool will be added to the structure merge viewer toolbar, in order to let the user choose if he wants to use the new model merge UI or not. It counts only for the non-conflicting differences.

Shaded colors

The “shaded colors” feature improves the user feedback in the high part. Remember in the 2.1.2.3 section : “f an optional difference is checked, then some new differences can appear and/or become “checkable” (and may be already checked). The initial difference is highlighted with a specific color, in order to remind to the user which initial difference is merging.” With the “shaded colors” feature, all the checked differences will be highlighted, and each time a user will select a new difference in the UI, then this new difference and the required differences associated with it will be highlighted with a new color. Thus, the user can better distinguish the correlation between differences.

Filters

With this feature, the filters tool will be accessible in the model merge UI.

Switch button

Suppose you want to merge a difference from left to right, but you click on the “Copy Current Change from Right to Left” button, or you simply just want to see what is the result on the other way. With the base pack, it is not possible to switch the way of the comparison in the model merge UI. Then, you have to click cancel and relaunch the UI by clicking on the appropriate button. An extension will allow to switch the way of the comparison in the model merge UI and thus avoid to users to relaunch the UI when they want to see what's happening on the other way. An icon will be added to the toolbar located on the top of the UI. The switching action will canceled all the differences already checked.

Content merge viewer retractable

With this feature, the low part of the model merge UI will be retractable. Once the low part hidden, the high part will occupy the whole UI. In case of big models, it will be easier for the user to have a larger space to select the differences he wants to merge.

Display more differences

Remember in the 2.1.2.3 section : “In case of merge a difference from a conflict, then the high part will show all the other differences that belongs to the same conflict (and their respective arbrorescence).” The idea of this “Display more differences” feature is to show all differences linked indirectly with a selected difference. In other words, in case of selecting a difference that is a containment reference, then the non-containment references referencing this containment reference will be displayed. Suppose you want to merge the tree item TitledItem [eClassifiers add] from right to left. With the base pack, the merge UI looks like this:

Cause, the merge of this difference has no consequences on other differences, the tree displays just the initial difference and its sub-differences.With the “Display more differences” feature, all the non-containment references referencing the initial difference will be displayed:

Backward Compatibility and Migration Paths

Metamodel Changes

TODO. (Document any change to the metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also.)

API Changes

TODO. (List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code.)

User Interface Changes

TODO. (List every user-visible change in the interface. Here "user" includes not only end-users but also developpers.)

Documentation Changes

TODO. (List every documentation needing an update here, starting by the New and Noteworthy documentation.)

Tests and Non-regression strategy

TODO. (This part of the document should describe the strategy to use to correctly test the evolution and guarantee the non-regression.)

Implementation choices and tradeoffs

TODO. (Any important tradeoff or choice made during the implementation should be referenced here with pros/cons leading to the final decision.)