Merging Document Work Items

There is often a need to have more than one version of a Document in progress concurrently. For example, the requirements specification for version 1.0 of a software application might be completed, and development and/or testing begun, while work begins on the requirements for version 2.0. In such cases, the team can branch the Document containing the version 1.0 requirements specification to create a specification for version 2.0. The Requirements in the version 2.0 Document are "referenced" from the version 1.0 Document, which is then the "master" requirements specification Document for the application. In the branched Document, authors can create new Requirements (Work Items) applicable to version 2.0. But it can also happen that Requirements contained in the master Document, and appearing as referenced items in the version 2.0 specification, need to be changed for version 2.0. Authors of the verion 2.0 specification can overwrite Requirements referenced from the version 1.0 master with new content applicable to the 2.0 version.

Then, at some point (a release, for example), it becomes desirable to merge the changed Work Items in the version 2.0 Document into the master Document in order to have the master in sync with the latest release. During the cycle, some items in the master Document may also have changed, and these changes need to be reflected in the version 2.0 document by updating the references and "freezing" them to the released 2.0 version. The master can then be branched again for a version 3.0 specification, and so on.

The process of branching is covered in the User Guide topic Branching Documents. This topic and following sections describe:

Understanding Merge Actions and Terms

Before getting started, it can be helpful to understand what you can merge under what conditions. In general, Polarion does not allow you to execute a merge action that is not valid for the target. The user interface will only offer valid actions for any merge direction. If you don't see some action you would expect to find, it may have been disabled in the project configuration. For example, project leaders could decide not to allow Work Items to be sent to the Recycle Bin, and could have an administrator disable the Send Item to Recycle Bin action. In that case, you would never see that action offered in the user interface.

To familiarize yourself with the full set of possible merge actions, and when they are available, see the User Reference topic Merge Actions for Compared Documents. It can also be helpful to review the topic on Merge Teminology.

Getting Started With Merging

The starting point for merge operations is in the Work Items page of the compared Documents view. To access it:

  1. Open the a Document you want to compare with another one (for example, the branched version 2.0 specification mention in the introduction).

  2. Click the (Actions) icon, and on the menu choose Compare with > Master Document or Compare with > Other Document, depending on what you want to do.

  3. In the Compare Document dialog, optionally select a Document revision (default is HEAD - which should be the choice in most cases).


    Leave the Filter field empty. Merging is not available from filtered Documents.

  4. On the toolbar of the compare page, click the Work Items button to open the compare view for Work Items.


The compare view opens provided the total number of Work Items in both Documents does not exceed 1000. If it does, there is an intermediate step in which you can choose specific things to compare (Document, Work Items, Fields). The default limit provides best system performance in most cases. An administrator can adjust the limit up or down via the system property com.polarion.ui.documentCompare.workItemsLimit.

Understanding the Work Items Page

When you first enter the Work Items comparison page, it presents a view of the Work Items in the compared Documents:

Figure 15.37. Document Work Items Compared

Document Work Items Compared

The Work Items page of two compared Documents

On the left is the Document from which you invoked the comparison. The Document to which you are comparing appears on the right. For example, if comparing a branched Document to a master, the branched Document is on the left, and the master on the right. You can switch the positions of the compared documents using the Switch Documents () icon located on the page toolbar.

Work Items contained or referenced in the each Document appear in respective columns. The order of Work Items is presented in the structure of left Document. For Work Items that are changed it is easy to see under which chapter they are located and whether there are parent Work Items. (Headings and parent Work Items appear only to reveal the structure. It is not possible to perform merge actions with them.) You can easily see the structure of Work Items, and the differences in the two Documents.

Work Items that exist only in one of the Documents that are being compared are also presented in the actual or potential (i.e. post-merge) structure of the other Document. For example, items that exist only in the right Document are shown in the left Document at the place they can potentially be inserted via a merge action

A Work Item that has been overwritten in one Document is compared on single line with the original Work Item it was branched from, or another overwritten item that has same original Work Item.

