Configuration management patterns using UCM, Part 1: Using a mainline project

Organizing release-based UCM projects

A common organizing practice in IBM Rational ClearCase is to use the /main branch to keep some order in the source tree. This article looks at how that concept translates to the UCM world as a mainline project. This is the first in a series of articles on implementation practices using UCM.


Jennie Brown (, CM Specialist, IBM Rational

Jennie Brown is a CM specialist for IBM Software, Rational Brand Services, helping customers define and implement enterprise CM systems. She is co-author, with Ueli Wahli, Matti Teinonen, and Leif Trulsson, of Software Configuration Management: A Clear Case for IBM Rational ClearCase and ClearQuest UCM.

25 October 2005

Unified Change Management (UCM) introduces the idea of a project object, a collection of streams and policies, generally organized around a deliverable body of work. Now we need some organizing principles around projects.

Released-based projects

In this example, Harvest Magic is an up-and-coming software company focusing on automated harvesting. They have two products so far, Wheat Magic and Corn Magic. The common code is encapsulated into a harvest framework. Figure 1 shows an organization of projects within the IBM® Rational® ClearCase® Project Explorer.

Figure 1. Typical organization of a released-based project set
ClearCase Explorer view if the project

Each project set is segregated by a folder. For products that have explicit release cycles, the use of release-based projects is typical. Here the Wheat Magic product has two releases in play: Release 1.0 and Release 2.0. There is also a main project, which will be discussed shortly.

The follow-on project

After Release 1.0 goes to beta, a group of senior engineers are spun off to begin development on Release 2.0. For this parallel development effort, a new project, Wheat Magic Release 2.0, is created based on the recommended baseline used for Release 1.0 beta.

The UCM Project Creation wizard provides an easy mechanism to create these follow-on projects. The second step of the wizard asks the question,"Would you like to see this project with the recommended baseline from a stream in an existing project?"

If you select Yes, the wizard will prompt you to pick a specific stream, in this case the Integration Stream of the Release 1.0 project. By default it will pick up the recommended baseline and all the project rules from the selected project. Just what you want. Almost.

The problem of ever-cascading projects

A standard follow-on project works great for the follow-on project of a first release. But fast-forward a few releases and the version tree starts to get messy with ever-cascading streams. Listing 1 shows a file listing from the fourth release.

Listing 1. Extended pathname in a fourth-generation follow-on project
cleartool ls husker.cpp

Some applications will break trying to use excessively long pathnames. In addition, the version tree becomes more and more difficult to cipher. Both problems can be fixed using a mainline project.

The mainline project

Instead of cascading projects one after another, use the mainline project as a release anchor. Here’s how it works.

When you’re ready to begin work on a new release:

  • Deliver the latest baseline from the exiting project to the mainline project
  • Create a baseline in the mainline project
  • Use the mainline as the base for your follow-on project

Using a mainline project as an anchor caps the depth of your streams. Listing 2 shows the same file using the mainline project:

Listing 2. Same pathname using a mainline project
cleartool ls husker.cpp 

Another important contribution of the mainline project is in organizing a more readable version tree. From the version tree shown in Figure 2, it is fairly easy to see that:

  • The file originated in Release 1.0
  • BL5_A1 was the base for the mainline anchor for Release 3
  • Release 3 does not yet include the latest work on Release 2
  • Release 3 does not yet include the latest code set from Release 2
Figure 2. Using a mainline project to organize releases
progress of a mainline project through subsequent integrations and releases

Also note the relationship between BL_A1 and the 3.0_init baseline. Can you tell by looking that the content of these files are identical?

The only changes made between the 2.0_init and 3.0_init baseline were changes introduced by the BL5_A1 baseline, so this will, by definition, be a trivial merge. This is what you count on to use mainline projects as anchors.

Getting started - creating the mainline project

Let’s walk through creating and using a mainline project for the new product Corn Magic.

Step 1: Create the mainline project

Since you will never be doing development on the mainline project, make the project single-stream, as shown in Figure 3.

Figure 3. Defining the mainline project
new project dialog box, step 1

It is recommended to rename the integration stream to mainline as a reminder that this is a special-purpose project.

Step 2: Allow the inter-project delivers

By default, inter-project deliveries are not allowed. Turn them on for the mainline project, as shown in Figure 4.

Figure 4. Allow inter-project delivers
defining delivery policies to the mainline

Use the standard defaults for the rest of the project definition.

Seeding a project using the mainline

The initial mainline project is now available for use. Figure 5 shows you how to create a project based on this mainline. Select Yes to seed the project based on a recommended baseline and browse to the mainline stream of the main project, here cn_magic_main.

Figure 5. Using the mainline project to seed a new release
seeding a new project from the mainline

Defining a default delivery target

When you are ready to begin your next follow-on project, first seed the mainline with your latest recommended baseline. To facilitate this step, set the default delivery target to the mainline during project setup, as shown in Figure 6.

Figure 6. Setting the integration stream to deliver to the mainline
setting an integration project's delivery target to the mainline project

Use the standard defaults for the rest of the project definition.

Delivering to the mainline

The Release 1.0 project is created and used. Eventually you are ready to set up parallel development and begin work on the next release. Since you have already set up a delivery default, just deliver the last recommended baseline to Default, as shown in Figure 7.

Figure 7. Delivering the latest baseline to mainline to seed the next project
delivering the last recommended baseline

Starting now is OK

It is never too late to create a mainline project. You can start using this technique the next time you’re ready to create a new release project. We often see mainline projects pop up at sites that have been using UCM for several years.



Get products and technologies

  • Find more resources for ClearCase users and administrators in the ClearCase area of the developerWorks Rational zone, including articles and whitepapers, plug-ins, scripts and triggers; and links to training, discussion forums, product documentation and support.
  • ClearQuest users and administrators can find more resources in the ClearQuest section of the developerWorks Rational zone, including ClearQuest hooks, Eclipse plug-ins, product documentation, articles and whitepapers.
  • To learn more about IBM Rational products, visit the developerWorks Rational zone. You'll find technical documentation, how-to articles, education, downloads, product information, and more.


  • The ClearCase discussion forum on developerWorks is a great place to post questions and get answers about configuration management and UCM with IBM Rational ClearCase.
  • To post questions and participate in discussions about change management with IBM Rational ClearQuest, see the ClearQuest discussion forum on developerWorks Rational.
  • Find a user group in your area from the Rational Global User Group Community. Rational User Groups are independent, user-run organizations that provide an open forum to promote information exchange between customers and Rational staff.


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=Configuration management patterns using UCM, Part 1: Using a mainline project