TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Migrating from Apex/Summit to Apex/ClearCase

If you have existing projects being developed or maintained under Apex/Summit, you may be planning to migrate those projects to ClearCase

Note: Apex does not require migration of Apex/Summit projects to ClearCase. Apex/Summit is not a deprecated product. new projects may in fact decide that Apex/Summit is more appropriate for their user than Apex/ClearCase.

This discussion assumes that you have an existing Apex project under Summit that you have decided to migrate to ClearCase. This section will not help you to decide whether to migrate an existing project to ClearCase, or which CM system to use for your new projects.

Note: You need to understand the basics of ClearCase in order to be able to make sense of the discussion that follows.

Apex provides tools to help automate migration of your projects source code base from Summit to Apex/ClearCase. A typical project under Apex/Summit consists of

The migration procedure produces the following artifacts:

If one of these config specs is used to configure a ClearCase view, the resulting view will select in the migrated .rss all of the element versions corresponding to the element versions in the Summit tower from which the config spec was generated. This allows for the creation of ClearCase views in which new development can proceed, or maintenance of old baselines (e.g. for fixes to existing releases) can be continued.

Migration is a one-way process. There is no automated way to migrate from ClearCase back to Summit, and no way to enable parallel development on the same project in both a ClearCase environment and a Summit environment.

Migration is non-destructive and does not affect the original source artifacts under Summit in any way. Once migration is complete, changes to the Summit subsystems and views have no effect on the migrated Rational Subsystems under ClearCase, nor does development in the ClearCase environment have any effect on the original Summit source base. While nothing prevents you from making changes to the Summit source base after migration, this would be strongly discouraged, since there is no automated way to propagate those changes into the ClearCase environment once changes have begun to be made in the source base under ClearCase.

The migration process uses the Apex Summit->ClearCase migration commands migrate_subsystem and migrate_view. The migrate_subsystem command operates on a list of one or more Summit subsystems. For each subsystem, migrate_subsystem creates a controlled .rss within a specified VOB. It then creates ClearCase branch types, branches and element versions in the VOB; these correspond to the source Summit subsystems history families, histories, and element versions.

Typically, migrate_subsystem is run over all of the projects Summit subsystems as the first phase of migration. The second phase consists of running migrate_view on the Summit towers that are to be migrated. The migrate_view command operates on a tower or set of views in the Summit subsystems. Migrate view creates checked-in versions of subdirectories in the Rational Subsystems, corresponding to Summit view subdirectories containing controlled elements (recall that while subdirectories within Summit views are not controlled, in ClearCase any directory that contains controlled elements is itself controlled). If necessary, migrate_view also creates new checked-in versions of the subsystem characteristics files in the Policy/, Imports/, and Exports/ subdirectories.

There is no need to migrate all of the towers at once. There is no point of no return beyond which towers may not be migrated to ClearCase, so you can go back and migrate more towers at any time (provided of course that the original Summit views have not been deleted). The only invariant you must preserve is that the Summit views being migrated be views of the Summit subsystems as migrated by the migrate_subsystem command. As long as you follow the rule of no changes in Summit after migrating to ClearCase, this can never be a problem.


Deciding which Towers to Migrate

You should decide how your project will handle maintenance of old releases whether out of the original Summit source base, or from the migrated ClearCase source base. The advantages of migrating old baselines to ClearCase are obvious:

Leaving old baselines in Summit can also have some advantages:

If absolutely no maintenance in old baselines is intended, then there is no point in migrating the towers to the new Apex/ClearCase development environment. If you expect there to be very little such maintenance, then it still may turn out that it is not worth it to migrate the old towers. It may be that for your project team it is not important to go back to the Apex/Summit environment for the very occasional change, and to manually replicate it in the Apex/ClearCase environment if it is necessary to bring the change forward into the newer baselines under ClearCase.

