Back Forward 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:

Initiating the merge of a branch

To begin merging a branch:

  1. 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.)
  2. On the General tab, in the Branch list, click Actions next to the branch, and then select Merge. Prior to merging, a snapshot of the base rule is created. This snapshot can be used as a restore point. To access the snapshot of the base rule, open the merge history of the merged rule.

    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 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 check box 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:

  1. For each branch RuleSet, select Create New Version.
  2. Enter a password in the Lock Target After Merge field.
  3. 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:

  1. For each branch RuleSet, select Create New Version.
  2. Enter a password in the Lock Target After Merge field.
  3. For the first branch RuleSet that has reported conflicts, click the conflicts notice to open the Notices window and resolve the conflicts.

  4. Take the appropriate action to resolve each conflicting rule. Select the Conflict resolved. Merge this rule. check box for each rule you resolve.
  5. In the Notices window, click OK to return to the main screen.
  6. Repeat steps 3 and 4 for each branch RuleSet that has reported conflicts.
  7. Click Merge to merge the branch.

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.

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:

  1. Examine the conflicts reported for the rule by expanding its section in the Notices window.
  2. 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.
  3. 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.

  4. Repeat steps 2 and 3 for any other conflicts reported for that rule.
  5. When changes to your branch rule are completed and tested, select the Conflict resolved. Merge this rule. check box 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.
  1. 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.
  2. 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.
  1. 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.
  2. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences.
  3. 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.
  4. 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.
  1. 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.
  2. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences.
  3. 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.
  1. 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.
  2. Review all differences between the rules, and use the Related Rules display to assess the impact of the differences.
  3. 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.

UpAbout the Merge Branch RuleSets wizard