Difference between revisions of "Papyrus Compare"

Revision as of 12:22, 28 January 2019

Papyrus Compare provides comparison and merge facilities for Papyrus models. It enables teams to work together on their Papyrus models using git. Therefore, Papyrus Compare hooks into git operations that require a merge and performs a model-level merge that respects the logical structure of Papyrus models, instead of a plain text merge. When comparing git branches or any git refs, Papyrus Compare also shows the differences on model level instead of showing a text diff. Papyrus Compare is integrated with the Eclipse Team tooling and workflows. Thus, Papyrus models can be compared, merged, cherry-picked, and rebased in Eclipse just like you would do it with source code.

To achieve that, Papyrus Compare builds on and extends EGit and EMF Compare, respectively, in order to customize them to seamlessly support their usage with Papyrus models. Papyrus Compare is an extra component of the Papyrus project but is not part of the Eclipse release train.

The goal of Papyrus Compare is to support all diagram types and domain-specific profiles provided in Papyrus. At this point, however, the maturity level varies across the diagram types and profiles.

Streams and Compatibility

Two streams of Papyrus Compare are available. The development stream called nightly and the more tested but less frequently updated integration stream. Both streams are compatible with Papyrus Oxygen, Photon, 2018-09, and 2018-12. Papyrus Compare requires EGit version 5.1.0 or higher. The nightly stream is built against the nightly build of EMF Compare, while the integration build is built against the latest release of EMF Compare.

Setting Up Papyrus Compare

Installation

To install Papyrus Compare in a Papyrus Oxygen, Photon, 2018-09, and 2018-12 installation, we first have to install the latest EMF Compare, if it isn't installed already from the EMF Compare Releases Update Site. Next, we have to add the Papyrus Compare update site. Depending on whether you want to install the nightly stream or the integration stream (see above), the location of the update sites are as follows:

• Integration (recommended): integration p2 update site
• Nightly (latest but less tested): nightly p2 update site

To add the update site, open the menu Help → Install New Software... and click Add.... In the Add Repository dialog, enter an arbitrary name, for instance Papyrus Compare, specify the location depending on the preferred stream as listed above, and click OK.

Select Papyrus Compare > Papyrus Compare Feature (Incubation) and click Next >. On the next page, confirm the selected feature to install and click again Next >. Now you have to confirm the Eclipse Public License by selecting I accept the terms of the license agreement and click Finish.

The installation will start in the background and may take a few minutes to finish, depending on your internet speed and the availability of the Eclipse servers. You can view the progress of the installation when you click on the progress button in the lower-right corner of the Eclipse window. If you are installing the nightly stream, you may see the warning above, as this build is not signed.

Please click Install anyway if you are fine with installing unsigned content. Once the installation is finished, you will be asked to restart Eclipse. Please click Restart now to restart.

If everything went fine, Papyrus Compare is successfully installed.

Configuration

There are various configuration options to consider. In the following, we list the recommended preference settings. Especially the first one is necessary to allow Papyrus Compare to handle Papyrus models during the git merge operations. To configure the preferences, open the menu Window → Preferences.

• Enable the model merge strategy in git (required) Go to Team → Git → Synchronize and select Recursive Model Merge Strategy
• Enable the Scalable Conflict Detector in EMF Compare (strongly recommended) Go to EMF Compare → Engines, open the tab Conflict, and check Scalable Conflict Detector
• Enable pre-merging non-conflicting changes (optional but recommended) Go to EMF Compare → Merge and check Pre-merge models when a real conflict is detected
• Enable workspace resolution of cross-references (optional but recommended) Go to EMF Compare → Resolution Strategy and select Workspace in the drop-down box Resolution scope
• Disable selecting the next unresolved difference after a merge action (optional) Go to EMF Compare → Editor, open the tab Model Difference Tree, and uncheck Select next unresolved difference after a merge action

You are all set and can now start using Papyrus Compare.

User Documentation

The user documentation is work in progress. In the meantime, please refer to the video tutorial and to the EMF Compare User Guide, in particular, the user interface documentation and documentation of how to compare models with EGit.

Developers' Information

Useful Links

• Code repository
• List of open Papyrus Compare bugs
• List of open EMF Compare bugs
• File bug reports
• Open Gerrit reviews
• Build on Eclipse Hudson

Building Papyrus Compare

Clone the source code repository and run the following command to build the nightly stream or the integration stream.

# Nightly stream
cd plugins/compare/
mvn clean install -Dtarget.stream=nightly

# Integration stream
cd plugins/compare/
mvn clean install