Remember that migrate_subsystem migrates the complete version history for each element, including check-in notes and attributes. It is not necessary to migrate old towers in order to capture the version histories of elements; towers are just configurations that select some set of element versions. When the subsystems are migrated, you have the complete change history of every file, and you have all of the versions so you can regress to older versions (back out changes), and you can examine deltas between any two versions, all without any necessity to migrate old towers (or any towers at all, for that matter). The only purpose for migrating old towers is to continue maintenance activity on old releases from within the new Apex/ClearCase environment.

Also, there is minimal storage overhead involved in migrating towers. The only additional storage consumed when a tower is migrated is for the possible creation of controlled directory versions within rss, and possible new versions of subsystem characteristic files. No ClearCase views are created by the migrate_view command; its output is a ClearCase config spec file. You can then create a view and configure it with this config spec, but there is no requirement to do so immediately, nor indeed ever. You can generate config specs to represent all your old baselines, then reconstitute views containing those baselines later on as required. When development in that ClearCase view is finished say, the defect is fixed, and no immediate need is forseen for more development in the old baseline you can even delete the view; you can always create one later with the same config spec should it be required again. (ClearCase views should be thought of as transient; they are not self-representational like Summit views. Deleting a ClearCase view does not mean losing a configuration, as long as its config spec is saved). So, storage considerations should not be a factor in deciding which towers to migrate.

Steps of the Migration Process

Below is a step-by-step example of the migration process.

Note: Before you actually start migrating, you should also read the documentation of the migrate_subsystem and migrate_view commands in the Command Reference. The reference entries explain these commands and their command-line switches in more detail than we attempt in this example.

1 . Install ClearCase

Before migration can begin, you need to have installed and configured ClearCase on all machines where it will initially be used. This involves host system requirements planning, setting up a ClearCase domain and designating a site-wide domain server, planning and securing storage resources, etc. These topics are all covered in the ClearCase Administering ClearCase manual.

You also need to have installed Apex 4.0 or higher on all machines where Apex/ClearCase will initially be used.

2 . Plan the structure of the migrated subsystems

Suppose we have the following Summit subsystems:

The first step is to plan what the migrated subsystem structure is going to look like under ClearCase. The only requirements are:

Suppose we decide to migrate the above subsystems into the following structure:

Some items to note:

To summarize, you can migrate into an arbitrary directory structure of VOBs, as long as there is a one-to-one mapping of Summit subsystems to Rational Subsystems.

A file called a migration map file is used to specify this mapping. A migration map file is simply a text file in which each line consists of two whitespace-separated fields: for each Summit subsystem to be migrated, the full pathname of the source Summit subsystem followed by the full pathname of the Rational Subsystem to which the Summit subsystem will migrate. This file is an input to both migrate_subsystem and migrate_view.

An example migration map file for the above example might look like this:

The backslash character (\) can be used in the migration map file to escape the newline character when continuing a logical line, and blank lines are ignored. A migration map file can have any name. Suppose we call our migration map file migrate_map well use this name in the rest of the example text to follow.

3 . Create the VOBs

The migrate_subsystem command does not create any VOBs (for that matter, it does not even know where the VOBs are, it only knows the target Rational Subsystem pathnames you have specified in the migration map). So you must create any required VOBs that do not already exist. In the case that the Rational Subsystems will be located in subdirectories within the VOBs, you do not need to create any of this subdirectory structure its fine if you do, but migrate_subsystem will create these subdirectories for you if you do not.

4 . Migrate the subsystems

The next step is to migrate the subsystems using the migrate_subsystem command. migrate_subsystem takes your migration map file as input, so that it knows where to create the .rss for each Summit subsystem being migrated. It also takes a list of Summit subsystem name arguments on the command line this is the list of subsystems to migrate. This may seem redundant, but migrating a subsystem can be quite a time-consuming operation (remember, we are creating and checking in each version of each element, with checkin notes, creating branches, etc.) so you might not want to migrate all the subsystems named in the migration map all in one go. In fact, typically you would do the migration one subsystem at a time, so for each invocation of migrate_subsystem you would supply a single Summit subsystem pathname on the command line.

