BranchManager for DOORS supports multiple branches of an entire project structure in DOORS, maintaining relationships (links and link modules) between the full hierarchy of DOORS modules. Individual requirement identity is maintained across all branches allowing you to view branch history across all source and children branches, as well as merge across the branches.
Branching is the concept of copying DOORS modules and keeping references of those copies. Changes in the copy can be merged into another branch copy later.
IBM Rational DOORS up to version 9.5 has no natural concept for branching in DOORS. Note that branching in BranchManager happens on a module level, i.e. during branching, a copy of a formal module is created (see also What does BranchManager copy).
In this manual we call the original module and the copied modules ‘parallel modules’.
To conform to the look and feel of DOORS, BranchManager defines a branch to be a DOORS project. Inside this project there cannot be parallel modules, i.e. when branching a module, the target must be in another DOORS project. When comparing or merging a module, only the target branch needs to be selected. BranchManager will search the target project for a parallel module and determine the correct module automatically. For this, BranchManager includes some metadata in the copied modules during the branching. This metadata is captured in teh form of specific module and object level attributes that store information about where the module was branched from and what merges have happened to each object.
When branching a DOORS module, BranchManager will copy all objects and attributes of the module (with some exceptions) to the target module. The objects retain the module hierarchy and their object identifier. Depending on the use case for branching, it could be beneficial to give the target module a different module prefix (to get different object identifiers) in both branches. Like the modules, the copied objects are called ‘parallel objects’ in this manual.
BranchManager also copies the out-links of the branched DOORS module. For details regarding the link handling, see the chapter Link Handling. In-links, as governed by the design of DOORS, are not part of the source module and will not be branched (see also Incremental Branching and Link Handling during branching
If only the source module is branched, but there is already a parallel module for the target module in the target branch, and there is also a parallel object for the link target, then BranchManager will replicate the link in the target branch. Using this strategy a module hierarchy can be branched a couple of modules at the time, provided that the branching happens from top of the hierarchy down to the bottom (see also Incremental Branching).
If there is no parallel module for the link target in the target branch, then BranchManager will recreate the link if the option “Recreate links to foreign objects” is selected. In this case the link will be created to the same target object as the original link. Otherwise the link will be skipped and a message will indicate this condition at the end of the branching.
If there is a parallel module for the link target in the target branch, but in that module the parallel object does not exist (e.g. because it has not been merged yet, or it was soft- or hard deleted) then BranchManager will recreate the link to the original link target only, if the option “recreate links to objects that are missing in the target branch to objects in the source branch” is checked. Otherwise the link will be skipped and a message will be displayed for this condition at the end of the branching.
BranchManager considers the common DOORS use case that link modules are typically valid inside the project, where they are located. Therefore, when BranchManager copies a link or the link set pairings of a DOORS module, it will check if the corresponding link module is located in the same project as the source module. If so, BranchManager will branch the link module too. If a module uses a link module outside its own project, then this link module will be reused, i.e. links and linkset pairings in the target branch will use the same link module.
When branching a module, BranchManager will copy the link pairing restrictions of the source module. This way, in the normal case, the user will be able to edit in the target branch right after branching, without having to change the link setup of the branch. Target modules and link modules are adapted depending on if the target module and the link module are available in the target branch.
However for some use cases, like branching a couple of modules of a larger project to a private workspace, this might lead to the undesired result that the links in the branched modules, which point to modules of the large project, are still editable in the target branch (See also Link Management). Therefore BranchManager provides an option to 'Allow only links inside the target branch'. This option will make BranchManager only create those linkset pairings for the branched modules, which have their target module inside the branch. In the following picture, the links to the source branch will still be there, but not editable.
Branches can be established incrementally to manage the size or time in which it takes to create branches. As it is described in the chapter Link handling during branching, BranchManager will create links to modules that exist in the target branch. This can be used to branch a new module from its source branch to other branches, e.g. to update a small bug fix branch with additional required modules. When doing the whole branch, there is no order to be kept in mind since BranchManager will take care of creating the modules in the correct order.
Incremental Branching works by starting at the top of the hierarchy and branching incrementally down to the bottom of the hierarchy. The important factor here is to keep in mind that all link target modules are either part of the branching operation, or already exist in the target branch.
When creating a branch, the branch will replicate folder hierarchy as well. This enables the same familiar structure and content that your users are familiar with. This will happen if you have one or multiple modules being migrated. Folder structure is not mandated for the branch. If the user decides to restructure the branch, there are no limitations and the relationship with the source branch remains the same. This works well for legacy projects that need to be reorganized. When two branches have a different folder structure, care must be taken when branching new modules from one branch to the other. BranchManager will create the modules in their legacy path, then those modules must been moved manually to the desired location in the new branch. Note that the module history will not reflect the move, as BranchManager does not track changes to folders. This does not affect functionality but must be kept in mind to avoid confusion when retracing the history of the module. For the same reason, it is not recommended to move one formal module to a different branch. While this will not affect the functionality, it might create confusion when users look at the Branch History of the module.
There are some important points that should be taken into account when branching:
The Branch History of a module contains:
The common base of the module in branch C and the module in branch B is baseline 1.1 in Branch A, since this is the last baseline that both modules have in common in their history. After that baseline, their history diverges, i.e. between baseline 1.1 and baseline 2.0 in branch A there are changes applied to the module in branch A, that did not make it in the history of branch B. This shows that the common base of two modules is not necessarily a baseline of either module. It can be a module of a completely different branch. Since the common base is important for the integration of two modules, the following should be kept in mind:
A module baseline that is the common base of two branches should not be deleted and also the module itselfshould not be deleted from the database.While branching creates a fairly complete copy of the source module, some differences between a module and its branched copy apply:
Attribute Name | Scope | Attribute Description |
BranchManager Internal ID | Module | This module attribute contains a copy of the modules own database and module identifier. It is used for copy paste detection on module level. Format: <db-ID>:<mod-ID> where <db-ID> is the database identifier <mod-ID> is the module identifier |
BranchManager Internal Reference Long | Module + Object | The "BranchManager Internal Reference Long" attribute, at the module level, contains a reference to the branch root (i.e. the oldest ancestor - the module that was branched first in the history of the module) and the immediate ancestor of the module (that is the module, from which the module was branched) Format: <db-root>:<mod-root>::<db-ancestor>:<mod-ancestor>where <db-root> is the database identifier of the branch root <mod-root> is the module identifier of the branch root <db-ancestor> is the database identifier of the immediate ancestor <mod-ancestor> is the module identifier of the immediate ancestor The "BranchManager Internal Reference Long", as set on an Object, contains a reference to the branch root of the object (i.e. the oldest ancestor - the object that was branched first in the history of the object) and a reference to the object itself (used for copy paste detection): Format: <db-root>:<mod-root>:<abs-root>::<db-this>:<mod-this>:<obj-this> where <db-root> is the database identifier of the branch root object <mod-root> is the module identifier of the branch root object (leading zeros stripped) <abs-root> the Absolute Number of the branch root object <db-this> is the database identifier of the current database <mod-this> is the module identifier of the current module (leading zeros stripped) <abs-this> the Absolute Number of the current object |
BranchManager Branch History | Module + Object | The Branch History is a newline separated text of history entries that describe the objects and modules branch history. Format of a history record on a Module: |INTBS|<date>|<reason>|<srcFullName>|<tgtFullName>|<srcID>|<srcBaseline>|<tgtID>|<tgtBaseline> where: <date> is the date for the record (i.e. Baseline date/time) using the format: yyyy-MM-dd hh:mm:ss <reason> is the kind of record, i.e. "Integration-Baseline", "Branch" or "Baseline" <src<reason>|<srcID>|<srcBaseline>|<srcObject>|<tgtID>|<date>|FullName> the fullName of the source of an Integration, or the source of a branch or the fullName of the module at the time of the baseline <tgtFullName> the fullName of the target of an Integration, or the target of the module at the time of the integration baseline (<n/a> in case of "Baseline" record) <srcID> the module ID or the source of an Integration, or the source of a branch or of the module that was baselined <srcBaseline> the baseline (major.minor suffix) of the source of an Integration, or the source of a branch or of the module that was baselined <tgtID> the module ID or the source of an Integration, or the source of a branch (<n/a> in case of "Baseline" record) <tgtBaseline> the baseline (major.minor suffix) of the source of an Integration, or the source of a branch (<n/a> in case of "Baseline" record) Format of a history record on an Object: |HIST|<reason>|<srcID>|<srcBaseline>|<srcObject>|<tgtID>|<date>| where: <reason> the reason for the entry, e.g. "Branch" or "Merge" <srcID> The module ID of the source module from where the object originated <srcBaseline> The baseline of the module from where the module originated <srcObject> The Absolute Number of the source object <tgtID> The target module ID <date> is the integer representation of date and time of the record |
BranchManager Current Integration | Module | empty if no integration takes place for the module. If an integration takes place, the attribute stores the parameters for the integration in the format: |INT|<srcID>|<srcBase>|<tgtID>|<tgtBase>| where: <srcID>, <scrBase>, <tgtID>,<tgtBase> are the identifiers for the Source Module, the Source Base, the target module, the target base in the format: id[(major.minor suffix)] where id is the module identifier and [(major.minor suffix)] is the baseline version string (left out in case of a current version). |
BranchManager Last Integrated On | Object | This attribute is cleared at the start of an integration and stores the date and time of the last "Mark as Integrated" / Merge operation. This way, the merge script can recognize if the source object of the integration was changed after an object was merged (in case the sourcemodule is a current version). If this is the case, the object will show up in the integration dialog again. |
BranchManager Integration/Merge Changes | Object | This attribute is cleared at the start of the integration and records all merge operations. It can be used to filter the objects that have already been merged in the current Integration. |
BranchManager Integration Options | Module | This attribute stores the integration parameters. Format: <deleted>|<structure>|<attributes>|<link>|<attribute 1>|<attribute 2>|...|<attribute n> where: <deleted> true or false, if new/deleted objects shall be taken into account <structure> true or false, if hierarchy changes shall be taken into account <link> true or false, if link changes shall be taken into account <attribute x> the name of the attributes that shall be integrated. There can be an arbitrary number of attributes. |