UCM for Zealots: Moving from Base Install to UCM ClearCase

Are you thinking of moving from base CleaCase to UCM? Does your base installation support your organization's current usage model? Here are some points from Christian Buckley and Darren Pulsipher that you may want to consider when making the decsion to move to UCM.


Christian Buckley, Principal, Red Hill Partners

Christian Buckley is a principal.

Darren Pulsipher, Configuration Management Architect, Cadence Design Systems

Darren Pulsipher is a Configuration Management Architect.

27 July 2004

What is Unified Change Management (UCM), and how does it apply to IBM® Rational® ClearCase?

UCM was developed to make it much easier for people using ClearCase to get started with an effective use model. This is because a "base" ClearCase installation has so much flexibility that many organizations find it difficult to use the application out of the box. To make ClearCase more useful to their specific needs, they write their own scripts and processes. UCM was an effort to identify the most common elements of ClearCase use models, and to create objects and methods that make the application more effective.

If you are currently running the base install of ClearCase, you may at some point consider an upgrade to UCM. But where to start? What is involved? What are the differences? Before considering a move from your current ClearCase system to a UCM system, you should first understand your current use model -- and how your organization has been using the Basic ClearCase objects since your installation. This process of change is very much like moving to ClearCase for the first time. As with any new project, you need to understand where you are before you can move forward.

The goal of this article is not to show you how to map your current process to UCM -- our intent is rather to describe the different UCM objects and how they are used. We'll leave the mapping process to you: after all, you know your system better than anyone. And we wouldn't want to deprive you of all that fun.

To begin, you should review the basic ClearCase objects that you are currently using. By reviewing your current objects, you'll be able to see the differences between your basic installation and UCM, and better understand what new functionally the UCM objects can bring to your ClearCase system. Most organizations making this change find that they have written many of their own scripts to perform functions covered by some of the UCM objects. In cases like this, it is okay to adopt the UCM objects. This benefits you because when ClearCase has the same functionality as your custom development, it's one less script that you have to support within the system, allowing you to spend more time concentrating on actual work.

Basic ClearCase Objects

If you already have a CM plan completed, you are almost done. If you don't yet have a plan, see the IBM® Rational Unified Process® methodology for a template. A good CM plan will contain the workflow in very general terms, and then a specific ClearCase mapping. If you have developed your own plan with a detailed map of your system, then you will find that changing over to UCM should be fairly straightforward. At the very least you will easily be able to see whether or not UCM is a good fit for your implementation. That's why you want to have a clear understanding of your existing objects and your current objects -- just because UCM is available does not necessarily mean that you should use it.

Basically, UCM adds additional objects and workflow to the base ClearCase objects that you have already been using. So, before you embark on this change, lets first walk through some questions about the current ClearCase objects you are using:

VOBs (Version Object Base)

VOBs are just as important in UCM as they are in the base ClearCase use model. You will probably continue to use the same VOB structure that is in your current system. While you may change things around a bit to make things more efficient in UCM, you most likely won't need to do anything. Of course, you'll need to answer some basic questions about your VOB structure, most of which you may already have answered in your CM plan:

  • How are your VOBs arranged?
  • Do you have admin VOBs?
  • What is the relationship between VOBs?
  • What kind of information is contained in VOBs, and how are their directories organized?


UCM does some interesting things with Views. They are typically longer-lasting than those found in base ClearCase implementations. It's important that you answer these questions about how your views are created and removed. In addition, your config specs are generated automatically in UCM, and they may not be what you expect. It's important that you also describe your config specs so you understand the mappings from your old system to your new. Ask yourself:

  • Who can create views?
  • How often are views created?
  • Are views created automatically or manually?
  • How long do views hang around?
  • When are views removed?
  • Are the config specs created automatically?
  • Are there shared config specs?


Labels are used in so many different ways it can make your head spin. It's impossible to list all of the possible questions about labels, but if you are conscientious and build a table that contains the information for each type of label in your system, you'll be on the right path. Labels are used in UCM to help with the UCM use model. It's always good to understand the following:

  • How are Labels used?
  • When are Labels used? (Builds, Merges, Workflow control)
  • What is the naming scheme of your Labels?
  • How are Labels aged and removed when not needed?


