Branching

This feature is available since 9.0.0

Tracker branching is a powerful tool for reusing requirements. With branching you can use the same set of requirements in different variants of the product while being able to modify them separately on each branch based on the needs of the variant. The main concepts of branching are:

• Branch: A copy of a tracker that was branched from the original tracker at a point in time. After creating the branch two copies of the requirements exist and these copies can be modified independently of each other. The process of creating branches is called branching.
• Merge: The process in which the changes from one branch are applied to an other branch. During the merge process the user has the ability to select which changes he wants to copy to the target branch. After the merge the branches can still be modified independently from each other. Note: a merge is possible only between the branches of the same tracker. Branches created from different trackers cannot be merged.
• Master branch: The tracker from which the branch was created.
• Branch hierarchy: Branches can also be created from other branches. This is the same process as creating a branch from a tracker (Master branch) but instead of copying the tracker items from the Master they are copied from the branch.

License and permissions

To be able to access the branching feature your license must include the Branching option. Other than that codeBeamer defines two branch related project permissions:

• Branch - View: allows users to view branches
• Branch - Admin: allows users to administer branches. Users with this permission can create and merge branches.

In addition to the project permissions codeBeamer also defines a tracker level permission: if the Branch - Merge permission is granted to a user on a tracker or branch then he is able to merge to that tracker or branch.

The following trackers cannot be branched: Team, Test Runs, Release, Platform, Test Configuration, Timekeeping, Issue, Contact, Bug

Working with branches

Creating branches

You can create branches from three places (but only if you have the Branch - Admin project permission).

To create a branch you can click on the Create Branch link in the more menu of a tracker or branch. This will show you a popup editor dialog like this:

The fields of this form:

• Name: this is the name of the branch. Mandatory field.
• Color: an optional color. We will use this color in the header of the branches to make them more recognizable.
• Key postfix: optional postfix. By default the branch key is the same as the tracker key. If postfix is specified then it is added to the tracker key.
• Branch Permissions: You have three options when creating a branch.
  • Copy permissions from parent branch: this will create the branch with exactly the same permission settings as the original tracker or branch.
  • Read-only branch: all users that can read or write the original tracker or branch will have read permission on the newly created branch
  • Private: only you, the user creating the branch will see the new branch
• Downstream References to update: the items in the original tracker may have downstream references from other trackers. By default these references will point only to the original item even after creating the branch. In this list you can select some fields. The selected fields will be updated after branch creation to point also to the branched version of the original items.
• Replace Downstream Reference values: when you select downstream references to update then by default the new references will be appended to the reference fields and the original values will be kept as well. If this checkbox is checked then the original values are removed from the fields and only the branched references are added
• Upstream References to update: the upstream reference fields of the current tracker or branch might reference items from other trackers. In this list you can select branches of those trackers. If branches are selected then after the branch creation the upstream references are updated to reference the selected branched version of the items instead of their Master version.
• Description: an optional description for the branch.

An other place for creating a branch is the branches list.

Creating Branches from multiple trackers

You can also create branches from multiple branches at the same time. You can do this on the Trackers page by clicking the button shown below:

This will open a slightly different create branch dialog:

As you can see some fields are missing from the form and there is a Trackers field. In the Trackers field you can select the trackers that you want to branch together.

This function will create a branch with the same name from each selected trackers. If there are references between the selected trackers they will be also updated: after merging the branch items of one tracker will reference the branch items of the other tracker (instead of the original versions). The newly created branches will be grouped together in the trackers tree into a folder with the same name as the branches.

Creating the branches this way has an advantage: if you open the branch in one of the trackers then you can immediately navigate to the same branch of the other trackers. The trackers menu points to the branches:

Example for reference rewriting during branch creation

As an example take the trackers below:

The Test Cases tracker references the System Requirement Specifications tracker which references the Customer Requirement Specifications tracker. The customer requirements have a branch without downstream or upstream references.

When you finished working on your system requirements you might want to create a new branch from the tracker. You also want your new branch items to reference the customer requirements on CustReq Branch1 instead of the Master. You also want to keep the downstream references from the Test Cases tracker on your new branch. To meet these requirement you just have to set up the create branch dialog like this:

You need to select the Test Case > Verifies field in the Downstream References... form field and the CustReq Branch1 branch in the Upstream References... form field. After creating the new branch with these settings the tracker configuration diagram looks like this:

Navigating between branches

You can navigate between branches using the branches and baselines dialog. This dialog shows the hierarchy of branches in the current tracker. To access this list just click the second icon above the document view tree:

This icon will open the branches and baselines dialog:

To switch to a branch just click on the link in the Name column.

If you navigate away within the same tracker to a different branch or master, you will get a warning dialog. In this dialog you can also switch to other branch.

