About the Merge Branch RuleSets wizard

The development environment that would typically use branches and branch RuleSets is a multi-team development organization, where multiple teams contribute to a single application. The following steps outline the overall approach for each team:

1. Create a development application that's built on the main application. For example, if the team is named Team1, create an application named Team1App. In the application rule for this development application, make sure the Built on Application and Version fields reference the base application under development, and Include Parent is selected.
2. Add the access group for this application to the operator records for the team members.
3. Create the development branches. In the development application's rule form, on the General tab:
   1. Define the branches for the Branch list (see Application rules — Completing the General tab).

      Make sure the order of the branches as listed in the Branch list matches the order in which the rules should be resolved for this development application's users (the developers on the team). When a developer logs into this development application, the system assembles the developer's RuleSet list, and the branch RuleSets according to the sequence in which the branches are listed in the Branch list.

   2. Save the updated application rule.
4. Create the branch RuleSets for the branches listed in the application rule.

   The branch RuleSet is associated with a branch based on your selections in the New form for creating a RuleSet. The branch must already be listed in the application rule, and the application rule saved, before you can create branch RuleSets for the branch. To make a branch RuleSet, in the New form for creating the new RuleSet, select the Branch RuleSet checkbox and select the branch name. Then save the new rule. When you save the rule for the branch RuleSet, the system associates the RuleSet with the identified branch, and you can expand the Branch array on the application rule's General tab to see the branch RuleSet.

5. Perform rule development using the branch RuleSets. For example, copy rules from the original (base) RuleSets into the branch RuleSets to update them, or create new rules directly in the branch RuleSet, that are targeted for inclusion in the base RuleSets when development is complete.

   When you have a record in a locked RuleSet displayed in the Designer Studio, you can click Check out to branch on the record form to save a copy to the branch RuleSet and check out the record in one step.

   Working with rules in the branch RuleSet is the same as in a standard RuleSet, except for the following differences:

   • Final rules — Normally, final rules can only be modified in the RuleSet and class in which they are declared final. This limitation means you cannot normally copy final rules to another RuleSet, either at the same Applies To class or a subclass of the final rule's RuleSet. For branch RuleSets that are branched from the final rule's originating RuleSet, this limitation is removed. You can copy a final rule from its original owning RuleSet into a branch RuleSet that is branched from the owning RuleSet.
   • Utility functions — Some function references in the system use the RuleSet name as part of the reference. To allow for rules to appropriately reference functions that exist in rules in a branch RuleSet, the system's function lookup considers the branches in your RuleSet list when resolving the references.

     Note: You cannot define new Utility Library instances in branch RuleSets.

6. Merge branches when development in the branches is complete.

   The branch's contents (the new and updated rules) are usually moved into the base RuleSets when development activity in the branch has reached a stable point, to make the newest updates available to the wider development team.

   To move a branch's contents into the base RuleSets:

   1. Start the merge process by clicking Merge Branch next to the branch to be moved (on the General tab of the team's application rule. The Merge Branch RuleSets wizard opens to start the merging process and guide you through it.
   2. Resolve conflicts and, optionally, address warnings.

      Because these multi-team development environments often have teams working on the same rules concurrently, more than one team might have branched the same RuleSets, and introduced changes to rules that conflict with one another. Conflicts are considered "blockers". You must take the appropriate actions to resolve all conflicts in a branch before completing the merge of that branch.

      The Merge Branch RuleSets wizard identifies conflicts and warnings, and gives you information to help you resolve the conflicts.

When the merge process is complete, the team's work in that branch is moved into the base RuleSets. Unless the team specified to retain the branch and its RuleSets after the merge, the branch and its associated branch RuleSets are removed from the system.

Notes about working with branches

The branch identifiers (their names) are system-wide. They can be used by anyone that has a compatibly configured application. However, if another team creates a branch RuleSet based on a RuleSet that's not in your application or one of its parents, and selects a branch identifier that you're using in your development application, the system does not associate that branch RuleSet with the branch. and associates a RuleSet that only they can see in their application. The system displays a warning in the application rule. In this situation, you can either add the missing dependency RuleSet to the correct location in your application stack, or negotiate with the other team to have them move their work into a new branch for their own use.

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.

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 Merge Branch next to the branch.

The system starts the Merge Branch RuleSets Wizard in a new tab in the Designer Studio. See Help: Merge Branch RuleSets wizard for detailed information about using the Merge Branch RuleSets wizard.

You can enhance this process for your development team in various ways, to comply with your organization's policies and procedures. You can:

• Add pre-processing behavior
• Add post-processing behavior
• Customize validation on the inputs in the Merge Branch RuleSets wizard user interface

For pre- and post-processing behavior, the flow rule that governs this process has two extension points (as subprocesses) at which you can add custom steps: pyPreMergeInstances and pyPostMergeInstances. By saving a copy of the standard rule and customizing your copy, you can override the generic behavior with custom behavior; for example:

• Pre-processing: By customizing a copy of pyPreMergeInstances, you can provide processing that occurs before the wizard starts — such as verifying that a person's operator ID is performing the merge instead of a generic account.
• Post-processing: By customizing a copy of pyPostMergeInstances, you can provide processing that occurs after the wizard completes — such as sending an email notifying the team about the status of the merge.

For customized validation on inputs into the wizard user interface, override the extension point activity pyValidateMergeOptions.