The default version history in Apex/Summit is Common. For each Summit history, migrate_subsystem creates a ClearCase branch with the same name, so in this case that branch will be named /Common. If you want the Summit Common history (or some other history) to map to the /main branch instead, you can override the default behavior with the main_history switch. See the migrate_subsystem entry in the Command Reference for more detail.

You must be running an Apex session in ClearCase mode to run the migrate_subsystem command. To migrate the subsystems in our example, you would issue (from an Apex xterm) this command for the first subsystem:

and so on for the rest of the subsystems.

Note that you do not have to be in any particular directory to run this command, and the argument to the use_map switch can be an absolute or relative pathname.

5 . Migrate the Summit towers

Suppose we have towers designated by the following subsystem-relative view names:

Release1.build.wrk
Release2.build.wrk
Release3.integration.wrk
smith.dev.wrk
jones.dev.wrk

Release1.build.wrk and Release2.build.wrk are the areas out of which two old releases are being maintained. Release3.integration.wrk is the integration area for the next release, and the last two towers are some developers personal work towers.

The towers should be migrated in order starting with the oldest baseline since successive versions of the artifacts created by migrate_view will be created in the order that the migrations are performed. You will now start with Release1.build.wrk:

You will then do the same for Release2.build.wrk, specifiying REL2 as the label type and Release2.config_spec for the generated config spec.

Next you will migrate Release3.integration.wrk. For this tower, we might decide not to apply a ClearCase label.

Finally, we would migrate the two developer towers, jones.dev.wrk and smith.dev.wrk. We do so again specifying branch /main and with no label. Even though those towers so not have any chronological relationship to each other, well go ahead and just migrate them one after the other everything will work out fine in the end.

6 . Create ClearCase views

The last step resulted in a set of config specs generated by migrate_view. We do not actually need to create views based on those config specs until the views are needed for reference purposes or for continued development or maintenance. Unlike with Summit, there is no purpose served by leaving views laying around if they are not being used as long as the config spec for a view is saved, a view containing all the same element versions can be created at any time.

A config spec produced by migrate_view can be used to create a dynamic view or a snapshot view whichever suits your needs.

The config specs produced by migrate_view all begin with an element * CHECKEDOUT rule. This is followed by a list of element rules, one for each migrated element. These rules all name the full pathname of the element and the specific version number. Lastly, there is an element * /main/LATEST rule (the so-called catch-all rule).

Some implications of this config spec are:

This config spec as it stands is really only useful for creating an archival view (in which case it should probably have checkouts disabled per (2) above). For live views, the config spec will need to be changed.

First lets consider the case of a view representing an old release that is still being maintained: in our example, a view corresponding to the Release2.build.wrk tower is such a view. To make this view viable, we will first create a new branch type that will be used by our view for any checkouts:

Next, we add this rule to the config spec, prior to any of the other element rules:

This rule specifies that if the release2.build branch (our private branch) exists for any element, then the latest version on this branch is to be selected. Since this rule occurs before any other element rules, whenever this rule matches it supersedes any other rule that might select a version of the element. Finally, we want all checkouts to happen on this private branch. We can do this by wrapping all the subsequent element rules in a mkbranch rule (including the catch-all /main/LATEST rule at the end), or by adding the mkbranch option to each individual element rule.

A brief note before we move on the form of mkbrtype that we invoked to create the branch type creates a per-VOB (ordinary) branch type. It creates this branch type within the current VOB (it requires that the users current directory be within a VOB). This will suffice if all of the migrated Rational Subsystems were created in the same VOB. If not, then you would have to do one of the following things:

1 . Invoke mkbrtype separately to create the branch type within each VOB where the views user is expected to perform checkouts; or