If you are using base ClearCase without branches, then you might as well forget reading through the questions below, because essentially you don't have a base ClearCase use model. If this is the case, you can move directly to the UCM model with no mapping from your current model. In effect, you'll have to throw out whatever you currently have in place.

If you do have branches in your model, then you have a lot of work to do. The branching model for UCM uses the concept of streams, which we will discuss later. Chances are your branching model will have to be completely abandoned. On the positive side, however, your use model is probably still useable. Make sure you take the time to understand the following questions:

  • When do you create a branch type?
  • What is your naming convention?
  • When are elements moved to a branch?
  • What is your branching strategy?
  • How many people work on the same branch?
  • Do you have an integration branch?
  • What do you do with the "main" branch?
  • Do you age your branches?
  • When are branches obsoleted or removed?


As with your branches, you need to spend some time understanding the questions about merging in this section. UCM has integration points and new commands to handle the merging of code from branch to branch, which is accomplished through two concepts called delivery and rebase. Understanding why and when you merge is very important. Ask yourself:

  • When is code merged? Triggered by an event? Triggered by time?
  • Is code merged automatically or manually?
  • Who is responsible for merging code?
  • Do you allow merging from integration branches to development branches?
  • How often do you merge code from a development branch to an integration branch?


Triggers are very important in most base ClearCase systems, as they help with workflow and process control. UCM does have some policies that include the use of ClearCase triggers. Ensure that your CM plan describes your triggers and the VOBs that use them. It is important to understand:

  • What are the triggers you use and why do you use them?
  • What VOBs are using what triggers?

Basic Objects in UCM

Where base ClearCase gave us very abstract concepts like branches, labels, hyperlinks, elements, views, and VOBs, UCM provides the higher-level abstractions that we deal with every day to develop, integrate, and deliver products. These higher-level concepts are:

  • Projects
  • Streams
  • Activities
  • Baselines
  • Components

If you have been using base ClearCase for some time, you will quickly find that you have these concepts already in your system, either in documentation or in scripts. Consider it a confirmation of your brilliance that the application now offers everything you've created scripts to do -- and now it is time for you to continue to be smart and use what is available.


A project is used to refer to a group of people working on a single development effort. This can be a product release, a sub-system of a complete system, or a collection of products to form a suite. A project contains one integration stream and zero or more development streams. This is where you -- as the CM guru -- must start planning. Before you start creating projects all over the place, though, you need to sit down with marketing, your software development team, QA, and your technical writers to determine how you want to work together.

ClearCase commands for projects include: mkproject, lsproject, chproject, and rmproject.


A stream can be compared to a development branch. The stream basically groups together specific versions of elements. The key differentiator between a generic branch and a stream is the additional information stored in the stream. For example, a stream contains a baseline, and a set of activities. It also contains relationships with other streams, such as a parent stream. The baseline, plus the set of activities, determines what versions of the elements the stream contains.

Figure 1. Sample stream flow
Sample stream flow

In Figure 1, there are two activities -- Activity 1 and Activity 2 -- that have been added to the stream. The baseline is defined by the versions of the elements represented by the bold circles in the diagram. The two activities have versions of elements that represent different patterns.

There are two basic types of streams: an integration stream, and a development stream. There is one and only one integration stream for a project. In very simple projects, developers can make their changes directly on the integration stream, and every member of the project working on the stream will see each other's changes as soon as they are checked in. More complex projects might have one or more levels of development streams originating from various baseline configurations of the integration stream. In this case, developers work "privately" on their unique development stream, and project members will not immediately see each other's work. Once developers have completed their work on the development stream and are ready to share it with the rest of the project members, the development stream contents are "delivered" to the integration stream. Think of the integration streams as where all the changes from the development streams come together.

Figure 2. Sample integration stream flow
Sample integration stream flow

ClearCase commands for streams include: mkstream, lsstream, chstream, and rmstream.


A baseline represents versions of elements that are used to start a stream or to rebase a stream. A simple way of looking at baselines is to compare them to labels, the difference again being that there is additional information (including relationships) stored with baselines. Baselines are typically the starting point for many of your activities, such as creating streams, rebasing a stream, and so on.