To better understand why Work Items are compared on one line, as well as for better decision making on merge actions, some additional information is displayed on each Work Item's header:

  • Frozen reference to rev # - appears if Work item is referenced from a specific revision.

  • Live reference - appears if a Work Item is referenced from its Head revision.

  • Branched from [ID] - appears if a Work Item was referenced from one Document and was overwritten in the other.

  • Does not exist - appears if a Work Item does not exist in the Document, and is not in the Recycle Bin.

  • Item is in Recycle Bin - appears if a Work Item is not shown in the Document, but exists in the Recycle Bin.

If a Work item has no additional information in the header it means that the Work Item is contained in the Document. That is, it is neither a reference nor a branched item.

Repair Missing Cross-references:

You can repair missing Cross-references by inserting the missing item using the Insert Live/Frozen reference merge action.

Using the Merge Sidebar

The Merge sidebar shows available merge actions for a selected Work Item in a given context, and enables you to perform merges. To access the sidebar, click (Merge) on the Work Items page of the Document comparison view. You must have VIEW permission for both Documents, and MODIFY CONTENT permission for any Document changed by a merge action you execute. (If you do not have the necessary permissions, the sidebar is disabled.)

Figure 15.38. Merge Sidebar

Merge Sidebar

The sidebar lets you choose from available merge actions for the merge direction

When Merge sidebar is open you can select a Work Item by clicking on its header (Work Item headers are light blue). Also, the left border appears highlighted, which helps you to easily see:

  • Which Work Item is currently selected: the header of the Work Item and the left border are highlighted.

  • Which Work Item has some pending merge action: the left border color changes to the color of the pending merge action in the sidebar. (The border color remains if you select another Work Item, until the changes are saved.)

  • That a Work Item has no pending merge action and is not selected: the left border is gray.

When you select a Work Item, its header row highlights and the Merge sidebar shows the merge actions available for the current selection. (For a complete listing and description of merge actions, see the User Reference topic Merge Actions for Compared Documents.)

Also keep in mind:

  • The arrow buttons at the top show the merge direction (Master to Branched, or Branched to Master for example).

  • If an arrow button is disabled, it means there are no merge actions available in that direction for the selected item.

  • Click an enabled arrow button to see the merge action(s) available in the respective direction for the selected Work Item:

    Figure 15.39. Merge Directions and Actions

    Merge Directions and Actions

    Available merge actions differ for merge directions

  • In the Merge sidebar, click on the merge action you want to execute.

    If you make a mistake and find you are looking at the wrong merge action direction, or you don't want to do any merge action, click Cancel, or the selected arrow button, or the other arrow button (if enabled).

  • You can optionally select merge actions for different Work Items without saving. After you have selected all the merge actions you want for all Work Items, click the Save button at the bottom of the Merge sidebar.

An administrator can configure which merge actions are available to users. For example, if project leaders decide that the Copy the Work Item action should never be available, the administrator can remove it from the configuration. For more information see the Administrator's Guide topic Configuring Merge Actions.

Merging Fields

For some merge contexts, the Merge Some Fields and Merge All Fields actions are available for the selected merge direction. The most common scenario is Test Case type Work Items that contain test steps (but it can be available for other types). By default, Merge Some Fields merges only the Title and Description fields. However, more fields can be specified in the Merge Actions settings in the global and/or project configuration. Merge All Fields merges all fields normally needed by users. (For a list of fields not merged by this action, see the User Reference topic Fields Not Supported for Merging.)

Handling of Merge Conflicts

Concurrent changes in one or both Documents involved in a merge action are generally a rare occurrence, but a conflict could happen. Polarion always notifies you if another user has made concurrent changes to the same Document you are working with, and displays messages explaining your options. These include reviewing the changes made by the other user, so you can decide whether or not to keep them or overwrite them.

Figure 15.40. Merge Conficts

Merge Conficts

If merging conflicts with other users' changes, you are notified and offered options.