This sample shows a baseline model and two models derived from it. As changes are made to the baseline or to the derived models, a process will be needed to accommodate the changes, preserve history and merge changes from one version into another.
ClearCase and its integration with StP can handle this process. In this paper I describe capabilities now supported by the toolset and proposed capabilities to consider for the future.
Figure 1 shows the versioning process with enough detail to account for baselines, branch versions, bugfixes and merges.
Increment 1 is the model at the time of first being versioned. In this example there are two drawings and a class table. It has an accompanying Sybase repository, as do the other branches or versions. Let us now say we will freeze Increment 1 as a baseline. The repository still allows it to be navigated, reports to be generated, etc. But we have decided Increment 1 can no longer be changed when we froze it.
Increment 2 is then created to support further development. Diagram A and the class table are both changed but in this example, Diagram B is unmodified. (In Figure 1 the dotted line boxes represent unmodified diagrams.) Increment 2 has its own repository and is still undergoing development.
The Bugfix branch model was created to take care of a problem discovered in Increment 1 and likely to affect Increment 2. The developer changed Diagram A and added Diagram D. She left B and the class table unchanged. When Bugfix was created it too received a dedicated repository.
Now our task is to merge the changes from Bugfix into the ongoing Increment 2 model. If we decide to freeze Increment 2 at its previous state before the merge, we would then have Updated Increment 2 after the merge, as well as the other three models and their repositories. This merge process is described below.
The StP / ClearCase integration allows users to version all StP diagrams, tables and annotations. Anything ClearCase can do with ASCII source code files will work with StP, although the Sybase repository requires special consideration.
With Clearcase, StP users have a supported technique for baselining, checkin, checkout and editing all elements of an StP model. The support is an interface supplied by IDE which allows the user of any StP editor to use ClearCase as diagrams are viewed or edited. This interface is a standard supported product supplied with each release of IDE's software.
The attached document, Software through Pictures with Atria ClearCase, describes the existing interface. There is an overview, rationale and screen shot.
Each time a model branches off a new repository should be created. Referring to Figure 1, as we move from Increment 1 to the Bugfix branch, we need a new Sybase repository. In practice, this means that at the time the branch is created in ClearCase, all StP files in the new branch are the same as the original model. To the user it looks as if there is a completely new set of StP files; in reality there is still only one set of files but ClearCase allows users to check out files from the new version and store modifications to them. Behind the scenes, ClearCase stores changes and additions to ASCII files as deltas.
When the new StP repository is created, it will reflect the evolution of the branch and allow StP users to navigate, build reports, etc. in the normal manner. The need for separate Sybase repositories for each branch means that some thought needs to be given to the overall versioning process with StP. What is an appropriate level of granularity for branch models? Should each user have his or her own branch? If that were the case, there would be a separate StP repository for each user. It may be better to have groups of people using each branch, partitioned by task or possibly on a class category basis.
Creating repositories for each new version or branch is presently a manual task.
The process is manual now. ClearCase will tell users which files have been changed. When ClearCase is working with traditional source code files, it has a "difference screen" that presents both versions of a source code file on the screen. However, it would be of little value for an StP user to see the ASCII files for diagrams. Annotation files could be hand edited but there is a risk of loss of integrity of the model. Therefore, any changes to StP files should be done through the StP editors.
Under the current system, ClearCase can inform the developer which files have been changed and are therefore out of synchronization. Referring to Figure 2, that would mean the ABugfix diagram is to be merged with the AIncr2 diagram. He would then bring up the appropriate StP editor with ABugfix and another copy of the editor with AIncr2 and make changes as needed to accomplish the merge.
The merge process described above would benefit from partial automation. For example, if the ClearCase differencing mechanism were fed into an intelligent StP-aware parser, then the merge process could look like this:
In this illustration of the differencing/merge process, the Menu List of Differences shown in Figure 3 has been generated by the output of the ClearCase differencing process fed into a yet-to-be-built Menu. This menu would present the user with a list of all the differences between StP branch models. One could then double click on the desired diagram, class table or annotation and be presented with two StP editor screens -- one for each version. At that point, all standard StP capabilities are available, which includes copy and paste from the graphical editors.
One could go further. The Menu List of Differences could operate at the individual element level. That is, for object models one could do a difference with class granularity. With this, the menu would present a three-column list of every class that is changed. The user would click on the class of interest and the appropriate StP graphical (or table) editors would pop up with the class highlighted and flashing. With suitable use of drag and drop, copy and paste, etc. one could reconcile models in a straightforward manner. A key benefit of this method is that all differences would be unambiguously captured by the tools and that reconciliation does not require manually tracking down the objects of interest.
These proposed capabilities use communication mechanisms already present in StP. They may be viewed as an extension of existing StP navigation facilities. The use of the editors themselves is unchanged by this process. The differencing engine is found in ClearCase as it exists now. The issue is constructing an StP-aware middle piece that recognizes the output of ClearCase's differencer and that supports the Menu List of Differences.
Annotations are stored as files under ClearCase so they should be supported by the Menu List of Differences too. The same navigation capabilities would be available. ClearCase would readily recognize all added or changed annotations.
This process should run with good speed. Once the StP diagram and annotation editors are on-screen, these navigations are fast. Assuming that the Sybase server is responding well, finding and bringing up the diagrams in already-instantiated editors happens quickly. The Sybase server of course is an essential element of the whole system. As production StP models grow, Sybase response is critical to overall performance. Selection and configuration of a sufficiently powerful computer (perhaps dedicated only to Sybase) is critical.
This process should run StP's consistency checking scripts to ensure overall system integrity as the merge draws to a close.
It is possible that the ClearCase MultiSite feature will allow everything discussed here to be performed across geographical distances and multiple platforms, and allow an orderly process for maintaining large projects with multiple sites.
One last thought on merging. It may be possible in the future to put both the old and new versions of a diagram on the same editor screen and use visual differencing (perhaps with color) to cue the operator. Then all unchanged elements would be left alone and those with differences would be highlighted. Note: This is speculation on my part and does not imply that any specific capabilities will exist in future releases of StP.
This paper, in its first conception, is intended to illustrate talking points which may be valuable in understanding and extending the versioning process with StP and ClearCase. This is not a proposal for any specific products or enhancements from IDE, nor is it a solicitation for customizations to be fabricated by IDE.
The paper may be useful as a starting point and as a focus for discussions. It may also be helpful for this author or other authors to cut and paste from here to subsequent discussions, proposals or statements of work.