The branches are also listed in the tree on the Trackers page. In this tree you can easily open and configure a branch like any normal tracker.

The tree on the tracker configuration diagram also lists the branches so you can easily see the references between the trackers and branches.

Deleting and editing branches

In the last column of the branches and baselines dialog you will find two icons:

The first icon opens the Properties page of the branch. On this page you can add comments, can modify the branch name and more importantly you can set fine grained role based read and write access for this specific branch.

The second icon deletes the branch.

Viewing branches

Opening a branch will bring you to the document view of the branch. It looks like the normal document view with only a few differences. The most visible difference is the header color. When you are on a branch the header is in dark green:

An other important difference is that on the properties panel you have a Show on parent Branch link. This will bring you to the item on the parent branch from which this item was created. Note that in some cases the item has no pair on the parent branch (for example when the item was created on the branch). In these cases this link is missing from the properties panel.

Modifications on the branch

The main purpose when creating a branch is that you need to create a new variant. This new variant shares most of its requirements with the master branch but you need to modify some of them, or add new requirements.

Initially (after creating the branch) the items on the branch are the exact copies of the original items. Whenever you update, or create an item either on the branch or the parent branch you will get notification badges on the document view. An example:

The possible badges are:

• Created on Branch: the item was created on this branch after the last merge, it does not exist on the parent branch
• Updated on Branch: he item was updated on this branch after the last merge and it is actually different from its pair on the parent branch
• Updated on Master/Updated on Parent Branch: the pair of this item on the Master branch was updated after the last merge and is actually different from the branch item

Clicking on the Updated badged will show the actual differences in a dialog, and you can use this dialog to merge the items one by one:

These badges are cleared after merging between the branch and its parent branch.

Merging branches

In some cases it is useful to get the changes from a branch to an other branch. An example: the quality team finds a bug in a variant and verifies that the same bug exists in other variants too. Instead of fixing the bug in each variants it might be useful to fix it in only one of them and apply the fix to the other variants. This is one case when merging is useful.

The merging process consists of the following steps:

• Selecting the branches to merge. This means selecting the source branch (in the example above this is the branch where the bug was fixed) and the target branch.
• Selecting the changes to apply to the target branch.
• Executing the merge

Selecting the branches to merge

In codeBeamer you can merge between any branches of the same tracker and you can also merge from a branch to the Master. You have three options for starting a merge:

• in the more menu of the branches there are two relevant menu options: Merge to Master (or parent Branch) and Merge from Master (or parent Branch). The first option will use the current branch as the source and the parent branch as the target, while the second option will use the parent branch as the source and the current branch as the target.
• if you click on an 'Updated on branch' or 'Updated on Master' badge it will open a merge dialog with only one item selected
• you can also start a merge from the branches and baselines dialog by selecting two checkboxes and clicking on the Merge link

Executing the merge

On the merge dialog you can see all the differences between the selected branches.

The dialog shows the different field values and the badges.

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. Similarly, the filter is locked to the left (Target) if Deleted is selected under Difference type.

Difference type: Select from All, Updated, Created, or Deleted, 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 the Created or Deleted are 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 branch 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.

The Swap Branches option changes the direction of the merge. So what is now the source branch will become the target and the target branch will become the source branch. If you click Swap Branches, your filters are retained.

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

When you are ready with selecting the changes to apply click the Merge button for the items on the current page. This will apply the selected changes and redirect to the source Working-Set branch. After the selected changes are applied the badges of the merged items are cleared.

If there are items on subsequent pages, repeat the steps for the merge operation, to merge the items on subsequent pages.

To adjust the page size, see: Application Configuration.

Updating Downstream References during a Merge

When working on branches you might add new downstream references to some branch items. In some cases it makes sense to update these references during a merge so that they also reference the master or parent item. For example you find a bug related to a user story on one of your branches. You fix the user story and decide to merge the fixes to the Master branch. Since the bug is also present in the Master version you would like to update the bug during the merge as well.

To make this process easy we added a New Downstream References section to the diff page:

This section shows all the Downstream references of an item that point to the branched version but not to the Master/parent item. You can select some of the checkboxes to update those references. You can also update these references without selecting any other changes of the branch item.

There are some restrictions:

• if you have no permission to update the referring item or the specific field of the referring item then you won't be able to select the reference
• this feature only works when merging to the parent branch (so doesn't work when merging from the parent branch or merging between branches on different levels)
• the added reference will always point to the HEAD version of the item on the parent branch

Skipping fields during merge

There are some fields that might change frequently but are not as important so that you want to merge them every time. For such fields you can check the Omit merge option on the field configuration page.

If this option is checked then the fields are shown in a separate group. Of course you can open this group and click the apply button for them as well.