Guidelines for working with branches - private sandboxes (repository-based CM)
This topic provides guidelines for working with branches.
Branches are useful, for example, when you want isolated Model Driven Development code generation, want to enforce a strict review process before reconciling changes to the trunk, want to work remotely, or want to develop variants of the trunk.
Do not make changes directly in the trunk
When working with branches, we strongly recommend that you do not make changes directly in the trunk – make all changes in branches and then reconcile those changes into the trunk.
Making all changes in branches means that the trunk is typically protected, unless a reconcile is being performed – this makes setting Package access permissions in the model easier:
• To reconcile to a protected trunk, a user needs only write access permissions to the Packages they change.
• To reconcile to an unprotected trunk, a user may need write access permissions to Packages they have not changed.
In addition, branching and reconcile operations are faster when the trunk is protected.
Create branches regularly
You do not want to be working with a branch for long periods of time, because the longer you are working with a branch, the more likely it is that there will be clashes when you reconcile that branch. In addition, while you are working with a branch, your changes are not available for other users to view and use. We recommend that you create and reconcile branches regularly.
A branch should include all the changes required for one task or change, so that a consistent set of changes are made, tested and reconciled together.
Typically only one person working with a branch
Modeler does support multiple users working with a branch, but typically we would expect only one user to be working with a branch.
As an alternative to creating a branch and then multiple users working with that branch, many branches can be taken from a trunk version with each user working with their own sandbox. The sandboxes can then be reconciled with each other before reconciling the resultant sandbox with the trunk.
Rebase a branch before reconciling
In a multi-user environment, it is inevitable that there will sometimes be clashes and conflicts when reconciling a branch:
• A clash is something that has been changed in the branch and has been changed in the trunk, and through the Clashes dialog you can choose to use the branch or trunk version in each case.
• A conflict is something that has been changed in the branch and has been changed in the trunk, but cannot be resolved by choosing the branch or trunk version. Instead, the rebase or reconcile operation attempts to merge the conflicts. When conflicts occur, the resultant model is left unprotected so that you can resolve the conflict.
Important: If a rebase or reconcile operation results in conflicts, the resultant model is left unprotected so that you can resolve those conflicts. After resolving the conflicts, ensure that you protect the model version, so that there is a record of the resultant model from the rebase or reconcile operation.
When clashes and conflicts occur, it is often better to resolve the clashes and conflicts in the branch, rather than in the trunk. To resolve clashes and conflicts in a branch, perform a rebase operation. After the clashes and conflicts have been resolved in the branch, you can then perform a reconcile operation to update the trunk with your changes in the branch.
When rebasing a branch:
• If the branch has not been rebased, the tip version of the branch is compared with the version of the trunk from which the branch was created.
• If the branch has been rebased, the tip version of the branch is compared with the version of the trunk from which the branch was last updated.
If a branch is no longer required, you should delete the branch to minimize the size of the database. You may want to back up model versions before deletion.
Remote working
Branches allow you to remotely work with a model. If you want to work remotely:
• Create a branch of the model you want to change, and then export the appropriate Packages from that branch.
• Working remotely:
◦ Create a model and then import the Packages you exported from the branch.
◦ Make the required changes to the Packages, and then export the Packages you have changed to a folder.
• From the branch you created, update the Packages from the exported Packages (you can difference them).
• Reconcile your branch (you can difference your branch with the trunk).
Using branches with change notes
If you want to track the changes being made in your branch through Change Notes, we recommend the following strategy:
• Create a branch to implement all the changes required for a Change Note - use that Change Note to track changes only in that branch.
• After all changes have been made to implement the Change Note, reconcile the branch.
Viewing the changes made in a branch
When you perform a rebase or reconcile operation, the Clashes dialog allows you to resolve any clashes before committing the rebase or reconcile operation.
You can use the Model Differencer dialog to review differences between the tip version of the branch and the tip version of the trunk; or review differences between the tip version of the branch and the version of the trunk from which the branch was created.
