What is a Merge Request?

A merge request is a way for users for sending their changes from a tracker to a an other tracker (or branch) even when they have no permission to modify items on the target tracker. It is a common scenario that a user creates his own branch from a tracker. He changes some of the items, adds new items then wants to move these changes to the parent branch. This is straightforward when the user has permission to add and update items on the parent branch: he can simply merge the changes.

Sometimes the project administrator may restrict the read access to the parent branch. This is where the Merge Request feature comes in handy. With this feature the user can ask other users (that have write permission on the parent branch) to review his changes and merge them to the target.

A Merge Request is a set of work items. For a Merge Request you can assign reviewers and moderators. The reviewers and moderators review the changes and then a moderator merges the approved items to the target branch.

Sending a Merge Request

You can create a merge request at several places in codeBeamer. You will find the Send Merge Request menu item:

• in the more menu of trackers and branches
• on the KanBan board
• on the report details page
• on the Review Hub

To send a Merge Request just click on Send Merge Request at any of the places listed above. This will start a short wizard that guides you through the Merge Request creation process.

In the first step you have to select the target tracker where you want your changes to be merged. When you are sending the merge request from a branch then the parent branch is selected by default. If you check the Include only suspected items.. then only the items that are suspected are included in the merge request.

The second step shows the differences between the source and the target branch.

The third step is a short statistics about the items in the Merge Request. You also have to specify the Merge Request name on this screen.

In the next step you can add reviewers an moderators to the Merge Request. The two type of users have different permissions:

• the Moderators are able to modify the Merge Request: they can add new users, change the name and other properties. They can also review the items. The most important difference from Reviewers is that only a Moderator can merge a Merge Request.
• the Reviewers can only review (accept or reject the items) but can not modify or merge the Merge Request.

The last step in the wizard is an overview of the items included in the Merge Request. If everything is correct then click on the Create Review button and Merge Request is created.

Working with a Merge Request

The Merge Requests can be found in two places. First, under Review HUB there is a Merge Requests submenu.

This will open a page with all the open Merge Requests that you have access to.

On this page you will find useful information (including the target tracker) about each Merge Requests.

You can also access the incoming Merge Requests of a tracker (the Merge Requests where the tracker or branch is the target) from the tracker page header and from the more menu of a tracker. When a tracker has open incoming Merge Requests then the tracker header shows a clickable badge labeled Pending Merge Requests. This will open up an overlay with the list of open Merge Requests for that tracker.

Reviewing the changes

One of the most important phases of a Merge Request is reviewing the changes. All the contributors (Reviewers and Moderators) can accept or reject the items in the Merge Request (except the ones for which they have no read permission). The Merge Request review page is very similar to the Review HUB.

Merging the changes

A moderator can merge the approved changes to the target branch. An item is approved when all the reviewers who voted on it approved it (that is no one rejected it). When a moderator clicks on the Finish button there are three choices:

• Merge: this button will show the merge screen with all the approved items
• Finish Merge Request: closes the Merge Request without merging the changes
• Restart Merge Request: restarts the Merge Requests. If the items in the Merge Request have newer versions then those versions will be included in the new request.

Clicking on the Merge button opens the merge dialog:

To see and merge relevant changes only, choose from the following Filters:

Report: Select a single report to reduce the displayed merge items. Use this filter carefully because it is possible that the selected report might not contain items from one of the branches. Only those changes are merged that are currently visible.

Apply to side: If you selected a report, the filter is locked to the right (Source) if Created is selected under Difference type.

Difference type: Select from All, Updated, or Created, to filter based on the displayed items. If Updated or All are selected, the Apply to side filter is not restricted to either side.

Field: Select from the available fields to filter the displayed items. This filter applies only to Updated items. The filter is enabled only when All or Updated are selected under Difference type. The filter is not enabled when Created is selected under Difference type. By default, All fields are selected except the ones marked as Omit Merge. This means that by default, items with changes only in omitted fields are not shown.

After you have made your filter selection, click GO.

Mark all as merged: If you select this check box, badges will be removed from all matching items, not only the ones that are shown on the current page. If you select a report and select this check box, only those items are merged that match the selected report and the filter combination. If you select a different report, any earlier check box selection is cleared.

Copy all created: If you select this check box, all items created on the branch and visible only on the current page, will be copied to the target.

For items that were created on the Working-Set you have only one checkbox. Checking it will copy the item to the target branch and create a hidden reference between the copy and branch item. From this point you can track the field changes between the items.

For updated items you can select which fields to copy to the target item by clicking the apply button for the field. If you want to copy all field values of an item then just click on the Apply button in the row of the name. This will apply all changes.

You also have a Mark as merged option for each updated tracker item. This is useful in the cases when you don't want to merge any field changes between the branches but want to acknowledge that the change is not important for you. Clicking this option will clear the badge on the document view without actually merging the changes.

Click Apply All for a bulk update on the current page, or click Apply to merge specific changes.

When the merge request is done between two trackers (not between a tracker and its branch) it is possible that the two trackers has different field definitions. If this is the case then the user may want to define the field mappings before the merge (so that the source values are copies to the appropriate target field). For this reason the merge dialog shows the field mapping box where you can define these mappings:

This dialog shows all the approved items and their difference between the source. This is very similar to the diff page that we use on other pages. The moderator can select the specific changes he wants to merge. When he simply wants to ignore the changes in an item he can just check the Mark as merged checkbox. This will set the item as merged without actually merging the changes.

Clicking the Merge button merges the selected changes, closes the Merge Request and the user is redirected to the Merge Request statistics page. Merging the changes means that the selected modifications are copied to the target tracker. From this point the Merge Request is closed. If there are new changes then the user has to send a new Merge Request including those changes.