ClearCase commands for baselines include: mkbl, lsbl, chbl, rmbl, diffbl, setplevel, and cleardiffbl.


All changes to any element in a ClearCase UCM project must be associated with an activity. An activity is the basic unit of work that your team members perform. It has the following components:

  • a headline (ID)
  • a creator
  • a change set (set of elements that have changed)
  • a stream with which it corresponds

If you are using IBM® Rational® ClearQuest®, an activity is usually tied directly to a defect or enhancement.

ClearCase commands for activities include: mkactivity, lsactivity, chactivity, and rmactivity.


A component allows you to group a set of related directories and file elements together, and then tie them to a UCM project. A component is developed, integrated, and all of its parts released together. All projects must have one or more components, and components can be shared between projects. However, a component cannot span multiple VOBs, and the largest a component can be is the size of its VOB. Other things to consider about components include:

  • Elements cannot be moved from one component to another.
  • An element can only exist in one component.
  • Once you create a component, you cannot reorganize it into sub components.

Planning your components up front is extremely important. One strategy is to put any elements that will be shared with other projects into the same component, or into groups of components.

ClearCase commands for components include: mkcomp, lscomp, and rmcomp.


A folder is basically a container for information about the project or projects. A folder can contain other folders, as well as any number of projects. Chances are you probably have been using directories in your VOB as a folder of some sort in base ClearCase. Now that folders are first class objects, you can use them instead.

ClearCase commands for folders include: mkfolder, lsfolder, rmfolder and chfolder.

Useful UCM Commands

Understanding the UCM objects is the first step to mapping your current process to UCM, but to help with your mapping there are some common commands that you should know about as well. These are basic commands that your developers will be doing often, and it is important for you to understand what it means when these commands are used.

Working on Activities

Before checking files in or out, your developers need to set an activity to the current view. The activity will keep track of changes that have been made in the view. All of these changes are kept in a change set. When delivering activities, the change set(s) attached to the activities are delivered to the integration stream so that everyone on the team can see the changes.

Delivering Activities

Once you have finished working on an activity, you can deliver your changes to the default integration stream (parent stream), or to any other stream that you choose. Streams can accept or reject changes depending on policies that have been established for the stream. The command to deliver activities is:

cleartool deliver -- This delivers changes to elements from a source stream to a target stream. The status of the delivery can be obtained with this command as well.

When the deliver begins, it creates a special activity to deliver the changes to the integration stream. This activity is created to help manage any possible merge conflicts and resolutions that may occur. Delivery can be accomplished in two steps, or in a single step. The first step is to perform the merges of elements that have changed. The second step confirms the changes and marks the activity as completed. You can force the delivery to be a one-step delivery using the complete flag.

Re-basing Work Areas

Periodically, you will want to rebase your stream from the integration streams. Remember -- your development streams usually hang around for a long time. Periodically, you will need to get updates from your team members' activities. In essence, the rebase command in ClearCase does just that: it provides the activities (and therefore changes) that other team members have delivered into an integration stream.

cleartool rebase -- Changes the configuration of the stream

Rebasing streams is a multi-step process, much like delivering activities. You can have code merging from the integration stream to your development stream, which involves moving labels and resolving merge conflicts. Just as with the deliver command, -complete can be used to mark the automatically created activity as completed (in other words, force a one-step rebase).

As a CM Manager, it is best that you provide recommended baselines against which developers can rebase their development streams. For example, a stable build could be put into the recommended base list, enabling developers to see that they are starting with code that was working at a given time.

Bringing Two Worlds Together

For those of you using base ClearCase, many of the concepts in the UCM model will probably not be very different from what you have already been doing. The key now is to map what you currently have to what UCM offers. Then you can examine the different use models available through UCM. This is not something you can do in a couple of hours -- as we've outlined, you will need to take the time to build a full CM plan. You will also need to thoroughly define what you are using today and what you want to do with UCM.

In our next two articles we will address UCM implementation planning in much greater depth.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=UCM for Zealots: Moving from Base Install to UCM ClearCase