We recommend that when using branches with a model, you leave the trunk always protected and make all changes in branches of the Model:
• If you leave the trunk protected, to branch and reconcile a branch you require write access permissions only to the Model and those Packages you want to change.
• If the trunk is unprotected and changes have been made directly to the trunk, to branch and reconcile a branch you require write access permissions to the Model, those Packages you want to change, and those Packages that have been changed in the trunk.
Branching from the trunk
It is often useful for all users to work with the same model, so that each user can work with the changes being made by all other users; however, there are times when you want to make changes to a model in isolation from other users, so that your changes do not affect other users, and their changes do not affect you. This is often the case when generating code from a model. Repository-based configuration management supports branching (private sandboxes) so that you can make changes to a model in isolation from other users.
A branch creates a parallel thread of a model, in which you can make changes independently of changes being made to the trunk and other branches. You can build and validate the changes you make in a branch, before reconciling that branch into the trunk. When you reconcile a branch, the changes you have made in the branch are merged into a new tip version of the trunk. After reconciling a branch, you can create a new version of the branch and make further changes. If you are using branches, you should consider a policy of only making changes in a branch and not the trunk, so that you can keep the trunk stable.
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 sandbox. The sandboxes can then be reconciled with each other before reconciling the resultant sandbox with the trunk.
The model items in a branch are initially the same as the model version from which the branch was created. When you change an item or diagram in a branch, the trunk and other branches do not see the changes you have made. After reconciling the branch, the items you have changed are available for changing in the trunk - the changes you reconcile do not appear in branches that are active at the time the branch is reconciled.
When you create a branch, Model Explorer or Modeler performs the following operations:
• If taken from the tip version of the trunk, protects the tip version of the trunk.
• Creates a model version that is a branch of the tip version of the trunk. The user that creates a branch is granted owner access permissions to the model version - the model version is set up as not Public Read and not Public Write. Note that Repository Administrators and Owners can open all model versions in their Repository.
The name of the model version created for a new branch is as follows:
<user name>'s sandbox of <model name> v<version number branched from>
If you attempt to branch a model version that contains locked items (items being changed), Modeler will abandon the branch operation. While a branch operation is in progress, other users will not be able to change the model version from which the branch is being created.
If you want to create a branch from a model version, you require write access permissions to that model version. If the model version you want to branch from is not protected, in addition you will require write access to all Packages in that model.
To create a branch: from Model Explorer, right-click the appropriate model version of the trunk, point to New, and then click New Private Sandbox; or, from Modeler, open the appropriate model version of the trunk, and then on the File menu, point to Model, and then click New Private Sandbox.
You can add a version comment to a model version through Model Explorer - right-click the model version, and then click Comment. In Model Explorer, version comments are displayed in the Comment column.
• While a model version is being branched, other users will not be able to change that model version.
• Package access permissions in a branch are initially set as they were in the trunk version from which the branch was created.
• If you change the access permissions of the model in a branch, the changes you make are applied to any previous versions of that model in the same branch.
• If you change the protected status or access permissions of a Package in a branch, the changes are not propagated to other branches in which the Package appears.
• If a Package in a protected model appears in other moved versions, you cannot change the access permissions of that Package.
Rebasing a branch
When working in a branch, on occasions you may want to merge in to your branch, changes that have made to the trunk – you do this by rebasing the branch. In addition, if there are clashes or conflicts between items in the trunk and your branch, you may want to perform a rebase operation so that you can resolve those clashes and conflicts in your branch, and then test that the clashes and conflicts have been resolved successfully before reconciling your changes to the trunk.
When you rebase a branch, Model Explorer or Modeler performs the following operations:
• Protects the tip version of the trunk.
• Protects the tip version of the branch, and then creates a new version of the branch.
• Compares the tip version of the branch with the appropriated version of the trunk:
◦ 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 rebased.
• If the rebase operation results in clashes that cannot automatically be resolved, such as properties that have changed in both the trunk and the branch, the Clashes dialog lists each clash and allows you to choose whether to use the trunk value or branch value in each case. For more information about the Clashes dialog, see
Resolving clashes - the clashes dialog (repository-based CM).
• Merges changes that have been made in the trunk (since the branch was created) into the tip version of the branch with any clashes resolved as specified in the Clashes dialog.
• If the rebase operation results in conflicts, Modeler creates a Text Diagram or Change Note in the branch to record which items need to be resolved. See
Resolving conflicts (repository-based CM).
• After the rebase operation is complete:
◦ If there are no conflicts, protects the tip version of the branch.
◦ If there are any conflicts, does not protect the tip version of the branch.
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.
If you attempt to rebase a model version and the model version you are reconciling or the tip version of the trunk contain locked items (items being changed), Modeler abandons the rebase operation. While a rebase operation is in progress, other users will not be able to change the tip versions of the trunk and branch.
If you want to rebase a branch, you require write access permissions to the tip version of model trunk. If the tip version of the model trunk is not protected, you also require write access to all Packages in the tip version of the model trunk.
To rebase a branch: from Model Explorer, right-click the tip version of the branch, and then click Rebase; or, from Modeler, open the tip version of the branch, and then on the File menu, point to Model, and then click Rebase.
• While a model version is being rebased, other users will not be able to change the model versions involved with the rebasing operation.
• If you delete an item in your trunk and then rebase a branch, the deleted item and its deleted child items are deleted from the resultant branch version, even if a child item had been moved to a new parent item in the branch.
• If the tagged value of an item's Tag Definition has been changed in the trunk and you have removed that Tag Definition from the item in your branch, on rebasing the branch the tagged value that was set for the item is lost.
• If a diagram has been changed in the trunk and branch, after reconciling the branch you may have to tidy up the resultant diagram.
• Modeler enforces name uniqueness of items that are directly scoped to the same item; however, if a scoping item has scoped items of the same name created in the trunk and in a branch, the resultant model will have items of the same name directly scoped to the scoping item. When this happens, the reconciliation creates a Text Diagram in the resultant model that records the details of the clash.
Reconciling a branch
When you have completed all the required work in a branch, you can merge the branch into the trunk by reconciling the branch to the trunk.
When you reconcile a branch to the trunk, Model Explorer or Modeler performs the following operations:
• Protects the tip version of the branch.
• Protects the tip version of the trunk, and then creates a new version of the trunk.
• Compares the tip version of the branch with the appropriated version of the trunk:
◦ 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 rebased.
• If the reconcile operations results in clashes that cannot automatically be resolved, such as properties that have changed in both the trunk and the branch, the Clashes dialog lists each clash and allows you to choose whether to use the trunk value or branch value in each case. For more information about the Clashes dialog, see
Resolving clashes - the clashes dialog (repository-based CM).
If there are clashes, you may want to perform a rebase operation before performing the reconcile operation, so that you can resolve the clashes in your branch, and then test that the clashes have been resolved successfully before reconciling your changes to the trunk.
• Merges changes that have been made in the branch (since the branch was created) into the tip version of the trunk with any clashes resolved as specified in the Clashes dialog.
• If the reconcile operation results in conflicts, Modeler creates a Text Diagram or Change Note in the trunk to record which items need to be resolved. See
Resolving conflicts (repository-based CM).
• After the reconcile operation is complete:
◦ If there are no conflicts, protects the tip version of the trunk.
◦ If there are any conflicts, does not protect the tip version of the trunk.
If you attempt to reconcile a model version and the model version you are reconciling or the tip version of the trunk contain locked items (items being changed), Modeler abandons the reconcile operation. While a reconcile operation is in progress, other users will not be able to change the tip versions of the trunk and branch.
Note that a sandbox can be reconciled with another sandbox that was created from the same version of the trunk. This allows 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.
After reconciling a branch, you can create a new version of the branch and make further changes. If you are using branches, you should consider a policy of only making changes in a branch, so that you can keep the trunk stable.
Before reconciling a branch, you may want to use the Difference command to compare that branch with the trunk.
If you want to reconcile a branch, you require write access permissions to the tip version of model trunk. If the tip version of the model trunk is not protected, you also require write access to all Packages in the tip version of the model trunk.
To reconcile a branch: from Model Explorer, right-click the tip version of the branch, point to Reconcile, and then click To Trunk or To Sibling Sandbox; or, from Modeler, open the tip version of the branch, and then on the File menu, point to Model, point to Reconcile, and then click To Trunk or To Sibling Sandbox.
• While a model version is being reconciled, other users will not be able to change the model versions involved with the reconcile operation.
• If you delete an item in your branch and then reconcile the branch, the deleted item and its deleted child items are deleted in the resultant trunk version, even if a child item had been moved to a new parent item in the trunk.
• If you change the tagged value of an item's Tag Definition in the branch and the Tag Definition has been removed from the item in the trunk, on reconciling the branch the tagged value that was set for the item is lost.
• If a diagram has been changed in the trunk and branch, after reconciling the branch you may have to tidy up the resultant diagram.
• If you change a Package in a branch and you do not have write access permissions to that Package in the tip version of the trunk (and that Package has changed), errors will occur if you try to reconcile that Package.
• If you change the protected status or access permissions of a Package in a branch, those changes will not be reconciled to the trunk.
• Access permissions defined in a branch are not reconciled to the trunk.
• Modeler enforces name uniqueness of items that are directly scoped to the same item; however, if a scoping item has scoped items of the same name created in the trunk and in a branch, the resultant model will have items of the same name directly scoped to the scoping item. When this happens, the reconciliation creates a Text Diagram in the resultant model that records the details of the clash.
Clashes and conflicts
A rebase or reconcile operation may result in clashes and conflicts:
• A clash occurs when an item has been changed in the trunk and branch, and the problem can be resolved by choosing to use either the trunk or branch item.
• A conflict occurs when an item has been changed in the trunk and branch, and the problem cannot be resolved by choosing to use either the trunk or branch item.
Clashes
The Clashes dialog is opened when you rebase or reconcile a branch (sandbox). If there are any clashes, the Clashes dialog lists each clash and allows you to choose whether to use the trunk value or branch value in each case.
Modeler creates a Text Diagram or Change Note in the model to record any clashes and the decisions made for those clashes. The name of the Text Diagram or Change Note begins with 'Clashes: '. If Change Tracking is enabled, Modeler creates a Change Note; if Change Tracking is disabled, Modeler creates a Text Diagram.
When conflicts occur, the resultant model is left unprotected so that you can resolve the problems.
Modeler creates a Text Diagram or Change Note to record which items need to be resolved. The name of the Text Diagram or Change Note begins with 'Conflicts: '. If Change Tracking is enabled, Modeler creates a Change Note; if Change Tracking is disabled, Modeler creates a Text Diagram.
If you choose not to reconcile a branch, you may want to minimize the size of the database by deleting the model versions in the branch. Likewise, if you no longer require a branch, you may want to delete it.
If you want to delete a model version, you require owner access permissions to that model version and all Packages in that model version.
To delete a model version: from Model Explorer, right-click the model version you want to delete, and then click Delete; or, from Modeler, open the model version you want to delete, and then on the File menu, point to Model, point to Delete, and then click Delete Model Version.
If the Confirm Model Tree Delete dialog is shown, click Cancel unless you want to delete all versions of the model, that is, the complete model.
Version numbers in branches
In Model Explorer, by default when you view a database's models, only the tip version of the trunk and the tip version of active branches to which you have read access are listed. If you want to open an earlier protected version of a model from Model Explorer, you must ensure that the Show Versions toolbar button is selected, and then you can expand a model to view previous versions.
The version number of a model version in a branch has three parts delimited by periods, such as 2.1.1. The value of each part is determined as follows:
• The first part is determined from the model version in the trunk from which the branch was branched. For example, model version 2.1.1 is branched from model version 2 in the trunk.
• The second part is determined by how many branches have been taken from that specific model version in the trunk. For the first branch from a model version the value is 0, for the second branch from the same model version the value is 1, and so on. For example, model version 2.1.1 is the second branch to be taken from model version 2 in the trunk.
• The third part is determined by how many times the model version in the branch has been versioned. For a model version in a new branch the value is 0, for the next version of that model version in the same branch the value is 1, and so on. For example, model version 2.1.1 is the second version of the model in that branch.
Finding out about version history
In Model Explorer, the Last Operation column that shows the last performed repository-based configuration management operation for a model version. The Last Operation column can show the following information:
• Reconciled from <version> - for a trunk version created through a reconcile operation.
• Reconciled to <version> - for a branch version that has been reconciled.
• Created from <version> - for a branch version that has not been rebased.
• Rebased from <version> - for a branch version that has been rebased.
Through Model Explorer you can generate reports about all versions of a model, or all versions in a branch of a model. For more information, see the following topics:
