® ®

IBM Software Group

Solving UCM Mysteries

How to deploy Rational UCM and live to tell about it

Bryan Miller bryan.miller@us.ibm.com

Ralph Capasso ralph.capasso@us.ibm.com
Maneesh Mehra mmehra@us.ibm.com

1
© 2005 IBM Corporation
 IBM Software Group

What were they thinking?

 At the end of a long day… 13

 At the end of an already long week…

 Just when you were beginning to see a
light at the end of the tunnel…

A double-session on
Thursday afternoon?

You’ve got to be joking…

2
 IBM Software Group

Solving UCM Mysteries… It’s “Elementary”

 Unsolved Mysteries
 Why did UCM do THAT ?!
 Is this expected behavior? A known
limitation? A bug?
 Further Inspection
 Learning how to identify some of
UCM’s behaviors and limitations
 Understanding the finer points of UCM
beyond the user documentation
• UCM’s “rules” for change flow
• UCM’s internal mechanics
 Mysteries Solved
 Practical advice for diagnosing and
working though UCM issues and
mysterious behavior

3
 IBM Software Group

Rookie Sleuths Need Not Apply (Intended Audience)

 If you’re not already somewhat familiar with UCM, then

you’re in the wrong place!
This is not an introductory presentation
It is intended primarily for technical folks who already know UCM
 This presentation will not try to teach you UCM internals
UCM architecture is a topic unto itself and is not discussed herein
Some of UCM’s internal mechanics are uncovered in order to
explain certain UCM behaviors, but that’s as far as it goes

 Rather, this session will attempt to explain the unexplained

by both expanding your current knowledge of UCM and by
providing some practical advice

4
 IBM Software Group

Session Objectives
 After completing this session, you should be able to:
Understand the relationships between UCM components, streams, and
baselines, and the impact these relationships have on UCM change flow
operations (deliver/rebase)
Identify problematic UCM change flow scenarios and how to work through
them
Understand how to best configure and utilize composite baselines
Uncover and solve some common mysteries surrounding the CC/CQ UCM
(SQUID) integration
Make Dave Bellagio proud

5
 IBM Software Group

Just Some of the Mysteries We’ll Try to Solve

 Can’t deliver…
Anything
Selected activities
 Can’t rebase
 Can’t stabilize a baseline and/or configuration
 Don’t trust a baseline’s contents
 Can’t easily add/remove changes from a configuration
 Can’t decipher deliver/rebase warning and error messages
 Don’t understand how to properly use composite baselines
 Don’t know how to customize and/or troubleshoot the CC/CQ UCM
(SQUID) integration
 Can’t get meaningful information and/or reports

6
 IBM Software Group

General UCM Mystery Classifications

 We’ll utilize the following “cases” to

classify the different types of UCM
mysteries we’ll be trying to solve:

Change Flow (deliver and rebase)

Composite Baseline issues
CQ-enabled UCM (SQUID) issues
The “K” Files (The kitchen sink –
things that don’t fall into any of the
above classifications) Time
permitting…

7
 IBM Software Group

This Session May Seem a Little “Lost”

 Many different UCM topics are

discussed in this presentation
(It’s “all over the map”)

 It doesn’t try to focus in on one

or two particular areas
 It is intentionally broad
Contains some depth and
internals information
But it could certainly contain more
 Primary goal of this presentation
is to raise awareness to many
UCM issues and behaviors

8
 IBM Software Group

Finding Your Way

 There is a lot of material contained
within this presentation
 Don’t expect to learn the finer details
here in short order because we are
going to move quickly
 The important take-aways are
highlighted along the way
 For future reference
 More in-depth material is available
and can be used to augment the
material in this presentation
 An advanced UCM topics course (with
hands-on labs) is under development
 This will provide more time and more
detail (when it becomes available)

9
 IBM Software Group

Tools of the Trade

Police Line identifies potential danger areas

Magnifying glass uncovers UCM clues and hints

Microscope reveals UCM internal details

Decoder ring translates confusing UCM messages

The “law” explains UCM’s rules and behaviors

Handcuffs describe UCM’s policy enforcement

Ambulance is rescue vehicle for UCM casualties

Pipe identifies areas for future product improvement

10
IBM Software Group

SQUID
Change (30 min)
Flow Other
(100 min) Topics
Intro X (15 min)
(10 min) Composite
Break
Baselines
(10 min)
(15 min)

re h er e
You a

11
 IBM Software Group

UCM Mysteries – Case #1

Comp
Base onents,
line
Chan s, a
ge F nd
(a.k low
.a.
deli
reba ver,
se)

12
 IBM Software Group

Analyzing Deliver and Rebase Issues

 Sometimes UCM deliver and rebase Proj B Integration
operations do not succeed by design Policy
 A policy setting may be prohibiting the BETA ProjA Integration
operation from succeeding
 A particular change flow may not be
allowed due to UCM’s own “rules” for BL1
deliver and rebase
• Some rules exist to prevent Activity B
Dev_streamA
complete chaos and to reduce the
BL1
potential for “foot shooting”
Deliver…
• Other rules exist to promote SCM
best practices
 Other scenarios may not be allowed BL2
due to UCM’s implementation Activity A
 These are less fortunate, but should still
be viewed as “expected behavior”
nonetheless
REL 1
BL3

13
 IBM Software Group

Components, Streams, and Baselines

 Deliver operations migrate (merge) changes from one or more activities

across streams
 Rebase operations update a stream’s configuration, and only work at
baseline (not activity) granularity

 Baselines are created:

Along component boundaries
Within the context of a stream
 Projects configure:
Component visibility
Component modifiability

 Bottom Line: Understanding the subtleties of deliver and rebase

operations requires a solid understanding of UCM objects like
components, streams, and baselines

14
 IBM Software Group

Component Refresher
 Generally speaking, a component
it a set of related elements
developed, integrated, and
released together
 A UCM Component is a set of
Com
elements included in a specific
pA
VOB directory tree i li
 Root of component is called n li
b
“Component Root Directory Element” c b
b
Affectionately known internally as a
str im a
.h str tx
CRDE or “cruddy” p.h
.c t.c
flt
 Benefits .c
Reduces complexity
Promotes sharing and reuse

15
 IBM Software Group

Baseline Refresher
 Generally, a baseline is a named,
stable configuration that
represents the integrated work of
team members
im str
 A UCM Baseline… str p.h .c tx
Identifies one version of each .h t.c
element in a single component 1 1 1 1
Is immutable 2 2 2
Is created within the context of a 3
UCM stream
• Except for special baselines (e.g.
Initial, Imported baselines)
Is cumulative in that it always
contains the contents of the last
baseline plus some new activity(ies)

16
 IBM Software Group

Mystery #1: Can’t Deliver A Stream

 Can’t deliver due to tightened deliver policy settings
Exhibit A: Inter-project deliveries
Exhibit B: Foundation baseline mismatch
Exhibit C: Component visibility mismatch
Exhibit D: Component modifiability mismatch

D
A

C
B
17
 IBM Software Group

Deliver Policy Violation

 There are numerous UCM policies governing the deliver

operation
 The best way to fully understand why deliveries may be
failing due to policy settings is to make sure that you
completely understand the policies
 The good news in most of these scenarios is that the error
messages are pretty straightforward
In most cases, when a deliver operation fails because of a policy
setting, the message will usually point you in the right direction

18
 IBM Software Group

UCM Deliver Policies

 Deliver policies tab is

available for both project
and stream
 May be enabled, disabled,
or set per-stream

19
 IBM Software Group

UCM Deliver Policy Basics

 Deliver Policies
 Separate policies exist for inter-project and intra-project deliver
 Policies apply to the target stream
 Target stream decides what is acceptable to deliver
 Policy Control
 Deliver policies are controlled at project AND stream
 Project policies govern all streams in the project
 Can enable or disable a policy for the entire project
 Can defer setting to each individual stream
 Stream can enable or disable – project takes precedence

20
 IBM Software Group

Take Care When Setting/Observing Policies

 Note that some policies can override others regardless of their setting
One inter-project policy setting, when disabled will trump all others
Stream-specific policies are meaningless if the project itself does not allow
per-stream settings

In order to get the big picture of a given target stream’s

policy settings, you must look at all of the settings on both
the stream and its project

21
 IBM Software Group

UCM Deliver Policy Specifics

 The old standbys…
Allow delivery with checkouts in the source stream
Require rebase to recommended baseline(s) before delivery
 Intra-project deliveries
Allow delivery of foundation in addition to activities from the stream
Allow delivery despite source/target stream component mismatch
 Inter-project deliveries
Allow inter-project delivery in general
Allow delivery of foundation in addition to activities from the stream
Allow delivery despite source/target stream component mismatch
Allow delivery despite source/target stream component modifiability mismatch

 All deliver policies are DISABLED by default

22
 IBM Software Group

Inter-Project Delivery Example

REL1 Integration
Feature B did not
make the cutoff for
REL1
Developer delivers
REL1_BL1 REL2 Integration
changes directly to
their dev stream for
Ralph_REL1_Dev REL2
REL2_BL1
REL1 BL1

Feature A Ralph_REL2_Dev
REL2 BL1
REL1_FINAL

Feature B

23
 IBM Software Group

Exhibit A: Inter-project Delivery Policy Violation

 Inter-project deliveries are governed by an over-arching UCM inter-

project deliver policy

By default, inter-project deliveries are NOT permitted - so this error will

pop up in those cases unless/until policies are opened up

24
 IBM Software Group

Delivering Foundation Changes – An Example

 A source stream might not

be based on a baseline from
the target stream
X
X
This couldn’t happen with
UCM in CC v4.x
 Activities not created by the
developer might potentially
be delivered A
A
Perhaps accidentally
 This can be prevented with a B
B
policy on the target stream

25
 IBM Software Group

Intra-Project Delivery: Same Foundation

 Alternate target deliver operations can involve changes made in the

source stream only

Integration

BL1
Dev_stream2

Dev_stream1 BL1

BL1

Activity B

26
 IBM Software Group

Intra-Project Delivery: Different Foundation

Integration

BL1
Act 1 Dev_stream1
Act 2
BL1
BL2

Dev_stream2
BL2

My Bugfix

Delivering “My Bugfix” from

Dev_stream2 to Dev_stream1
will also deliver the foundation
baseline (BL2)

27
 IBM Software Group

Exhibit B: Foundation Baseline Mismatch

By default, deliveries that include changes from other foundations are not
permitted for both intra-project and inter-project deliveries

28
 IBM Software Group

Tweak Deliver “Foundation” Policy Settings, OR…

Integration
Alternatively, rebase
Dev_stream1 first…

BL1
Dev_stream1
BL2
BL1
BL2

Dev_stream2
BL2

My Bugfix

And then deliver the activity

when the foundations match

This alternative approach accomplishes the same

thing without opening up deliver policies

29
 IBM Software Group

UCM Will Still Notify Users if Policy is Loosened

 Setting deliver policies is really a matter of a project manager’s

preference – and is typically set based on users’ experience level

30
 IBM Software Group

Consider These Alternate Target Deliver Scenarios

Project Integration Many alternate target deliver scenarios may involve
merging more changes than you might think

BL1 DevB
BL1
DevA
BL1.1
BL1 DevB2
BL1.1

BL2 DevC
BL2
BL2.1 DevC2
BL2.1

31
 IBM Software Group

Component Visibility and Modifiability

 UCM allows a project

manager to make
distinctions as to how
UCM projects make use of
components
Producer (modifiable)
Consumer (read-only)
 These settings are visible
at the project level

32
 IBM Software Group

Visibility/Modifiability Impact on Change Flow

Change flow operations may involve changes in
components from the source stream that are not visible in
the configuration of the target stream, or are visible in the
target, but not modifiable
UCM’s deliver policies provide an effective way to prevent
deliver operations when there is a mismatch between the
source and target streams’ component configuration
• Separate policies exist for visibility mismatch and
modifiability mismatch
• Separate policies govern intra-project and inter-project
deliveries

33
 IBM Software Group

Component Visibility and Modifiability (cont’d)

 Distinct UCM projects may see different sets of components
 For projects that share some of the same components, they may still differ
in their modifiability
 E.g. Component X is visible in both projects, but only modifiable in REL1

N
Y
X
Z M

REL1 Project REL2 Project

34
 IBM Software Group

Exhibits C,D: Component/modifiability mismatch

You definitely have to read between the lines here. There are a lot of
messages about changes from foundations, etc…. But the bottom line is that
there are components (with changes) in the source stream that are not visible
in the target stream – and this violates the current policy settings.

35
 IBM Software Group

Why does UCM care about these mismatches?

 Because loosening these policies enables the possibility of partial
change sets to creep into some configurations
 UCM allows a single activity’s change set to span component
boundaries – this is a product feature
 If component mismatch policies are loosened willly-nilly, then beware
of the possibility for partial changes to be delivered

 Deliver Scenario (Partial Change Sets):

 Activity123 may have versions in its change set from both components A and B
 A developer delivers Activity123 to another project’s integration stream
 The other project only has visibility/modifiability of component B, but the deliver policy
settings that check component visibility are loosened to allow this
 Oops! Now the deliver target only picked up part of the change for Activity123

UCM project managers should fully understand the consequences of

loosening these policies (potential flexibility vs. consistency tradeoff) or else
they “shouldn’t go there”

36
 IBM Software Group

Mystery #2: Can’t Deliver Selected Activities

 Can’t deliver activity(ies) due to UCM’s deliver “rules”
Exhibit E: Individual activities from integration stream
 Can deliver activity(ies) due to dependencies:
Caused by overlapping change set versions
• Exhibit F: Created explicitly by development activities
• Exhibit G: “Forced” by rebase activities
Caused by existence of baselines in the source stream
• Exhibit H: Created explicitly using mkbl in the source stream
• Exhibit I: Created implicitly by the deliver operation

E G I
F H
37
 IBM Software Group

Under the Microscope – UCM’s Deliver Operation

 UCM’s deliver operation attempts to

create the illusion that it delivers
activities from one stream to another

 In reality, the mechanics of deliver

work slightly differently than this
UCM’s deliver operation actually creates
a(n unlabeled) baseline on the source
stream of the delivery
And then delivers that baseline to the
target stream

 The end result is the same, but the

existence of the baseline can have
some undesirable side-effects in some
use cases

38
 IBM Software Group

UCM Deliver Mechanics

Integration
 UCM always presents the abstraction that its
deliver operation works at the activity level of
granularity BL1
 In this example, a user performs three distinct deliver
operations – one activity at a time Dev_stream1
 Internally, UCM creates baselines on the source trans1
BL1
stream for each deliver operation
Activity A
 The operation actually delivers the baseline
containing the activity, rather than actually delivering
the activity itself Deliver
 The baselines created by the deliver operation are Activity B
unlabeled baselines
Deliver
Although this may seem like a subtle distinction,
Activity C
understanding the internal mechanics of UCM’s deliver
operation becomes important when trying to understand
some of UCM’s deliver rules and behaviors. Deliver

39
 IBM Software Group

Exhibit E: Integration Stream is Source Stream

 Deliver selected baselines only
 UCM does not allow activity-level granularity when the source stream
in a deliver operation is a project’s integration stream
 Integration streams must deliver using selected baselines
 Integration stream is typically the place where many UCM baselines
are created by the integrator and/or project manager
 UCM limits deliveries out of an integration stream to baselines that
have already been created in that stream

Now that we understand how the deliver operation actually works

behind the scenes, we can better understand why UCM limits
deliveries out of an integration stream to baselines.
Project managers probably would not want arbitrary baselines (caused
by deliveries) being created in an integration stream, so UCM – by rule
– prohibits this from ever happening by not allowing individual activities
to be delivered from an integration stream.

40
 IBM Software Group

Proj B Integration Source Stream is Integration Stream

BETA
ProjA Integration

BL1

Activity B
Dev_streamA
BL1
Deliver…

BL2
Activity A

REL 1
BL3

41
 IBM Software Group

Delivering Baselines

This menu is
inactive in
this context

42
 IBM Software Group

Delivering Baselines

 Integration streams are typically targets of deliver

operations, not sources of deliveries
 When an integration stream is the source of a delivery,
UCM only allows baselines to be delivered
 UCM does not allow individual activities to be delivered out of a
project’s designated integration stream

For activity-level granularity, always deliver using a development

stream as the source stream

43
 IBM Software Group

Delivering Selected Activities

 In source streams where there exist multiple activities with
undelivered work, UCM gives users an option:
Deliver all activities in the source stream (the default)
Deliver only selected activities in the source stream
 In the case of selective activity deliveries, UCM may enforce the
delivery of other “dependent” activities

44
 IBM Software Group

Can’t Deliver Selected Activities

 I’m sure you’ve probably seen this dialog box before

 There are two general classifications for activity dependencies in a source stream:
Change set dependencies (often self-inflicted)
Baseline dependencies (often UCM’s “fault”)

45
 IBM Software Group

Deliver Dependencies
 Activity dependencies take two forms:

Overlapping activity change sets

• Dependencies can be created knowingly by users who work on the
same files simultaneously across different activities in the same stream
• These dependencies can also be forced on users by rebase operations
that are performed while work is still pending in a source stream
Baselines in the source stream
• In multi-tier stream strategies, baselines may be purposely created in
development streams (that act as intermediate collection points)
• Under the covers, baselines are created by deliveries out of the stream
− These dependencies are unfortunate, and often misunderstood
− This is known limitation of UCM and can cause some customer
heartburn when they encounter this scenario

46
 IBM Software Group

Change Set Dependencies

Integration

 Change set dependencies are probably the Integration

Integration
most common (and most understandable)
form of activity dependencies
 In this case, Activity B cannot be delivered
without also including Activity A
 This is really no different than a Base-CC
findmerge operation from branch to branch BL3 77 Joe Dev
trans1
BL3
Base CC would also make you include the
changes in version 1 when merging the Joe
Joe Dev
Dev
changes from version 2 to the integration 88
branch
Activity A
UCM’s deliver operation does not allow 11 1
Base-ClearCase subtractive merge
operations under the covers (e.g. to break
Activity B
these kinds of change set dependencies by 22 2
subtracting out the delta from Activity A).

47
 IBM Software Group

Exhibit F: “Normal” (Self-Inflicted) Dependency

File1 File2 File3 File4 File5

Feature X Feature Y

Fix 101 Fix 102 Fix 103

Fix 3

48
 IBM Software Group

Exhibit G: “Forced” Dependency (Upon Rebase)

File1 File2 File3 File4 File5

Unfinished

Rebase Fix 101 Fix 102 Fix 103

Fix 3

49
 IBM Software Group

Hint: Mitigating Merges upon Rebase

 Even though there is no guarantee against having to do
merges upon rebase, it is never a bad idea to “retire” a dev
stream every so often in favor of a new dev stream
 Every stream has a distinct branch type association
A long-lived stream will have a branch instance for any element ever
modified within the context of that stream
A new stream won’t have any branch instances for elements not
modified in the stream since the stream was created
 Retiring old streams in favor of new ones will reduce the
likelihood of merges upon rebase
Best case scenario will update config spec without requiring merges
Mitigating rebase merging may also mitigate rebase dependencies

50
 IBM Software Group

Perils of Long-Lived Streams Integration

Integration
Integration
Once changes have been made to some element
in a development stream (and a branch instance
has been created in that element), then all
subsequent rebases involving changes to that
BL3
element will require (often trivial) merges – even if 77 Joe Dev
no further changes are ever made to that element trans1
BL3
in the context of the development stream.

Joe
Joe Dev
Dev
deliverA
88

Activity A
11 1

deliverX BL4
Deliver 15
15
RebseBL4
deliverY 22
Deliver 16 BL5
16
RebseBL5
33

51
 IBM Software Group

“Retiring” Dev Streams Integration

Integration
Integration

Alternatively, creating a new development

stream to replace an old (long-lived) one will
BL3
reduce the likelihood of having to perform 77 Joe Dev
unnecessary trivial merges upon rebase. trans1
BL3

Joe
Joe Dev
Dev
deliverA
88

Activity A
11 1

Joe Dev2 deliverX BL4

15
15
BL5
trans1
BL4
RebseBL4
Joe
Joe Dev2
Dev2 deliverY 22
16
16 BL5
No merges!
Rebase to BL5 RebseBL5
33

52
 IBM Software Group

Activity “Baseline” Dependency

 The existence of baselines in a source stream will impact which
activities can be selectively delivered from that stream
 In short, UCM will only allow delivery of selected activities that have
not already been included in any baseline on the source stream (not
included in any previous deliveries out of that stream)
Sometimes baselines are explicitly created in a source stream
However, many time users may not be aware of such baselines because
in some cases, baselines in a source (development) stream are created
under the covers by UCM deliveries and not explicitly by a user
Deliver baselines are unlabeled and don’t even show up (by default) in
the baseline browser GUI

Once an activity has been included in a baseline on the source

stream, then it MUST be delivered in any subsequent delivery from
that source stream.

53
 IBM Software Group

Exhibit H: “Explicit Baseline” Dependency

 Sometimes users and/or project managers will intentionally
create baselines in a development stream
This isn’t common in a relatively flat stream hierarchy
But this can be very common in a nested stream hierarchy
• Feature stream model
• Sub-team model
 When activity dependencies occur in these scenarios, they
are more understandable to end users

54
 IBM Software Group

Sub-Team (Feature Stream) Example

The project integration stream
Integration is the eventual collection point
for inter-team integration

Developers “join” the project by creating

BL1
their development streams under their
respective sub-team’s stream
Core_Team
BL1
Jim_Core_Dev Jill_Core_dev

BL2 BL1 BL1

Intermediate development
streams act as GUI_Team
“integration” streams for BL2
Chris_GUI_dev
individual teams
BL2

55
 IBM Software Group

Sub-Team (Feature Stream) Example

Integration
Developers deliver to their sub-team
“integration” stream
BL1
…And subsequently rebase
from baselines created there
Core_Team
BL1
Jim_Core_Dev Jill_Core_dev

BL2 BL1 BL1

CORE_BL1

GUI_Team
BL2
Chris_GUI_dev
BL2
GUI_BL1
56
 IBM Software Group

Sub-Team Example Simplified

Integration In this case, a developer could still (alternate
target) deliver the original Activity B directly
from the development stream to the integration
BL1 stream in order to achieve the desired effect.

Core_Team
BL1
Jim_Core_Dev Jill_Core_dev
CORE_BL1
BL1 BL1

deliverA
BL2 Activity A Activity B

deliverB
Deliver Activity C

CORE_BL2

Only “deliverC”A baseline is intentionally

and “Integ Act” (the two
deliver C
activities not created
already in this intermediate
included in a baseline
stream asstream)
on the Core_Team a checkpoint (for dev
are eligible for
selectivestream rebasing purposes)
Integ Act
delivery from this stream

57
 IBM Software Group

Exhibit I: “Deliver Baseline” Dependency

 Two sibling development streams exist within a
UCM project
 Developer 1 works on several activities in the Integration
context of Dev_stream1
 Developer 1 delivers only a selected activity
(Activity A) to Dev_stream2 BL1 Dev_stream2
 This is an alternate-target deliver scenario trans1
BL1
 Developer 1 now tries to deliver a different Dev_stream1
selected activity (Activity B) to the project’s trans1
BL1
integration stream
 A default-target deliver scenario Activity A
 UCM complains that Activity B has
dependencies on Activity A Deliver
 Developer 1 must include activity A when
delivering to the integration stream (because Deliver Activity B
Activity A is now in a baseline)
 Even though activity A and activity B have NO
CHANGE SET DEPENDENCY!
The existence of this (unlabeled) deliver baseline
forces the inclusion of Activity A for any subsequent
deliveries out of Dev_stream1

58
 IBM Software Group

Solving the Mysteries of Activity Dependencies

 Obvious solution – deliver everything or minimally the selected activity
and its dependents (not ideal if that’s not what you want to do)
 Working in a one-activity-per-stream model will always avoid this
particular problem by isolating work on each activity in its own stream
This model introduces more overhead and potentially more complexity
 Drop down into base ClearCase and do some subtractive merging
Dave Bellagio’s cset script is capable of doing this today
 Will the product itself ever offer relief in this area?
• There are no current plans to offer subtractive merges via the UCM deliver
operation in order to break change set dependencies
• Baseline dependencies are a big limitation and a known problem for
customers – and it would be highly desirable to “fix” this problem
− However, there are some clever workarounds to this problem

Longer term, the next-generation UCM solution won’t suffer

from these types of limitations

59
 IBM Software Group

One-Activity-Per-Stream Model
 Create a new stream for each new activity
 No development stream ever contains more than one activity
 Pros
 Complete activity independence
• Won’t be forced to combine activities if not desired
 Ability to create configurations with arbitrary combinations of activities
 Cons
 “Porcupine” models are high-overhead
• These models require many streams (and merges)
 UCM provides few conveniences to work this way
• “Join Project” wizard may not apply
− Probably favor a straight “create stream” approach for new activities
− New activity must be created as an additional step
• Not SQUID-friendly out of the box
− The WorkOn action cannot create a new stream on the fly

60
 IBM Software Group

One-Activity-Per-Stream Example
A single integration stream is
Integration usually the collection point for
all changes within a project A new development
stream is created for
BL1 each new activity
Feature A
Bugfix 123 Feature B BL1
BL1
Each activity is
BL1 BL1
worked in isolation,
Feature A
BL2 independent of all
Feature B others

Bugfix 456
Bugfix 123
BL2
Activities may
be delivered in
any sequence
Bugfix 456

61
 IBM Software Group

Workaround to Deliver Baseline Dependency Issue

 Can’t deliver selected activity because of a previous delivery from the
source stream to an alternate target
 Create a new activity in the development stream
This activity will be “beyond” the deliver baseline that is causing the dependency
problems
 Move the changes from the originally delivered activity’s change set to
the new activity that was just created
 Remove the original activity from the source stream
 Attempt to deliver the selected activity again
This delivery will succeed without delivering the changes in the original activity’s
change set
The new activity – even though it contains the same changes, is no longer a
dependency because it is not included in a baseline

62
 IBM Software Group

“Deliver Baseline” Dependency Workaround

 An original activity is created and delivered
(alt-target) to a sibling development stream
 Another activity is created, but when Integration
attempting to deliver only this activity to the
project’s integration stream, it is flagged as
dependent (because of the deliver baseline) BL1 Dev_stream2
 Create a new (workaround) activity in the trans1
BL1
same source stream Dev_stream1
 Move the change set versions from the original
trans1
BL1
activity to the workaround activity
 Remove the original activity (this is possible Original
because its change set is now empty)
 Now attempt the delivery again
 Deliver will not complain about dependencies Deliver
because the original activity is no longer in the Deliver Another
source stream Deliver

Success! Workarnd

Be aware, however, that when you use rmact, you may

see strange reporting when using diffbl and/or lsact –
contrib (because the original activity is no longer there)

63
 IBM Software Group

Using cset.pl to Move Changes (when deliver won’t)

 As a last resort (if all other workarounds aren’t
acceptable for a given case), you can use the
cset.pl script – obtained internally
 This script is not officially part of the ClearCase
product (it is custom script)
 Using this script is really just an automated
equivalent to dropping down into base
ClearCase and using fancy merging techniques
(e.g. merge -insert)
 Be aware that by doing this you may be inhibiting
your ability to track your changes back to the
original activity
 In this illustration, cset.pl –move is used to
effective “move” a single activity’s changes from
Project_2’s integration stream into Project_1’s
integration stream
 UCM’s deliver operation would prohibit this
operation because it only allows baselines (not
individual activities) to be delivered between
integration streams Always beware of the side-effects of using base-
CC merge techniques within a UCM environment

64
 IBM Software Group

Mystery #3 – Can’t Rebase or Recommend Baseline

 Can’t rebase in any direction or even recommend baselines
Exhibit J: Because baseline is not contained in parent
Exhibit K: Import baselines are not “real” baselines
 Can’t rebase backwards and/or “sideways”
Exhibit L: Because changes exist in the stream
Exhibit M: Identical baselines were created in the stream
Exhibit N: Baselines were implicitly created by composites

J L N

K M
65
 IBM Software Group

Rebasing Streams: A Refresher

 Normally rebase to recommended baselines
This is always the default rebase behavior
 Can also rebase to arbitrary baselines selected by the user
Subject to validation by the stream
 Five cases:
Advance to successor
Revert to predecessor*
Move “Sideways”*
Add new component
Drop component*

* Restricted operations

66
 IBM Software Group

Rebase “Direction”
 Advance – New foundation baseline contains current foundation
 Revert – New foundation baseline is ancestor of current foundation
 Sideways – New foundation baseline is neither ancestor or descendent

IntStream IntStream IntStream

Project2

BL1 DevStream BL1 BL1 DevStream P2.1

BL3
BL1 DevStream
P2.2
BL1
BL3
BL1
BL2 BL2 BL2
P2.2

BL3 BL3 BL3

P2.3

Advance Revert Sideways

67
 IBM Software Group

Two Important Things To Know About Rebase

 Advancing is by far the most natural and common rebase direction
 Reverting and moving sideways are less common, but can be very
useful in certain circumstances
 Sideways and backwards movement are not always permitted in
every rebase scenario – and may often fail without users
understanding the reasons why

 Determining whether backwards and sideways rebase are permitted

depends primarily on two things:
Whether changes have been made in the stream being rebased
The ancestry of the stream being rebased, and whether the new
baseline(s) are contained in the stream’s parent

68
 IBM Software Group

“Rules” for Rebase

Advance – New baseline already contains current foundation
• Rebase in this direction is always allowed
• Changes are merged in the view if needed
• Many cases have no merge, rebase just updates the config spec
Revert – New baseline is an ancestor
• Allowed if there are no changes to the component in the stream
• Always allowed on read-only streams

 Sideways – Neither ancestor nor descendent

 Allowed if component is non-modifiable and there are no baselines (ident
baselines) on it, OR

 If the new baseline would not strand changes in the stream (or its child streams)
AND the stream would only be delivering its own changes to its parent

69
 IBM Software Group

Sideways Rebase Rules Explained

 This confusing Verbiage:
 No (child) stream would have stranded changes
 Stream would only be delivering its own changes
 Can be more clearly restated as:
The new baseline must be contained in the parent stream

Rel_1.0

trans1 Dev_stream2
trans1
Build_stream trans2 Dev_stream1
trans2
trans1

trans2_deploy

The development streams are only allowed to rebase to trans2_deploy

after Build_stream has delivered its work to the integration stream
70
 IBM Software Group

The “Contained In Parent” Rebase Rule

 Rebase allows a stream to pick up changes from another

stream provided those changes have been delivered to its
own parent
Ensures that the default deliver to a parent stream delivers
changes from your stream
Requires integration one level higher than you
 The rules for recommending baselines are consistent with
the rules for rebase
UCM will allow a parent stream to recommend a baseline that was
not created in that parent
…As long as the parent stream also sees those changes

71
 IBM Software Group

Stream Ancestry - Terminology

Integration
Grandparent
Parent

BL1
Parent
Child
Dev_stream1
BL1 Child
DEVBL1
Dev_stream1A Dev_stream1B
DEVBL1 DEVBL1

Siblings

72
 IBM Software Group

Stream Ancestry – Terminology (cont.)

Integration

BL1

Dev_stream1 Dev_stream2
BL1 BL1
DEV1BL1 DEV2BL1
Dev_stream1A Dev_stream2A
DEV1BL1 DEV2BL1

Cousins

73
 IBM Software Group

Who’s your daddy?

 A very important question when it
comes to the rebase operation
 Whenever a rebase operation is
performed (and is subsequently
disallowed) – check the parent
stream’s foundation

 When setting up projects and

stream strategies, always keep
this in mind
 You may not be allowed to
rebase to desired baselines if
you don’t establish appropriate
relationships between your
projects and streams

74
 IBM Software Group

Exhibit J: UCM Genealogy Lesson

Mainline Project

BL6 Project N

Had Project Z been founded from a baseline created in

the mainline project (and not a baseline created in
BL7 BLN1 Project N), then this rebase would have been
successful. In this particular setup, Project N’s
integration stream must contain BL9 in order for this
BLN2
rebase operation to be successful.
Deliveries from
other projects
BL8 BLN3
Project Z

BLN4 BLZ1

BL9
This failed rebase scenario
came up recently at a customer
deployment
75
 IBM Software Group

Sidebar: Alternate Target Deliver vs. Rebase

 In many scenarios, it may be possible to create a given
configuration by using either rebase OR deliver
 Is one method any “better” than another?
 Often – rebase is more efficient than deliver because it
can reduce the amount of merging

 Example:
 Two sibling development streams want to share work
 Alternate target deliver allows them to share by merging
work from one stream to the other
 Q: What about using rebase? Can one stream rebase to
baselines created by the other development stream?
 A: Only if the changes are included in the parent stream

76
 IBM Software Group

Sharing via Alternate Target Delivery

Developer1 and Developer2
Integration
want to share changes without
going through the integration
stream
BL1
Dev_stream1
Dev_stream2 BL1
BL1
BL1

My Bugfix

Deliver the activity directly from

one development stream to the
other

77
 IBM Software Group

Sharing via Rebase

Developer2 creates a baseline
in their development stream
Integration with the intention that
Developer1 can rebase to it

BL1
Dev_stream1
Dev_stream2 BL1
BL1
BL1
First attempt to
rebase will fail
My Bugfix because the BL
is not included in
Dev_stream1’s
DEV_BL parent
Deliver the changes to
the integration stream
(the parent for both of
these dev streams)

78
 IBM Software Group

Sharing via Rebase

Developer2 creates a baseline
in their development stream
Integration with the intention that
Developer1 can rebase to it

BL1
Dev_stream1
Dev_stream2 BL1
BL1
BL1

My Bugfix

DEV_BL
Deliver the changes to The rebase will
the integration stream now succeed
(the parent for both of
these dev streams)

79
 IBM Software Group

Exhibit K: Rebase and Imported Baselines

 “Import Baselines” are a handy mechanism for creating a starting
point for new UCM projects
From past Base-ClearCase labeled configurations
From past history imported form a conversion tool
 Imported baselines are not so handy when used as “general
purpose” UCM baselines
Import baselines are special-cased – they are not “real” baselines
Import baselines are not recorded in a stream’s “timeline”
 Imported baselines were only designed to be UCM “starting points”
(foundations of a new stream)
 Any other use of import baselines (e.g. rebase) will likely have some
functional limitations

80
 IBM Software Group

Imported Baselines as Stream Foundations

main
main Use imported baselines as the foundation for new
UCM streams. This can save unnecessary
merging between Base CC and UCM when
77 starting new UCM projects.

REL1 Rel2 Integration

88 REL1
REL1

REL2_Integration
REL2_Integration

LABX
15
15 11

LABY Rel3 Integration

16
16 LABY LABY
13
13 REL2
LABZ Rel4 Integration
17
17 LABZ LABZ

81
 IBM Software Group

Imported Baselines are not “Full Service” Baselines

They can be used effectively as foundations

for new UCM streams, but…

Imported baselines are not

created within UCM streams

Rebase?

82
 IBM Software Group

Rebase Between Two Imported Baselines

main
main
These imported baselines were created from Base-
CC labels and were not created within the context of
77 a UCM stream (like a “normal” baseline). UCM has
no context (e.g. streams, timelines, activities) within
REL1 which to compare these “baselines” in order to
Rel2 Integration perform an actual UCM rebase operation
88
REL1 REL1

REL2_Integration
REL2_Integration

LABX 11
15
15 LABX

Rebase LABX

Use the least common denominator (Base CC) to move changes

between Base-CC branches and UCM streams. Findmerge, for
example, could be used in this scenario to effectively “rebase”..

83
 IBM Software Group

Rebase Between Two Imported Baselines (cont’d)

This error message doesn’t seem very appropriate for this scenario (you’re probably
well aware of the fact that you’ve made changes based on the current baseline).
What UCM is really trying to tell you is that you are attempting to rebase between
two imported baselines (on a stream that contains other changes).

84
 IBM Software Group

Exhibit L: Changes Exist in the Stream

 UCM baselines are immutable and their contents are cumulative

(inclusive of all previous baselines)
 Therefore, rebase in any direction other than advancing is subject to
validation by the stream
 “Backwards” rebase is the most constrained rebase direction because
it is prohibited if changes exist in the stream being rebased
 Under the “rules” of rebase, backwards rebase is only permitted when
no changes exist in the stream being rebased
Read-only streams can always be rebased backwards

According to UCM’s “rules”, backwards rebase is

only permitted on streams with no modifications

85
 IBM Software Group

Backwards Rebase Illustrated

 A stream containing no changes is not Integration
restricted from rebasing backwards
 No branch instances for that stream exist
in any elements BL1 Dev_stream2

 Reverting in this case simply replaces trans1

BL1
BL1
BL2
Deliver 1
the foundation baseline Dev_stream1

Revert BL1
 A stream that contains changes may trans1
BL1
BL2
Deliver 2
not revert to a predecessor baseline
 This is true whether the changes in the
stream conflict with the existing baseline BL2
or not
Activity A

Revert BL1
Backwards rebase is not a silver bullet for
removing unwanted changes from a stream that
contains other work

86
 IBM Software Group

Exhibit M: Identical Baselines

 UCM will not (by default) create new
baselines on a stream when no
changes have occurred since the
previous baseline
 UCM has always allowed identical
baselines to be created on a stream
(using the mkbl –ident switch)
 Identical baselines may seem quite
harmless (and perhaps even useful)
on the surface…
 Beware: These friendly clones could
actually behave more like evil twins

87
 IBM Software Group

Why mkbl –ident can be a dangerous thing

 Some customers use mkbl –ident in order to force a common
naming scheme across baselines that were created at the
same time
This may seem like a clever solution to this problem
Composites and/or templates are probably a better solution
 Gratuitous usage of mkbl –ident can prevent cases of
sideways and backwards (revert) rebase – even when there
are no changes on the stream being rebased
Because mkbl –ident force-creates new baselines in a stream, even
when new baselines are not required

You can really paint yourself into a corner and take away a lot of rebase
flexibility if your UCM process involves frequent usage of mkbl –ident. Even if
there are no changes in a stream, identical baselines will make the UCM
rebase operation behave as if there are changes in the stream

88
 IBM Software Group

Sidebar: Recommending Baselines

 UCM attempts to enforce the notion that users should

always be successful rebasing to recommended baselines
 UCM will not allow a parent stream to recommend a
baseline to which its children cannot successfully rebase
 Therefore, the act of recommending baselines validates the
baseline(s) that a parent recommends to its children

A child stream may be configured with any of:

• A baseline created in its parent stream

• A baseline in the parent’s foundation
• A baseline created in a stream other than its parent (in the
same project), and is contained in the parent

89
 IBM Software Group

Exhibit N: Nested Composite Baseline Override

 Mathlib, Alpha, and Gamma are composite baselines
 Alpha and Gamma both contain a baseline of component C, and these are
in conflict with one another
 User must override component C (with C5) to resolve this conflict

Mathlib1 C5
C5

Alpha1

F2
A1 C3

Gamma2

B2 C1
C1 E1

90
 IBM Software Group

Overrides are Modifications

 Mathlib makes changes in F and needs a new baseline

Mathlib1 C5
C5

Alpha1

F2
A1 C5
C5
C3 Gamma2

B2 C1
C5
C5 E1

 Where are the changes?

Component F
Also: Components Alpha and Gamma

(Because there is a new member of component C visible)

91
 IBM Software Group

Rootless Changes Won’t Restrict Rebase

 Project delivers a single (composite) baseline
 Root of this baseline is on a rootless component
 Greater flexibility for customer-projects

Mathlib1

Alpha1

F2
A1 C5 Gamma2

B2 C1
C5 E1

The GA versions of v2002 and v2003 are restricted – even for rootless
composites. You will need a patch or SR in order to obtain the
changes that loosen the rebase restriction for rootless composites.

92
 IBM Software Group

Mystery #4: Deciphering Deliver/Rebase Messages

 Exhibit O: Deliver can’t merge some elements
 Exhibit P: Deliver informed me that it was
“skipping” some elements
 Exhibit Q: Deliver errors during posted deliveries

O P

Q
93
 IBM Software Group

Exhibit O: Deliver Non-mergeable Element Types

 The Problem
UCM can’t generate a config spec to do the potentially easiest thing
• E.g. Never branch non-mergeable elements
• This is a one-line addition to a config spec in base CC
• Adding custom config spec rules to UCM won’t help in this case
ClearCase also has no concept of “universally reserved” checkouts
• To ensure no one else is ever modifying a given element on any branch

 The UCM Solution

UCM can only support a “branch and never merge” or “branch and copy
merge” model, it can’t support a “never branch” model. Choices:
• Branch all non-mergeable elements and leave them hanging
• Branch all non-mergeable elements and “copy-merge” them

94
 IBM Software Group

The Problem Illustrated

95
 IBM Software Group

A Solution: Use Merge Type Attributes

 Merge type attributes are supported by deliver and rebase
 Implemented via element type attribute called mergetype
 Merge types are created on custom element types using mkeltype
 The currently supported merge type attributes are:
 Auto (default)
• deliver/rebase will automatically merge elements using the element’s specified
ClearCase type manager (this is why deliver/rebase won’t work by default)
• Probably want to try to avoid these scenarios when dealing with binaries and other
non-mergeables as deliveries will always require manual intervention
• Only use this attribute on mergeable element types
 User
• deliver/rebase will automatically perform trivial merges by “copy-merging”
• non-trivial merges must still be done manually
• Example: user this attribute on VB Forms (*.frm, *.frx) and .NET artifacts
 Never
• deliver/rebase does not merge these files at all
• Example: use this attribute on type on staged DO elements

96
 IBM Software Group

Merge Type Attribute Example

 Create a new element type called “image” and attribute the new
element type with the “user” merge type:

O:\class_comps\compA\junk>cleartool mkeltype -nc -super

compressed_file -mergetype user image
Created element type "image".

97
 IBM Software Group

Merge Type Attribute Example (cont.)

 Create new elements of the new merge type “image”
 Modify those elements (and others) in a development stream
 Deliver the changes to the integration stream

Binaries of element type “image”

98
 IBM Software Group

Merge Type Attribute Example (cont.)

 Start the delivery

99
 IBM Software Group

Merge Type Attribute Example (cont.)

 Observe the version history of the two “image” elements

100
 IBM Software Group

Merge Type Attribute Example (cont.)

 During the delivery…

101
 IBM Software Group

Merge Type Attribute Example (cont.)

 Manually merge the non-trivial image

102
 IBM Software Group

Merge Type Attribute Summary

 Merge type attributes can be used effectively in dealing with binaries

and other non-mergeable element types in deliver/rebase scenarios
Use the “user” merge type to automatically “copy-merge” trivial changes
Use the “never” merge type to ignore changes altogether
Use the “auto” merge type for all element types that can be merged by a
known type manager
 As we saw, some of these merge types can help automate the
delivery of non-mergeable element versions
However, there are no guarantees of fully-automated merges in all cases
 Caveats: Prior to v2003, there were some scenarios whereby the
“user” merge type did not work as advertised because of bugs in the
deliver operation (not properly identifying some trivial merges)
These were fixed in v2003

103
 IBM Software Group

Exhibit P: Skipping Elements Upon Deliver/Rebase

 Sometimes deliver and/or rebase will notify
the user that some elements are being
“skipped”
 These warnings are most visible when running
the operations from the CLI
 From the GUIs, rebase warnings tend to be
more visible than deliver warnings
 Typically, this is caused by directory
changes (e.g. rmname) in one stream that
conflict with changes in another
 Take care to understand the details of what
it being skipped so that changes don’t “fall
on the ground”
 Or else you may experience the “now UCM
(you see ‘em), now you don’t” phenomenon

104
 IBM Software Group

Skipping Elements Scenario

 A versioned directory in a modifiable
component is modified such that an element is
removed in the context of the project’s
integration stream
 A developer working in a development stream
modifies that element (but may not actually
modify the directory itself)
 Upon delivery, the changes made to the
element on the development stream will not
be delivered to the integration stream because
the element is no longer visible there
 A user has to catch this warning in the deliver
details or else they may not know that their
changes were not delivered
 Upon rebase to a baseline that includes a
version of the directory with the element
removed, rebase will warn the user that it is
“skipping” the element

105
 IBM Software Group

Skipping Elements Illustrated

Integration Development
trans1

Same Foundation

n+1 n
Deliver

rmname

106
 IBM Software Group

Skipping Elements (cont’d)

Even if nothing more is done, this deliver operation may

still be completed (this is just a warning error).
However, to avoid problems down the road, it might be
a better idea to remove the offending change (rmver –
xhlink) from the dev stream activity’s change set and
redeliver without the conflicting change.

107
 IBM Software Group

Skipping Elements (Rebase)

Note that if you actually want to keep the changes and reverse the effects of
the rmname operation (upon either deliver or rebase), then you can make the
element “reappear” within a directory by using the “cleartool ln” command.
You might also use “cleartool find . –all –nvisible –print” within a directory to
locate any potentially “missing” elements.

108
 IBM Software Group

Exhibit Q: Posted Delivery Failure

 Error retrieving delivery state for stream
'stream:Dev_Stream2@pvob'
Stream Dev_stream2, mastered at USA, does not match project
vob, mastered at India.
Stream Dev_stream2, mastered at USA, does not match project
vob, mastered at India.
Stream must be mastered locally to perform deliver operation here.

Wait a minute…
The deliver operation is supposed to detect when the target stream is remotely
mastered and “post” the delivery. Isn’t that a UCM feature?

It is, but that’s not exactly what’s happening in this case. This scenario can be as
confusing as the error message itself. In this case, UCM is actually trying to tell
you that there is already a posted delivery in progress, and that this new delivery
cannot be posted until the first one has been completed.

109
 IBM Software Group

Can’t Post Delivery in a MultiSite Environment

Integration

Site: India Site: USA

BL1
Dev_stream2
Dev_stream1 BL1
BL1
BL1
Delivery of Activity A
is completed
normally Activity A Activity B

Delivery of Activity B
is posted, but not
completed
Posted delivery
of Activity C fails
Activity C
This posted delivery of Activity B temporarily changes the
mastership of Dev_stream2 to India. This prohibits any subsequent
delivery from Dev_stream2 until the first posted delivery has been
completed at the remote (mastering) replica.

110
 IBM Software Group

Mystery #5: Can’t Stabilize a Baseline

 Exhibit R: Use Stabilization Streams
 Exhibit S: Selective Baseline Creation

R
S

111
 IBM Software Group

Integration Streams are “Moving Targets”

 Baselines contain changes from many streams

 Developers can rebase to recommended baseline(s) before
delivering their changes, but new changes keep arriving
 The larger the project, the larger the volume (and frequency) of new
deliveries to the integration stream
 Desire to stabilize a baseline from the integration stream,
 But that may involve making more changes on top of the baseline
 This cannot easily be done when new changes have already been
introduced to the integration stream
 The integration stream wants to recommend a baseline that
contains changes from its stream, plus any changes needed to
fix problems in that baseline

112
 IBM Software Group

Volatility of the Integration Stream

Integration  Two O'clock and all is well
A new baseline (BL2) is created on the
integration stream
BL1 This baseline represents the “tip” of the
stream
BL2 Would like to test this baseline and
potentially recommend it to other streams
Deliver 1
 Three O'clock and things have changed
Testing reveals that minor changes must be
Deliver 2
made to BL2
Deliver 3 However, by this time, many new deliveries
have cluttered up the integration stream

113
 IBM Software Group

Things Look Different Than They Used To…

Integration
 New Deliveries Have Arrived… Now What ?
 A new baseline on the integration stream at 3:00 will
now include BL2 plus all of the new changes
 I may not want those changes in my baseline, and
BL1
even if I did, I still may have similar stabilization issues
because deliveries could continue coming in
BL2  Consider These Options
I. Lock the stream until the baseline can be stabilized
Deliver 1 and recommended (potential bottleneck)
II. Create a new baseline but only include the old baseline
Deliver 2 plus the stabilization work (mkbl –act) without including
the new deliveries (subject to dependencies)
Deliver 3 III. Create a “stabilization stream”

Stabilization streams don’t have as many

drawbacks as the first two options

“I don’t recall seeing all of these activities here before”

114
 IBM Software Group

Exhibit R: Using Stabilization Streams

 Stabilize configurations by isolating the work in one or more
component baselines to a different stream
 This stream can then be used for build stabilization or for QE
testing
 Fix errors or testing defects in the stabilization stream
 Create a baseline in the stabilization stream
 Deliver that baseline to the integration stream
 This is a key step
 The project’s integration stream can only recommend this baseline to
its child streams if the baseline is contained within the stream itself
 Recommend the baseline from stabilization stream
 Development streams may then rebase to the more stable
baseline rather than one created on the integration stream

115
 IBM Software Group

Using Stabilization Streams – An Illustration

Integration BL2-STAB may be recommended once the
BL1 is
recommended changes are seen by the integration stream.
The development stream can then rebase.
BL2 is created, BL1
but not stable Dev_stream1
BL2-STAB
BL1
BL2

Influx of new Deliver 1 Stabilization

deliveries makes it BL2
nearly impossible Deliver 2
Stab
to try to stabilize
BL2 directly on the Create a stabilization stream
Deliver 3
integration stream from BL2 and make changes
necessary to stabilize the BL
BL2-STAB
Deliver to the Create a stable baseline
integration stream

116
 IBM Software Group

Exhibit S: Creating “Selective” Baselines

 Stabilization streams provide much flexibility, but also impose the
overhead of a new stream, recommending baselines, etc…
 Alternatively, in some cases it may be possible to create selective
baselines using the “mkbl –act” command
Create a baseline that includes the last baseline plus selected activities
The activities included in a selective baseline are subject to change set
dependencies (similar to selective activity delivery)
 Many customers have tailored their UCM processes around using
mkbl –act to create their baselines
This technique has its advantages, but it also has its limitations

Whether to employ a selective baseline technique vs. creating

stabilization streams vs. some other method is really a matter of
preference. Each solution has its own set of pros and cons.

117
 IBM Software Group

Creating Selective Baselines – An Illustration

Integration This technique cannot be relied upon if there are
BL1 is any change set dependencies between the
recommended activities that you wish to include in the selective
baseline and the activities that you wish to
exclude from the baseline.
BL2 is created, BL1
but not stable Dev_stream1
BL2-STAB
BL1
BL2 BL2
Influx of new Deliver 1
Stab
deliveries makes it +
difficult to stabilize Deliver 2
BL2 on the
integration stream Deliver 3 = BL2-STAB

Create a stabilization
Stab
activity directly on the
integration stream
Create a selective stable
BL2-STAB
baseline (mkbl –act)

118
 IBM Software Group

Selective Baseline Behavior (v2002 and v2003)

 The default behavior for “mkbl –act” changed between
v2002 and v2003
The change was introduced to fix a defect with the “diffbl” command
Unfortunately, the fix to the diffbl problem further restricts “mkbl –act”
in v2003
 This change was not documented in the release notes
 This upset many customers who had come to rely upon
using the “mkbl –act” command to create baselines
The new restrictions in v2003 enforce tougher dependency checking
on the activities to be included in any selective baseline
Change were included in a v2003 SR to effectively “reverse” the
effects of these changes (at the risk of re-introducing the “diffbl”
defect). With the SR installed, customers can choose which
behavior they prefer. Unfortunately, there is no solution today which
provides a solution to both issues.

119
 IBM Software Group

We’re only scratching the surface…

 The previous examples are only a couple of potential solutions to
frequent configuration management problems
 You can imagine other techniques for isolating and subsequently
integrating change to stabilize configurations
 Branching and merging techniques are topics in and of
themselves and are even the subject of some SCM books
However this is not the primary motivation of this session…

 Just remember that different groups have different isolation and

integration needs
It would be naïve to think that there is some one-size-fits-all technique for
doing effective parallel development
I still cringe a bit when our marketing refers to UCM as a “process”

120
 IBM Software Group

Mystery #6 My Baseline is Lying to Me

 Exhibit T: Partial Change Sets Upon Delivery (Recap)
 Exhibit U: Partial Change Sets Upon Rebase
 Exhibit V: Partial Change Sets When Creating Baselines

U
T
V
121
 IBM Software Group

Symptoms of Partial Change Sets

 Diffbl might tell you that activities are included in a given baseline when,
in fact, they are not (at least not the entire activity’s change set is not
included)
 The lsactivity command may tell you about contributors to an activity
that may not really have contributed at all

122
 IBM Software Group

Exhibit T: Partial Change Sets Upon Delivery

 Earlier we discussed the value of UCM’s deliver policies and how
tightening those policies can decrease the likelihood of creating
configurations with partial change sets

 Deliver Scenario (Redux from earlier):

 Activity123 may have versions in its change set from both components A and B
 A developer delivers Activity123 to another project’s integration stream
 The other project only has visibility/modifiability of component B, but the deliver policy
settings that check component visibility are loosened to allow this
 Oops! Now the deliver target only picked up part of the change for Activity123

We already discussed this earlier, but it’s worth mentioning again

123
 IBM Software Group

Exhibit U: Partial Change Sets Upon Rebase

 We’ve seen how loosening some deliver policies could enable partial change
sets to creep into a target stream’s configuration
 Note that this can also happen upon rebase (where no UCM policies exist to
completely protect you from avoiding it)

 Rebase Scenario (Partial Change Sets)

 Activity123 may have versions in its change set from both components A and B
 A developer delivers Activity123 to the integration stream
• An integrator creates new baselines for both components A and B
 Another developer rebases their dev stream just to the new component A baseline
• Oops! Now they’ve only picked up part of the change for Activity123

Unlike deliver, there are no policies to protect a user from picking up partial
changes via rebase (since rebase works at the baseline level of
granularity). If an activity’s changes span component boundaries, then this
risk must be mitigated by best practices and not by the rebase operation

124
 IBM Software Group

Deliver Policies Don’t Mitigate All Potential Risks!

 Other (non-deliver) scenarios can also expose partial change sets
 UCM provides NO policies to govern partial change sets for the following:
Changing a project’s recommended baselines
Rebasing to baselines other than recommended
Setting up the foundation of a new project/stream
 In addition to tightening deliver policies, a PM might also consider:
Avoiding activities whose change sets gratuitously span components
• And potentially writing triggers to enforce this
Use composite baselines to ensure that related baselines of components are
always used together whenever change sets do span component boundaries
Avoiding partial change sets when new baselines are created

Tight deliver policies are only one mechanism that may be employed to
mitigate the risk of partial change sets. Project managers and users alike
must employ other techniques for avoiding partial change sets during
baseline creation and during rebase.

125
 IBM Software Group

Exhibit V: Partial Change Sets During mkbl

 An individual component baseline itself may contain

partial change sets from included activities
UCM does not validate whether an entire activity is physically
included in a baseline at the time when the baseline is created
 Example – running mkbl while a delivery is in progress
may capture only part of a delivered activity
 A baseline that contains only a partial change set will still
report that it contains a certain activity, however only
some of the versions in its change set might actually be
labeled by the baseline

126
 IBM Software Group

Avoiding Partial Change Sets During mkbl

 The mkbl command is not an “atomic” operation
 Tips to mitigate the risk of partial changes in baselines:
Lock the integration stream before creating baselines
• This is something that the UCM documentation recommends
• Not always possible or feasible in some shops due to the
inconvenience it may cause on the integration stream
If the stream cannot be locked efficiently, check the consistency of
baselines with a trigger or some other mechanism – post baseline
creation

Deliver and rebase aren’t the only operations to watch out for.
Baseline creation should also be an area of concern.

127
 IBM Software Group

Mystery #7: Can’t “Back Out” Deliveries

 Deliver and rebase can be cancelled before completion
 Cancellation effectively nullifies the operation and reverts to “old” configuration
 Once completed, UCM provides no out-of-box way to “undeliver” changes from the
target stream’s configuration
 This is a frequent customer complaint

128
 IBM Software Group

UCM has no formal “undeliver” command

Integration
 UCM’s deliver operation allows a delivery to be
“undone” – prior to the completion of the delivery
 Once complete, however, UCM provides no
mechanism for removing a delivery from the
target stream’s configuration
Deliver 1

Deliver 2

Deliver 3

Deliver 4
Individual activities cannot simply be “pulled
out” of a stream’s configuration

129
 IBM Software Group

Strategies for Removing Unwanted Deliveries

 Trivial case (no descendents) can be easily scripted
 Query the change set of the “offending” activity(ies), then rmver –xhlink the change
set versions, and then rmact the deliver activity

 Non-trivial cases could also be effectively cancelled out with scripting

 Create an “anti-activity” that effectively removes the offending changes
 Subtractive merges would have to be performed in cases of dependent changes
• The cset.pl script can be used in this capacity

 Start a new “integration” stream that effectively “backs up” to the last good
baseline that does not include the offending changes
 This is an easy way to configure a stream without including the offending changes,
but it does not solve the problem of “re-parenting” development streams
 UCM has no way to “reparent” a development stream to change its default deliver
target to some other stream – this would be a problem
 Any subsequent changes would have to be performed by alternate target deliveries
to the “new” integration stream (and might be potentially confusing to users)

130
 IBM Software Group

Using cset.pl to Effectively “undeliver”

 Earlier, we saw an example of how “cset.pl
–move” could be used to effectively move
changes across streams
 In this case, we can use “cset.pl –undo” to
effectively remove changes from a stream
 The script actually subtracts the changes
by adding an “anti-activity” to the stream
which effectively removes the change set
of the offending activity

X
 The original activity does not really Activity

disappear from the stream, rather it’s

changes are cancelled out by the presence Anti-Activity
of its alter-ego

The presence of both the original activity and its anti-activity in the same
stream have a canceling effect on one another. If used on a project’s
integration stream to “undo” a deliver activity, this script can be one
solution for (effectively) performing an “undeliver” operation.

131
 IBM Software Group

Avoidance: The Best Undeliver Strategy

 Aside from all of the previous advice, perhaps the best solution for
“undeliver” is to prevent the “bad” changes from being delivered in the
first place
 Using the rebase before deliver policy will decrease the likelihood of
merging upon delivery (although it cannot guarantee all trivial merges)
 Take advantage of the fact that UCM’s deliver operation is a multi-step
operation
Take care to test delivered changes in your integration view prior to completing
any delivery
If things don’t look right, you can always undo the delivery if you haven’t
already completed it
You can also make changes right on the integration stream to fix any problems
with deliveries before completing

Mitigation is a solution unto itself – so employ best practices to try

to avoid “undeliver” scenarios altogether

132
 IBM Software Group

Will UCM Ever Provide “Un-Deliver”?

 UCM could provide this functionality for trivial cases Integration
 However, many cases would not likely be trivial
 Other deliveries may have arrived in the stream (which may have
dependencies on the offending activity – requiring subtractive merge)
 New baselines may have already been created in the stream
• And other streams may have potentially rebased to those baselines
Deliver 1

Deliver 2

Deliver 3 Deliver 3

Deliver 4

It is still possible that UCM could someday provide some limited

undeliver operation in the future (for trivial cases).
Longer term, next generation UCM will not be subject to such limitations.

133
 IBM Software Group

Break Time…

This
appears to
be 2-ply

Let’s take a break now (because this is a “2-ply” session)

134
IBM Software Group

SQUID

Other
Change
Topics
Flow
Intro X
Composite
Break
Baselines

re h er e
You a

135
 IBM Software Group

UCM Mysteries – Case #2

Comp
o
Base site
line
s
A
A
A
A
A
A

136
 IBM Software Group

Composite Baselines
 Introduced in v2002 as a means of aggregating multiple disparate baselines into a
single entity
 Fulfilled the requirement of a single object to define a common development
environment
 Simplified baseline management because only one baseline needs to be specified
for the entire set of baselines
 Provided a mechanism to tie together multiple related/unrelated development
components into a hierarchy – either as a flat structure or as a complex geometry
 Helped clear up the clutter of multiple baselines in the stream’s foundation by
providing implicit selections of dependent baselines
 Supported the use of baseline overrides to supersede the changes brought by
another implicit foundation baseline or to resolve conflicts of a common
component in multiple composite hierarchies

Although composite baselines are a great mechanism for streamlining changes, they are
based on a set of rules which must be understood clearly and completely to do successful
parallel development. Thus, it is imperative that a good deal of thought must be provided
in deciding development strategies including component hierarchies, project policies,
stream hierarchies. rootless/rooted components, release machinery etc.

137
 IBM Software Group

Composite Baselines (continued)

 Creation of composite dependency is possible through both the GUI and the CLI
 Creation requires a new baseline on the top-level component of the hierarchy to denote the
dependency
 Baseline dependency relationships are propagated ONLY through mkstream or rebase
operations
 In deliver, changes to individual components are merged into the target stream; nothing about
baseline relationships is communicated
 Successor baselines to a composite inherit the members of the predecessor (unless
components are explicitly added/dropped)
 Reasons to create a successor composite include:
Changes made in the top-level component (only when using rooted composites)
Changes made to the dependency graph
Changes made in a member component

It is important to understand that the composite dependency relationship is between

baselines and not components. This dependency may last for the life of a given
project but it might be different for other projects and the dependency graph itself may
change as more components are added/dropped.

138
 IBM Software Group

Rooted vs. Rootless Composites

 A composite baseline fulfills multiple roles – identifying a set of versions,
aggregating members, changes in member components
 It is an expensive operation to determine which reason caused the creation of a
new composite baseline
 A rootless component does not have an associated root directory (thus no
elements) and need not be concerned with the role of identifying its own versions
 A new rootless composite baseline indicates either dependency relationship
changes or new baselined versions of member components
 A rooted composite dictates a strict dependency relationship between
components - an attribute not achievable using rootless composites
 UCM is less restrictive in terms of movement of foundation baselines
(forward/backward/sideways) for rootless composites than it is for rooted
composites

Use rootless composites to combine components that do not require strict

dependency relationships. These help projects adopt composite baselines quickly and
successfully. Use rooted composites to ensure a close synchronization of related
components. This prevents most baseline conflicts but is likely to be feasible for
projects with a small number of shared components.

139
 IBM Software Group

Composite Mystery #1 – All I did was choose another

baseline. Then why can’t I rebase ?
 Can’t rebase sideways to another composite after rebasing
to a baseline of a read-only component
Exhibit W: Because the stream has put a new baseline on the
composite component, it is not allowed to rebase sideways (or even
backwards)

140
 IBM Software Group

Exhibit W: Unable to rebase sideways after rebasing to a

baseline of a read only component
Project A Project B
Project R

A.BL1 B.BL1
R.BL1 Project X
A.BL1
A.BL2 B.BL2
B.BL1 A.BL3 B.BL3
R.BL2 A.BL4 B.BL4
A.BL2
B.BL2

R.BL3 R.BLX
A.BL3 A.BL2
B.BL3 B.BL4

Project X cannot rebase to R.BL3 (or even R.BL1) as it has created a new baseline on the composite
component to capture an overriding baseline of its read-only component. The presence of baseline
R.BLX prevents the project to rebase to other composite baselines as it makes the stream look like its
made changes. Also, it may not be feasible to remove R.BLX if a child dev stream is using it and has
already made changes to either component R or component A.
141
 IBM Software Group

Mystery #2 – I can’t rebase nor deliver anything

 Can’t rebase in any direction nor deliver activities/baselines
Exhibit X: Because stream is based on a baseline not yet recommended
and project policy requires “rebase before deliver”.

142
 IBM Software Group

Exhibit X: Project Policy Requires Rebase But Stream

Ahead Of Current Recommended
 A Classic case of when developers are over-enthusiastic in selecting “The Latest
and The Greatest” baselines of the parent stream (as opposed to those
recommended).
 A UCM Project is created with “Rebase Before Deliver” policy enabled.
 An Integration stream creates a baseline (BASE1) on a rootless composite and
recommends it.
 A Stab stream based on the recommended baseline makes more changes,
baselines them (STAB) and delivers it to the Integration stream.
 The Integration stream recommends the baseline on the Stab stream, makes
more changes, baselines them (BASE2) but does NOT recommends this
baseline.
 A Development stream uses BASE2 and makes some changes to a dependent
component.
 The Development stream cannot deliver as the policy requires it to rebase to the
last recommended before deliver.
 The Development stream cannot revert to an earlier baseline as it has made
changes to a dependent component.

143
 IBM Software Group

Composite Mystery #3 – Who Owns This Composite ? Me ?

You ? Who ?
 Political issues on who owns a composite hierarchy in a
producer-consumer relationship of baselines
Exhibit Y: Other teams are making baselines on components they don’t
own.

144
 IBM Software Group
Exhibit Y: Why is the other team making baselines on OUR
components ?
 This problem relates to an age-old quest of human kind on display of authority.
 Team A creates a composite hierarchy on component CompA owned by the team.
 The composite hierarchy on CompA contains:
 components produced by the team (Aplus, Aminus)
 read-only components produced by other teams (Oplus, Ominus).
 Team B consumes baselines of CompA but prefers a different version of Oplus and
so overrides a baseline to suit its needs.
 Team B plugs this composite hierarchy (with overrides) into its own bigger
composite hierarchy on component CompB.
 The composite hierarchy on CompB contains:
 components produced by the team (Bplus, Bminus)
 read-only components produced by other teams (Aplus, Aminus, Oplus, Ominus)
 Team B makes baselines on CompB which has a side effect of making baselines on
CompA to capture the override on Oplus.
 Team A is infuriated to see new baselines on CompA created by Team B.
The bottom line here is that in this kind of producer-consumer relationship no one “owns” the composite
component. If you are particular about who owns what, then share your stuff outside of a composite
hierarchy. Alternatively, do it using a rootless component as it imposes fewer restrictions.

145
 IBM Software Group

Mystery #4 – But it was in the foundation just a minute ago ?

 Unable to create a development stream using the parent’s

previous foundation set
Exhibit Z: Because the parent stream has no history of its previous
foundation baselines.

146
 IBM Software Group
Exhibit Z: Why can I not create a stream using a baseline
that was in my parent’s foundation previously ?
BootStrap
Project

BS.BL1 Project X

DevStream X.1
BS.BL1

X.BL1
BS.BL2
DevStream X.2
BS.BL1

Although there exists a baseline (X.BL1) on the Project X Integration stream that is a successor of the
baseline BS.BL1, this stream cannot be created as the Integration stream has no recollection of which
baselines it had in its foundation set.

147
 IBM Software Group

UCM Mysteries – Case #3

CQ-E
nabl
ed U
(a.k CM
.a.
“SQU
ID”)

148
 IBM Software Group

SUM ClearQUest Integration Doodad

149
 IBM Software Group

These are the only SQUID guts you’ll see today!

Remember that this is primarily a tips/tricks presentation. It was not
intended to be an internals session. An advanced UCM class will be
available for all those interested in learning about SQUID internals.

150
 IBM Software Group

(One Reason) Why We Won’t Cover SQUID Internals

 04/16/2004 10:08 PM
 ID: 38836

 Squid May Be Dangerous Work Hazard

 3 crew members of a South Korean freighter (that washed ashore) may have died
after breathing in toxic gas coming from rotting squid organs. The captain of the
vessel is being questioned by the Coast Guard.

 The crew members were found dead in two storage rooms and the skipper was
found unconscious. Officers found rotted internal squid organs in these storage
rooms.

 Investigators think the members died from lack of oxygen or carbon monoxide
inhalation that was emitted from the decomposing squid. Carbon monoxide and
hydrogen sulfide were both discovered in the cabin.

151
 IBM Software Group

SQUID Mystery #1: A Case of Mistaken Identity

 It’s probably no mystery to anyone that
ClearCase and ClearQuest have different
means of user authentication
 Because SQUID needs to enforce certain
policies, the integration must try to map
operating system (CC) user to CQ users
 This mapping is cached per-user (as a
convenience to the user)

 This can cause problems if a given operating

system user needs to perform SQUID
operations with more than one CQ identity
E.g. Operating system user “rcapasso” used the
SQUID integration as CQ user “ralph”, but now
wants to use the integration as CQ user “admin”

152
 IBM Software Group

Mystery Solved: Clear the CQ User Cache

 Unix and Windows use different
mechanisms for implementing
this cache
 Registry setting on Windows
 “Hidden” home directory file on
Unix
 In either case, removing the
cached CQ user value will force
a CQ login dialog upon next use

153
 IBM Software Group

Mystery #2: CQ-enabled UCM and multiple DBsets

 Currently, the UCM integration can co-exist with environment that have
defined more than one CQ DBset (master)
 However, on any given client machine, the integration will only
recognize one CQ dbset at a time
 The best a user can do is toggle this setting if working (from a single
client) with UCM projects that are associated with distinct CQ user
databases residing in more than one CQ DBset
 The SQUID integration does not currently record CQ Dbset information
in any associations it makes with CC projects and activities
But it would still have problems even if it did

154
 IBM Software Group

Obstacles to Supporting Multiple CQ DBsets

 CQ DBset names are not fixed.
Users can name them whatever they want, and later change the name. There
is no concept of a “universal selector” for CQ DBsets.
CQ automatically changes the connection (or dbset) names when replicating
a CQ database through CQ/MultiSite
 CQIntSvr currently creates a single file (on Unix) or one registry entry
(on Windows) per user, containing dbset login information for the last
dbset accessed by SQUID.

The Windows registry key (HKEY_CURRENT_USER\Software\Rational

Software\CQ\2003.06.00\Common\CQIntSvr\UCM_SquidIntegration_<username>) has
the following parameters:
DBName | DBSetName | Password | UserName
In ClearCase, the integration currently stores the CQ record ID and its entity type on the
CC activity object – but not the Dbset

155
 IBM Software Group

Working with Multiple CQ Dbsets Today

 The current implementation of the SQUID depends on the “default”

connection recognized by CQIntSvr as the dbset of the UCM project
The one that is set from the CQ db maintenance tool
 When assigning names to CQ dbsets, follow these rules:
If you have only one dbset, then name it whatever you want.
If you have multiple dbsets, the dbset that is to be associated with the
integration should, if possible, be named after the CQ version that you are
using, for example, 2003.06.00.
If you have multiple dbsets and none of them can be assigned the name of the
CQ version string, you have to set an environment variable (SQUID_DBSET)

There are planned changes to support multiple DBsets

(concurrently) in an upcoming new release

156
 IBM Software Group

SQUID Mystery #3: Can’t re-assign an activity

 A developer works on an activity in the context of one stream, but
realizes that they really meant to work on that activity in another stream
 The developer wants to “move” the activity to another stream
The information in the CQ record is important, so creating a new activity in the
other stream isn’t a good enough workaround
 Problem #1: UCM doesn’t allow such movement of activities across
streams
 Problem #2: The CQ record is already bound to an activity in the
“wrong” stream

157
 IBM Software Group

Re-assign an Activity that is Already “Bound”

 A developer “Works On” an activity in the
context of one UCM, but realizes that they
should have indicated a different stream

Integration

BL1
Dev_stream2

Dev_stream1 BL1
“Bound”
BL1 by SQUID
Activity B

User meant to work on this

activity in Dev_stream1 instead

158
 IBM Software Group

CC-Only vs. CQ-Enabled UCM

 By UCM “rule”, an activity may not be moved from one stream to another
after it has been created.
The workaround in a CC-only UCM environment would simply be to create a
new activity in the desired stream and work there
In CQ-enabled UCM, this case is not as trivial because there is an associated
CQ record (with information, history, etc…) that the user still wants to
associate with a different activity in a different stream
 As long as the activity has an empty change set, then it is possible to
“re-assign” the “activity” (e.g. the CQ record) to a new UCM activity in
the desired stream
This is accomplished by removing the original UCM activity (and its
associations to the CQ record), creating a new activity – and associating that
activity with the CQ record.

In the future, SQUID may provide a more automated

way to do this ‘re-association”

159
 IBM Software Group

Re-assign an Activity that is Already “Bound”

 Remove the UCM activity using “rmact”
 This will also remove the association to CQ
 Associate the CQ record with a new activity in
the desired stream

Integration

BL1
Dev_stream2

Dev_stream1 BL1

BL1

Activity B
New Act

Remember that an activity cannot be removed

unless its change set is empty and it is not
currently set in any view
160
 IBM Software Group

Mystery #4: Disabling the integration

 There are different techniques and procedures for disabling (and
subsequently re-enabling) the SQUID integration
Some solutions are well known and well documented
Some are only available through internal tooling
Which one you should use depends upon the desired outcome
 An earlier presentation this week discussed the mechanics of the
linkages between CC activities and CQ records
This presentation does not get into those details, or details about backup,
restore, and recovery of CQ-enabled UCM environments
It will, however, provide some tips for achieving desired results

161
 IBM Software Group

Permanently Disabling the Integration

 SQUID has always provided a way to
both enable and disable the integration
“on-the-fly”
 The checkbox on the right is the most
obvious way to enable/disable SQUID
 The chproject command is an alternate way
of doing the same thing
 Disabling the integration in this fashion is
a good way to remove all linkages of CQ
from the CC project
 This function not only disables the
integration, but removes all record/activity
associations
 This is the best solution for permanently CQ-
disabling a project

This is probably not the best way to temporarily CQ-disable a project, however,
because subsequently re-enabling a project will create all new CQ records for
the project’s activities – it will not re-link them to the original associations.

162
 IBM Software Group

Temporarily Disabling the Integration

 If you only want to temporarily disable the integration (and subsequently re-
enable it – preserving past record/activity associations)…
 Then do NOT use the method shown earlier (chproject –ncrmenable)
 Use the undocumented ucmutil command instead
 This technique will allow you to temporarily disable the integration (and continue to use
CC-only UCM), but re-establish old links upon re-enabling the integration
 Scenario steps
 Disable the integration using the undocumented ucmutil command:
• %CC_HOME\etc\utils\ucm_util cleanup_crm <project_selector>
 This removes all of the associations on the CC-side only (e.g. PVARs), but leaves the
CC information intact within the CQ records
 CC-only UCM can be used successfully without errors (with some exceptions – e.g.
trying to modify the headline or view UCM tab information from within CQ won’t work)
 Re-enable the integration using the documented checkvob –ucm command to re-
establish the links between CQ and CC

163
 IBM Software Group

Using chproject vs. ucmutil to Disable SQUID

PVOB
CQDB

MyProject

Activity A

Activity B

Ucmutil
Chproject cleanup_crm
–ncrmenable only
removes
removes
associations
CC associations
on BOTH(but
sides,
leaves
making
CQ
it difficult
information
to re-establish
intact)links
164
 IBM Software Group

Mystery #5: Deliver Transition Policy Not Granular

 In ClearCase v4.x, all UCM policies (for deliver and for
SQUID) were only granular at the project level
This was the appropriate level of granularity for v4.x because it was
not possible to create stream hierarchies in v4.x
 In ClearCase v2002, UCM introduced the notion of stream
hierarchies, alternate-target delivery, etc…
As a result, all of the deliver/rebase policies were changed such that
they could be defined at either the project or stream granularity
Unfortunately, the SQUID policies were not changed to be more
granular than a UCM project
 This could lead to problems if project managers want fine-
grained control over automatic state transitions

165
 IBM Software Group

State Types and Default Actions There are four state

types included in the
AMStateTypes package
Postpone

Assign Open
Postpone Waiting Ready Active
Postpone
Duplicate
Duplicate, Close
Submitted Assigned Opened
Postponed Close Resolve

Reject, Re-Open

Duplicate, Validate
Complete
UCM-enablement also
All user-defined states must Resolved requires that a minimal set of
be mapped to one of these default actions exist between
Closed
state types in order to UCM- states mapped to these types
Duplicate
enable the record type.

166
 IBM Software Group

SQUID Policies and Stream Hierarchy

Integration Currently, SQUID policies can only be defined at the project.

BL1
It would be preferable to define SQUID policies on streams.

Core_Team
BL1
Jim_Core_Dev Jill_Core_dev
CORE_BL1
BL1 BL1

deliverA
BL2 Activity A Activity B

“WorkOn”
deliverB
Activity C
Activity C

CORE_BL2

deliver C
Waiting Activity C
No transition
Integ Act
(on Activity C)
Ready Active Complete
occurs here
167
 IBM Software Group

SQUID Policies and Stream Hierarchy

 Enabling SQUID policies at the stream granularity may only
be one part of a complete solution
 One can imagine introducing one or more additional state
types as well
 Another key part of a more complete and flexible solution
would be for the integration to understand and track the
“contributors” relationship within ClearQuest

Some clever hook and/or trigger writing can get you part way there
today, however this is something that would best be solved
internally within the products and the integration.

The UCM team is considering “out of the box” solutions to this problem for future
releases.

168
 IBM Software Group

Mystery #6: Want to track contributors within CQ

 For some stakeholders, tracking changes can be just as important as
migrating changes
 Because UCM deliver operations always create new activities, tracking
changes through deliver operations often involves understanding a
change’s contributors
Tracking deliveries across projects
Tracking changes through more complex stream hierarchies within projects
 This relationship is visible/navigable from CC in many places
The compare baselines (diffbl) operation always tracks through contributors
Users can also use “show contributors” (lsact –contrib) for any activity
 It would be nice if this relationship was navigable from within CQ

Changes were added in v2003 to make this relationship visible

from ClearQuest, but it is not navigable (using CQ record links).

169
 IBM Software Group

Display Contributors from CQ Record

170
 IBM Software Group

Customization – Use CQ Parent/Child Relationships

 ClearQuest already provides record-linking mechanisms (and
GUI controls) out of the box
 It is possible to build these into a CQ-enabled record type to
represent the UCM activity “contributors” relationship
 The establishment of the contributor relationship could be
further automated in CQ by a deliver hook or trigger

Note that the UCMUtilityActivity record type (the entity type unto
which all deliver and rebase activities are mapped) cannot be edited
by default in the CQ Designer (because it is introduced by way of the
UCM package). You must use the undocumented CQ “packageutil”
command in order to make this record type modifiable.

171
 IBM Software Group

Custom Contributors Solution

172
 IBM Software Group

Mystery #7: Using CQ-enabled UCM over a WAN

 The relative performance of native CC clients (and some CQ
clients) over a WAN sucks!
 This is a well-known and undisputed fact…
 Web clients are absolutely no help whatsoever
 Neither CCweb nor CQweb (ASP or java) were engineered to
support SQUID use cases
 Citrix/WTS can be a viable workaround for individual remote
users, but these probably can’t support large teams
 MultiSite could still be the best solution for geographically
distributed “teams”
 Both CC/MS and CQ/MS are required in order to make this work
 The combined CC and CQ MultiSite solution can be cost prohibitive
for customers to both buy and support
 CCRC may potentially be another solution to the SQUID
WAN issue (but not necessarily in v2003 SR4)
CCRC will support some (but not all) SQUID use cases

In v2003 SR4, CCRC is not a sliver bullet for all SQUID customers with remote
access needs. MultiSite may still be the better solution for many customers.
173
 IBM Software Group

SQUID Client Support: CQ-Initiated Use Cases

Native CQ Native CQ CQ Eclipse CQ CQ Web CQ Web .NET

Eclipse

Windows Unix Windows Unix (ASP) (Java)

CQ Display UCM Properties yes yes yes yes yes yes yes
CQ Display UCM Change Set yes yes no no yes no yes
CC ops available from cset display yes yes* no no no no yes
CQ ToDo list queries yes yes yes yes yes yes yes
WorkOn action from CQ yes yes no yes no no yes
Check assignment before WorkOn yes yes no yes no no yes
“Show Contributors” action from CQ yes yes no no no no yes
Change “mirrored” field yes yes yes no yes yes yes

174
 IBM Software Group

SQUID Client Support: CC-Initiated Use Cases

Native CC Native CC CC Eclipse CC Eclipse CC Web CCRC .NET

Windows Unix Windows Unix

CC checkout/in dropdown list yes yes yes yes yes yes yes
CC checkout/in “Browse” button yes no yes no no no yes
CC checkout/in “New” button yes yes* yes yes no no yes
Display CQ form as property sheet yes yes yes yes no no yes
CQ actions from property sheet (CQ form) yes yes yes yes no no yes
Check before CC delivery hook yes yes yes yes no yes yes
Do CQ action after delivery hook yes yes yes yes no yes yes
Perform transition after delivery yes yes yes yes* no yes* yes
Do CQ action before chact (finish) yes yes yes yes no yes yes
Do CQ action after chact (finish) yes yes yes yes no yes yes
Perform transition after chact (finish) yes yes yes yes* no yes* yes
UCM project creation yes yes no no no no yes*
Changing CQ policies from CC yes yes no no no no yes*

175
 IBM Software Group

Mystery #8: The SQUID “WorkOn” Action Distilled

 There are actually two different flavors of this action
Explicit (CQ-initiated) WorkOn from CQ pulldown Action list
Implicit (CC-initiated) WorkOn from CC checkout when a CQ record is being
associated with a CC change for the first time
 Both flavors perform the same actions
Creates a new UCM activity in the specified project/stream and “binds” the
activity to the CQ record
Fills in the UCM project/stream/view fields in the CQ record
Transitions the CQ record from a “ready” state-type to an “active” state-type by
taking the default action defined by the record type’s state machine
Optionally runs the CQ policy hook (if the UCM policy is set)
• By default this hook does a validation of the user’s identity
• However, this hook can be further modified by users to do other sorts of
validations before allowing the association to occur

176
 IBM Software Group

One Behavioral Difference

 There is one behavioral difference between the explicit (CQ-initiated) and
implicit (CC-initiated) WorkOn action
 The implicit case will pop up the CQ form upon encountering required fields upon
transition from ready->active
 The explicit case will fail gracefully and inform the user to make the state transition
manually

177
 IBM Software Group

More CC Context Available

 Note that the past several ClearCase releases and service releases have
made more CC context available from within the SQUID hook environment
(which could be handy for further customization)
 More ClearCase information is actually passed to the hook itself
 Stream where a change request is being worked on
 Stream/View where a change request is being delivered to
 Project/Stream Information where a change request is being modified
 More API support (both CAL and CtCmd) is also available to retrieve
information from CC from within VB and Perl hook scripts
 WorkOn Hook Validation Examples:
 Validate that the user working on the activity is the assigned CQ user
 Validate that the activity is not already in a completed state
 Validate that user is not working directly on an integration stream

The first two examples are validations that the default hook code
automatically performs when the policy is enabled.

178
IBM Software Group

SQUID

Other
Change
Topics
Flow
Intro X
Composite
Break
Baselines

re h er e
You a

179
 IBM Software Group

UCM Mysteries – Case #4

K
Kitc I
T
hen
Sink

180
 IBM Software Group

Misc. Mystery #1: Long Pathnames on Windows

 Windows enforces a MAXPATH value of 260 characters

 This can be a problem in and of itself even when ClearCase is not
involved
Deeply nested directory depth can be a problem in Windows – and there
isn’t much you can do about it except to avoid it.
 ClearCase can complicate this problem due to the way in which it
creates version-extended pathnames
E.g. \vob\subdir\element.suf@@\branchname\nestedbranchname\versionid
Even if a ClearCase user doesn’t reference versions directly in this manner,
many ClearCase operations will (e.g. findmerge, deliver, rebase, etc…)
This will cause ClearCase operations to fail on Windows if pathnames are
over 260 characters in length

181
 IBM Software Group

Solutions: Long Pathnames on Windows

 If using v2002 or earlier…

In a mixed Windows/Unix shop, you can perform the offending operation on
Unix (if possible) to avoid the problem altogether
Manually shorten directory and/or branch names
• Be careful when doing this in a UCM environment due to the way that
UCM streams reference branches
If possible, adopt a technique that does not encourage “cascading”
branches/streams atop one another
 If using v2003
V2003 GA has “fixed” this problem in the ClearCase core, therefore if an
operation fails from the Windows GUI, it can be worked around by running
the same operation from the CLI

V2003 SR3 actually fixes this problem from the

Windows GUIs as well as the CLI.

182
 IBM Software Group

REL1 Integration
“Cascading” Follow-on Projects

BETA REL2 Integration

The version-extended pathname for a
version in a developer’s stream in the
REL 1 REL2 BL1 RELn project might look like this:
foo.java@@\main\REL1_Integration\REL2
REL2 BL2 _Integration\REL3_Integration\...RELn_Int
egration\Ralph_RELn_Dev\3

BETA …
REL3 Integration RELn Integration

REL2 REL3 BL1 RELn BL1

183
 IBM Software Group

Creating “Follow-On” Projects is Easy, But…

There may be better ways to
put this feature to use

184
 IBM Software Group

Mainline Alternative: Using a “Mainline” Project

MN_1 The version-extended pathname for a
REL1 Integration version in a developer’s stream in the
MN_1 RELn project now looks like this:
REL1 BL1
foo.java@@\Mainline\RELn_Integration\
BETA
Ralph_RELn_Dev\3
REL1
MN_2 (this is some 47+ characters less)
REL2 Integration
MN_3
MN_3
REL2 BL1

All projects have

MN_4 BETA
REL3 Integration foundations from BLs
MN_5 in Mainline project
MN_5 REL2
REL3 BL1

185
 IBM Software Group

And Now a Word From Our Sponsor…

 The UCM graphical user

interfaces are brought to you
by… Camel brand cigarettes

 Specifically,

 Camel NON-FILTER!

186
 IBM Software Group

Misc. Mystery #2: GUI Usability and Filtering

 Currently, UCM GUIs don’t offer enough filtering options
 This can lead to usability problems in larger environments

187
 IBM Software Group

GUI Filtering Workarounds – Not Ideal

 There is some filtering available today

 Project Explorer allows filtering by PVOB
 In some baseline selection GUIs, it is possible to filter by stream
 The vtree and component tree browsers also offer some filtering parameters
 These are helpful, but not nearly sufficient

 Some customers have found it useful to employ the ClearCase lock/obsolete

command in order to filter uninteresting objects from GUI displays
 Many GUIs will not display objects that are locked as obsolete
 This can reduce clutter, but can also introduce undesired side-effects
 Ideally, the product would offer more filtering parameters in all of its GUIs
such that customers can tailor their environment to their needs

188
 IBM Software Group

Future Enhancements

 Better filtering…

 Filtering to be available in more UCM object browsers

 Include support for “shortcuts” in UCM Project
Explorer

The UCM development team is working on some of

these types of GUI enhancements for the future

189
 IBM Software Group

Misc. Mystery #3: Abstract Access Controls

 UCM is an abstraction built atop ClearCase
 Irony: UCM doesn’t support any abstract (e.g.
role-based) access controls
 UCM also doesn’t do a great job at enforcing
any default behaviors at the group level
 Even though all UCM objects have explicit user
and group ownership
 These factors make it difficult to create
access controls at the right level of
granularity (without having to resort to
trigger-writing and/or wrappers)
 E.g. Many customers have the notion of an
integrator role for creating and
recommending baselines in an integration
stream
Next generation UCM should solve this
 Today, customers must customize in order to problem more abstractly, however there
enforce the controls associated with the role isn’t much hope of getting more abstract
access control mechanisms in
ClearCase/UCM as we know them today.

190
 IBM Software Group

Misc. Mystery #4: Lack of canned reporting

 Reporting is another one of the true
injustices that exists within UCM today
 UCM offers all of this wonderful abstraction,
but not enough built-in support to harness it,
organize it, and report on it
 There are many different ways to get
reports from CC and CQ, but very few that
can combine/collate the information
UCM commands (e.g. diffbl)
CC reporting wizard, cleartool find
CQ queries, charts, and reports (Crystal)
Project Console
SoDA
 Each has its advantages and disadvantages

191
 IBM Software Group

Reporting Workarounds
 Sometimes the user has to do a lot of the
heavy lifting when it comes to reporting
due to lack of out-of-the-box support
 Some of the bigger challenges involve
reporting across product domains
E.g. CQ only contains reference to a UCM
activity but stores nothing about its change
set versions in CQ itself
 CoP is working on harvesting solutions
that have already been implemented in
the field

This is NOT an area of focus for any future product releases, so

homegrown solutions will continue to be the norm.

192
 IBM Software Group

Session Summary
 Now that you have completed this session, you should be able to:
Understand the relationships between UCM components, streams, and
baselines, and the impact these relationships have on UCM change flow
Identify problematic UCM change flow scenarios and how to work through them
Understand how to best configure and utilize composite baselines
Uncover and solve some common mysteries surrounding the CC/CQ UCM
(SQUID) integration

193
 IBM Software Group

Congratulations!

UCM
Detective

You’ve survived this double-length session…

194
 IBM Software Group

Have an Unsolved UCM Mystery on Your Hands?

 Round up the “usual suspects”

Kent Seith – UCM Product Manager
Tom Milligan - Tech Marketing Dweeb (CC)
Jim Tykal – Tech Marketing Dweeb (CQ)

 Call the “CoPs”

Dave Bellagio – Community of Practice lead
Bryan Miller – Community of Practice lead

195
 IBM Software Group

1 2 3 4 5
7’ 7’

6’ 6’

5’ 5’

4’ 4’

3’ 3’

2’ 2’

196
 ® ®

IBM Software Group

Solving UCM Mysteries

The End
Bryan Miller bryan.miller@us.ibm.com
Ralph Capasso ralph.capasso@us.ibm.com
Maneesh Mehra mmehra@us.ibm.com

197
© 2005 IBM Corporation