2 . Set up an administrative VOB with the migration VOBs as clients, and use the global option to mkbrtype to create a global branch type. See the Administering ClearCase manual for more information.

Consider next the example of the Release3.integration.wrk tower, which is an integration tower for the next version of the project to be released. We want the system integrator to be able to make localized changes, just as in the Summit tower, and in a normal ClearCase integration view you would be able to do this by allowing the view to check out elements on the main branch. However, with a view migrated from a Summit tower we will probably have to do things differently. This illustrates a difference between the Summit style of development and change propagation and the branch/merge paradigm of ClearCase. In Summit, the development towers are typically allowed to run ahead of the integration tower in versions on the public histories they often contain later versions of elements than those in the integration tower. At some point, the developer may deliver his changes by accepting them into the integration tower. (Actually, the canonical model is that he accepts them into the stage tower, and the system integrator is responsible for accepting them into the build tower). But in ClearCase, you do not accept changes from one view into another; instead, developers keep their changes isolated from the integration stream by developing on a private branch, as we saw in the previous example. They deliver their changes using ClearCases automated merge facility, and they use this same merge automation to rebase their views (the equivalent of a Summit developers accepting changes from a base tower).

It is not unknown for teams using Apex/Summit to use a private history system which is quite similar to the ClearCase branching paradigm, although this is more difficult in Summit. If all the developers in the migrated Summit project used this style, then the migrated integration tower can be set up as a normal ClearCase integration view, just by adding the element * CHECKEDOUT rule. Otherwise, this view should be treated in exactly the same way as a view representing an old baseline (such as in the Release1.build.wrk example) by setting up a private branch for the integrator to work on.

Finally, we consider the developer towers. ClearCase development will proceed using private branches in the normal ClearCase fashion. If development in the Summit project uniformly made use of the private history style, then these branch types do not need to be created they correspond to private histories in the Summit subsystems, and therefore they were created already by migrate_subsystem. To set up the config spec for each developer view, you would start with the config spec by migrate_view for the corresponding Summit tower. You would add the element * CHECKEDOUT rule as before, then enclose the other element rules in a mkbranch rule:

If the private branch was not migrated from a private history in Summit, then you would create it at this time.

There is a special consideration to deal with in the case of developer views. migrate_view creates controlled versions of certain elements if they differ from the latest version as they are migrated. These elements include directories corresponding to Summit view subdirectories that contain controlled elements, and also the subsystem characteristic files (most significantly, Policy/Switches and the Imports/ files). If these are different across the developer towers being migrated, they will appear in a strange form as a succession of checked-in versions in the elements version tree (they had to go somewhere!). This looks odd when you view the version history, so you should be aware of it. But nevertheless, if you use a config spec derived from the one produced by migrate_view, you will get a view with exactly the same controlled contents as the source Summit tower. Since any checkouts will be on your private branch, it is acceptable that some of these controlled elements created by migrate_view might have later versions than the version selected by your view. The only anomaly is something that may occur the first time the developer delivers changes (that is, merges back into the main or integration branch). Any import changes, switch changes, or directory contents changes that are represented by element versions on the main branch will not look like changes to the merge process. In order for these to be delivered correctly, you need to check them out, then check them back in again using the Force check-in if identical option. Once that is done, they will exist on the private branch and will be included as candidates for the merge.

At some point, a stable build of the project will be achieved, and a label will be attached to all the element versions in the view which produced the stable view. Then it will be time for the developers to rebase, that is, refresh their views with the recommended versions from the stable build. At this time, the developers can delete from their config specs all of the per-element rules emitted by migrate_view. Those were just to enable you to continue development without missing a beat, and to get you as far as the first rebase. Now the developers config specs should look much more like normal ClearCase config specs, something like this:

At this time the developers would typically merge out from the main branch into their private branch, to get all the latest changes to any elements for which the private branch exists.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS