Help: Merge Branch RuleSets wizard

After development in a branch has reached a stable state, use the Merge Branch RuleSets wizard to move the branch's contents into the base RuleSets. Because other teams might have branched the same base RuleSets to enhance the same rules, or modified the core rules at the same time as work was done in your own branch, you need to identify any conflicts between your changes and theirs before moving your changes into the base RuleSet. The Merge Branch RuleSets wizard helps identify potential conflicts, so that you can address them before moving your changes.

Merging branches is one step in using branches and branch RuleSets in multi-team development. For a description of how to work with branches and branch RuleSets, see About the Merge Branch RuleSets wizard.

Preparation and Prerequisites

Before merging a branch, it is a best practice to determine your answers to the following questions:

Will you lock the branch RuleSets before merging the branch?
The best practice is to lock the branch RuleSets as a signal to others working in the same branch environment that the development in the branch is complete to that point in time, and should not be altered using that branch.
Do you want the merge process to create a new RuleSet version in the base RuleSet? So that after a successful merge of the rules from the branch RuleSet, the new RuleSet version contains the rules updated and created in the branch?
The best practice is to always create a new RuleSet version in the base RuleSet to contain the rules from the corresponding branch RuleSet, because doing so makes it easy to deliver enhancements in a precise, modular way.
Will you lock the new RuleSet version created in the base RuleSet?
The best practice is to lock the new RuleSet version in the base RuleSet, because in the multi-team environment that typically uses branches, locking the RuleSet version alerts other teams that the features in that version are complete as of the point in time the version was created.
Are any rules in the branch RuleSets checked out?
If the Merge Branch RuleSets wizard encounters checked-out rules in the to-be-merged branch RuleSets, it displays a warning and provides a report of the checked-out rules. All rules must be checked in before you can complete the merge. If you exit the wizard to complete steps to check in the rules, you must restart the Merge Branch RuleSets wizard from the beginning.
Do you want the branch and branch RuleSets (with their rules) to be available after the merge? The default is to delete the branch and branch RuleSets after a successful merge.

Initiating the merge of a branch

To begin merging a branch:

Open the application rule for your development application that contains the branch. (See Branches and branch RuleSets for a description of a development application in a branch development environment.
On the General tab, in the Branch list, click Merge Branch next to the branch.

The system starts the Merge Branch RuleSets Wizard in a new tab in the Designer Studio.

Parts of the Merge Branch RuleSets wizard

The first screen of the Merge Branch RuleSets wizard displays all the RuleSets in the branch. So that you can easily and quickly identify issues that might be problems for the merge process, for each branch RuleSet, the wizard displays:

The number of rules in that RuleSet that are candidates to be merged to the base RuleSet. These include the rules from the base RuleSet that were copied into the branch RuleSet and rules that were created directly in the branch RuleSet.
The number of rules in that RuleSet that are checked out (if any), both from the branch RuleSet (Source Checked Out) and from the base RuleSet (Target Checked Out). Those rules must be checked in before the branch can be successfully merged.
The number of problems that might be blockers for a successful merge. Counts of both conflicts and warnings are displayed. These are issues you need to be aware of and must decide how to address before completing the merge.

The fields and controls in the main screen of the wizard are:

Field	Description
Source	Displays the name of the branch RuleSet. You can expand and collapse this title to manage the detailed information for merging that branch RuleSet. To examine details about the rules in the branch RuleSet (such as how many rules it contains), open its rule form by clicking its name. When its rule form is displayed in the Designer Studio, you can drill-down to see the individual rules by clicking on the number in the All Rules column on the Versions field of the RuleSet's rule form. If the branch RuleSet is locked, a lock symbol () appears next to its name. If the branch RuleSet is unlocked, a warning symbol () appears next to its name. Best practice is to lock the branch RuleSets before merging the branch.
Target	Displays the name of the base RuleSet and RuleSet version into which the rules in the branch RuleSet will be merged. To open the base RuleSet's rule form (to examine its RuleSet versions or manage its passwords), click the displayed name. Use the drop-down list next to the RuleSet name to choose the base RuleSet version into which the rules will be merged. Choices are: `Create New Version` — The default. Best practice is to merge rules into a new RuleSet version, or the highest existing one if it is empty. When this choice is selected, the Merge Branch RuleSet wizard creates a new RuleSet version in the base RuleSet during the merge process, using the next higher version number that is available in the base RuleSet. In a field next to the drop-down list, the system displays a default description of the to-be-created RuleSet version. The default description is a combination of the version number and the branch name. You can enter a new description in the field. An existing base RuleSet version (such as `01-01-01`) — You can choose to merge rules into an existing RuleSet version in the base RuleSet. If the existing base RuleSet version is locked, its password is required in the appropriate Password Details fields to merge rules into that RuleSet version.
Password Details
Source Version	Appears when the branch RuleSet version is locked. Enter the password for the branch RuleSet version so that its rules can be merged. The system does not change the protection set on the RuleSet version.
Target Add Version	Appears when `Create New Version` is selected for the target, and the base RuleSet (the target) is password-protected for adding a new RuleSet version. (See RuleSet form — Completing the Security tab). Enter the password for adding a RuleSet version to the base RuleSet, as specified by the To Add a RuleSet Version field on the Security tab of the base RuleSet's rule form. The system does not change the protection set on the base RuleSet. Entering the password here allows access to create the new RuleSet version and save the to-be-merged rules into that RuleSet version.
Target Version	Appears when you are merging rules into an existing base RuleSet version, and the selected RuleSet version is password protected. (See RuleSet form — Completing the Versions tab). Enter the password that locks the selected RuleSet version, as specified for that RuleSet version in the Versions tab of the base RuleSet's rule form. The system does not change the protection set on that base RuleSet version. Entering the password here allows access to save the to-be-merged rules into that locked RuleSet version.
Target Update Version	Appears when you are merging rules into an existing base RuleSet version, and the base RuleSet (the target) is password-protected for updating a new RuleSet version. (See RuleSet form — Completing the Security tab). Enter the password for updating a RuleSet version in the base RuleSet, as specified by the To Update a RuleSet Version field on the Security tab of the base RuleSet's rule form. The system does not change the protection set on the base RuleSet. Entering the password here allows access to the selected RuleSet version and save the to-be-merged rules into that RuleSet version.
Lock Target After Merge	Optional. Appears if `Create New Version` is selected for the target. Enter a password for locking the RuleSet version that will be created in the base RuleSet (the target) by the merge process. At the end of the merge process, the system locks the new RuleSet version using this password and saves it in the base RuleSet. Best practice is enter a password to lock the new RuleSet version after the merge.
Content Details
Total Candidates	Displays the number of to-be-merged rules in the branch RuleSet. To see a list of the rules, click the displayed number. Displaying the Total Candidates list is a useful way to verify whether there are any rules in the branch RuleSet you do not want to merge into the base (such as rules created just for testing or prototyping.
Source Checked Out	Displays the number of rules checked out from the branch RuleSet. You must have all of the rules checked into their branch RuleSet before you can merge the branch RuleSet. To see which rules are checked out and by whom, click the displayed number. In the report that opens, for each row, the Locked by column displays the operator ID for the user that has the rule checked out.
Target Checked Out	Displays the number of rules checked out from the base RuleSet (the target destination for the to-be-merged rules). You must have all of the base rules checked into their base RuleSet before you can merge the branch RuleSet. To see which rules are checked out and by whom, click the displayed number. In the report that opens, for each row, the Locked by column displays the operator ID for the user that has the rule checked out.
Notices	Displays the number of conflicts, how many are resolved (if any), and the number of warnings. Conflicts are problems that are blockers for a successful merge. Before the wizard will proceed with the merge process for the branch, you must specify that you have resolved all conflicts. To identify which rules have conflicts, the reasons why, and resolve the conflicts, click the number of conflicts to open the Notices window. See Addressing conflicts and warnings help section for how to identify conflicts and resolve them. Warnings are issues that, while they do not block a successful merge, are important to be aware of so that they do not cause problems in future development. To identify which rules have warnings and the reasons why, click the number of warnings to open the Notices window. The displayed report of conflicts and warnings depends on the target RuleSet version selected for the merge. For example, merging a rule into target RuleSet version 01-01-01 might display no conflicts and one warning, while merging that rule into target RuleSet version 01-01-02 might display one conflict and no warnings. You must select the target RuleSet version for the merge to get an accurate report of the potential conflicts and warnings. When there are resolved conflicts, the report refreshes to indicate how many are resolved.
Additional Options
Keep all Source Rule and RuleSets after Merge	Optional. Select to have the system retain all of the branch RuleSets and the rules they contain after successfully merging the rules into the base RuleSets. By default, the system deletes the branch RuleSets and their contained rules after a successful merge. The system retains the branch itself in the application rule regardless of this checkbox setting. To remove the branch itself, open the application rule and delete it from the General tab.
Merge	When all identified conflicts have been resolved, click to start merging the rules from the branch RuleSets into the selected targets.
Cancel	Click to cancel the merging of the branch.

Running the merge process — examples

Simple merge process — No conflicts or warnings, merging into a new RuleSet version, and locking that version after the merge:

For each branch RuleSet, select Create New Version.
Enter a password in the Lock Target After Merge field.
Click Merge.

The system performs the merge and deletes the branch rules and branch RuleSets. A confirmation message displays and you can expand the sections for each branch RuleSet to examine details about what was merged.

To see a list of the merged rules for a merged branch RuleSet, and the status of merging each rule, click the Merged n of n link to open the Merge Results window:

Click Done to close the wizard.

Simple merge process with conflicts — Merging into a new RuleSet version, and locking that version after the merge:

For each branch RuleSet, select Create New Version.
Enter a password in the Lock Target After Merge field.
For the first branch RuleSet that has reported conflicts, click the conflicts notice to open the Notices window and resolve the conflicts.
Take the appropriate action to resolve each conflicting rule. Select the Conflict resolved. Merge this rule. checkbox for each rule you resolve.
In the Notices window, click OK to return to the main screen.
Repeat steps 3 and 4 for each branch RuleSet that has reported conflicts.
Click Merge to merge the branch.

Addressing conflicts and warnings

The Notices window displays an expandable list of rules that the Merge Branch RuleSets wizard has identified as having conflicts, warnings, or both. To open the Notices window, click the displayed number of conflicts and warnings on the main wizard screen.

The Notices window reports on both conflicts and warnings for the listed branch rules. To see the conflicts and warnings for a branch rule, expand its section in the window.

Resolving conflicts

Before the wizard will proceed with the merge, you must indicate in this window that you have resolved all conflicts reported by the wizard. Conflicts occur for the following situations:

Conflict situation	Example of how this occurs
The rule in a lower base RuleSet version has been recently updated.	Base RuleSet XYZ has two locked RuleSet versions, 01-01-01 and 01-01-02. TeamA branches XYZ into their Story-A branch, and TeamB branches XYZ into their BugFix-1 branch. TeamB's work is a bug fix for version 01-01-01, and they complete their work and merge their BugFix-1 branch with the changed rules for base RuleSet XYZ into 01-01-01. Then TeamA starts the wizard to merge their Story-A branch by creating a new version for base RuleSet XYZ. The wizard reports a conflict because the rule was updated in RuleSet version 01-01-01 (a lower version) by TeamB prior to TeamA's merge.
The rule in the selected target (base) RuleSet version has been recently updated.	Base RuleSet XYZ has two locked RuleSet versions, 01-01-01 and 01-01-02. TeamA branches XYZ into their Story-A branch, and TeamB branches XYZ into their Story-B branch. TeamB completes their work and merges their Story-B branch into 01-01-02. Then TeamA starts the wizard to merge their Story-A branch into 01-01-02 also. The wizard reports a conflict because the rule was updated in the same RuleSet version 01-01-02 (TeamA's selected target version) by TeamB prior to TeamA's merge.

To resolve the conflicts for a rule:

Examine the conflicts reported for the rule by expanding its section in the Notices window.
Click Compare next to the first conflict to examine the differences between your branch copy of the rule and the one in the base RuleSet. Alternatively, click the RuleSet name (next to the ) to open the base rule and directly examine it.
Review and resolve all of the differences between the base rule and your branch rule.
If the changes are minor (such as a typo), open your branch rule and apply the same changes to it so that it matches the base rule.
If the changes are more complex, or if they conflict with the choices or logic in your branch rule, contact the individual who modified the base rule and negotiate what the final set of changes should be and the testing procedure for testing them. After reaching a mutual decision, make the agreed-upon changes in your branch rule and test.
Repeat steps 2 and 3 for any other conflicts reported for that rule.
When changes to your branch rule are completed and tested, select the Conflict resolved. Merge this rule. checkbox to indicate you have resolved the conflict.

When all conflicts reported in the Notices window are marked resolved, you can click OK to close the Notices window and return to the Merge Branch RuleSets wizard to continue with the merge process.

In the main screen of the wizard, you can see if all conflicts are resolved by verifying if the number of Resolved conflicts matches the number of reported conflicts for all of the branch RuleSets:

Addressing warnings

While important to understand why they occur, warnings are primarily informational. They are provided to make you aware of how merging your branch rule might impact other teams or might not behave exactly as you think it will. Best practice is to review the reported warnings so that you can assess the potential for future problems.

Warning situation	Example of how this occurs	Recommended steps
A rule with the same keys as the branch rule exists in a higher RuleSet version in the target RuleSet.	You are merging the branch rule into target RuleSet version 01-01-01, and the corresponding base rule also exists in target RuleSet version 01-01-02.	Click Compare next to the warning to examine the differences between your branch copy of the rule and the one in the other base RuleSet version. Alternatively, click the RuleSet name (next to the ) to open the other rule and directly examine it. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences. If the features in the rule in the higher RuleSet version does not apply to your target RuleSet version, and your changes in the lower target are not present in, or will not impact, the one in the higher RuleSet version, it is likely safe to proceed with your merge. Merge into the lower RuleSet version. The changes in the rule will work at that RuleSet version level. Those applications that use the higher RuleSet versions might not see your merged changes. For changes in your branch rule that you determine need to be ported to the rule in the higher RuleSet version, define a new development application and matching branch using the higher RuleSet version, and copy the base rule from the higher RuleSet version into that branch RuleSet. Make your changes in that branch, test, and merge to the higher RuleSet version.
The corresponding base rule exists in another branch RuleSet in the system.	Another team has branched the same base RuleSet that you are merging, and has a copy of the base rule in their branch RuleSet.	Click Compare next to the warning to examine the differences between your branch copy of the rule and the one in the other branch. Alternatively, click the RuleSet name (next to the ) to open the other rule and directly examine it. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences. Contact the owner of the other branch, or the author of the other branched rule, and describe the changes you made to the rule in your branch and how they can test for the changes. Best practice is they would validate your changes after your merge your branch and they obtain your changes and include them in their branch. Complete the merge of your branch.
The corresponding base rule exists in another branch RuleSet, which is branched from a different RuleSet than your branch RuleSet.	In this situation, the rule exists in another branch RuleSet which will later be merged into a different RuleSet than the one the corresponding base rule is in. A team has branched a base RuleSet that is different than the one you are merging, and has copied the base rule that corresponds to your branch rule into their branch RuleSet.	Click Compare next to the warning to examine the differences between your branch copy of the rule and the one in the other branch. Alternatively, click the RuleSet name (next to the ) to open the other rule and directly examine it. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences. Contact the owner of the other branch, or the author of the other branched rule, and discuss why a rule with the same name exists in two different RuleSets, and determine whether there are reasons for both to exist or whether one should be removed. If the base RuleSets are for different purposes and will not be run concurrently, then continue with your merge. If the teams agree the RuleSets are to be combined, negotiate an appropriate conclusion and perform agreed-upon changes. Depending on the outcome, complete your merge if appropriate.
A rule with the same keys has been updated somewhere else in the system.	A rule exists in the system that has the same keys as the rule you are merging, and the other rule has been updated.	Click Compare next to the warning to examine the differences between your branch copy of the rule and other rule. Alternatively, click the RuleSet name (next to the ) to open the other rule and directly examine it. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences. Contact the owner of the other RuleSet, or the author of the other rule, and discuss why a rule with the same name exists in two different RuleSets, and determine whether there are reasons for both to exist or whether one should be removed. -If the base RuleSets are for different purposes and will not be run concurrently, then continue with your merge. -If the teams agree the RuleSets are to be combined, negotiate an appropriate conclusion and perform agreed-upon changes. Depending on the outcome, complete your merge if appropriate.

About the Merge Branch RuleSets wizard

Help: Merge Branch RuleSets wizard

Field

Description

Resolving conflicts

Conflict situation

Example of how this occurs

Addressing warnings

Warning situation

Example of how this occurs

Recommended steps