Solving UCM Mysteries
197
® © 2005 IBM Corporation ® IBM Software Group 1 Solving UCM Mysteries How to deploy Rational UCM and live to tell about it Bryan Miller [email protected] Ralph Capasso [email protected] Maneesh Mehra [email protected]
Transcript of Solving UCM Mysteries
®
© 2005 IBM Corporation
®
IBM Software Group
1
Solving UCM Mysteries
How to deploy Rational UCM and live to tell about it
Bryan Miller [email protected]
Ralph Capasso [email protected]
Maneesh Mehra [email protected]
IBM Software Group
2
What were they thinking?
At the end of a long day… At the end of an already long week… Just when you were beginning to see a
light at the end of the tunnel…
13
A double-session on Thursday afternoon?
You’ve got to be joking…
IBM Software Group
3
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
IBM Software Group
4
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 internalsUCM 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
IBM Software Group
5
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
IBM Software Group
6
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
IBM Software Group
7
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…
IBM Software Group
8
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
IBM Software Group
9
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)
IBM Software Group
10
Tools of the Trade
Police Line identifies potential danger areas
Ambulance is rescue vehicle for UCM casualties
Magnifying glass uncovers UCM clues and hints
Decoder ring translates confusing UCM messages
The “law” explains UCM’s rules and behaviors
Handcuffs describe UCM’s policy enforcement
Pipe identifies areas for future product improvement
Microscope reveals UCM internal details
IBM Software Group
11
Change Flow
(100 min)
CompositeBaselines(15 min)
SQUID(30 min)
Other Topics
(15 min)Intro(10 min)
X
You are here
Break(10 min)
IBM Software Group
12
UCM Mysteries – Case #1
Components, Baselines, and Change Flow (a.k.a. deliver, rebase)
IBM Software Group
13
Policy
Analyzing Deliver and Rebase Issues
Sometimes UCM deliver and rebase operations do not succeed by design A policy setting may be prohibiting the
operation from succeeding
A particular change flow may not be allowed due to UCM’s own “rules” for deliver and rebase
• Some rules exist to prevent complete chaos and to reduce the potential for “foot shooting”
• Other rules exist to promote SCM best practices
Other scenarios may not be allowed due to UCM’s implementation These are less fortunate, but should still
be viewed as “expected behavior” nonetheless
Proj B Integration
BETA
REL 1
Dev_streamA
BL1
ProjA Integration
BL1
BL2
BL3
Activity A
Deliver…
Activity B
IBM Software Group
14
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
IBM Software Group
15
Component Refresher Generally speaking, a component
it a set of related elements developed, integrated, and released together
A UCM Component is a set of elements included in a specific VOB directory tree Root of component is called
“Component Root Directory Element”
Affectionately known internally as a CRDE or “cruddy”
Benefits
Reduces complexity
Promotes sharing and reuse
str.h
inc
imp.h
libalibb
str.c txt.c
flt.c
CompA
IBM Software Group
16
Baseline Refresher
Generally, a baseline is a named, stable configuration that represents the integrated work of team members
A UCM Baseline…Identifies one version of each element in a single component
Is immutable
Is created within the context of a 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)
imp.h
1
2
33
str.c
11
txt.c
11
2
str.h
1
22
IBM Software Group
17
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
B
A
C
IBM Software Group
18
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 straightforwardIn most cases, when a deliver operation fails because of a policy
setting, the message will usually point you in the right direction
IBM Software Group
19
UCM Deliver Policies
Deliver policies tab is available for both project and stream
May be enabled, disabled, or set per-stream
IBM Software Group
20
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
IBM Software Group
21
Take Care When Setting/Observing Policies
Note that some policies can override others regardless of their settingOne 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
IBM Software Group
22
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
IBM Software Group
23
REL2 Integration
REL2_BL1
Ralph_REL2_Dev
REL2 BL1
Inter-Project Delivery Example
Ralph_REL1_Dev
REL1 BL1
REL1 Integration
REL1_BL1
REL1_FINAL
Feature A
Feature B
Feature B did not make the cutoff for
REL1Developer delivers changes directly to their dev stream for
REL2
IBM Software Group
24
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
IBM Software Group
25
AA
BB
Delivering Foundation Changes – An Example
XX
A source stream might not be based on a baseline from the target streamThis couldn’t happen with
UCM in CC v4.x Activities not created by the
developer might potentially be deliveredPerhaps accidentally
This can be prevented with a policy on the target stream
IBM Software Group
26
Intra-Project Delivery: Same Foundation
Alternate target deliver operations can involve changes made in the source stream only
Integration
Dev_stream1
BL1
Dev_stream2
BL1
BL1
Activity B
IBM Software Group
27
Act 1
Act 2
Intra-Project Delivery: Different Foundation
Integration
Dev_stream1
BL1
BL1
My Bugfix
BL2
Dev_stream2
BL2
Delivering “My Bugfix” from Dev_stream2 to Dev_stream1 will also deliver the foundation
baseline (BL2)
IBM Software Group
28
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
IBM Software Group
29
Tweak Deliver “Foundation” Policy Settings, OR…
Integration
Dev_stream1
BL1
BL1
My Bugfix
BL2
Dev_stream2
BL2
And then deliver the activity when the foundations match
BL2
Alternatively, rebase Dev_stream1 first…
This alternative approach accomplishes the same thing without opening up deliver policies
IBM Software Group
30
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
IBM Software Group
31
DevC2
BL2.1
Consider These Alternate Target Deliver Scenarios
DevA
BL1
Project Integration
BL1
BL2
BL1.1DevB2
BL1.1
DevB
BL1
DevC
BL2
BL2.1
Many alternate target deliver scenarios may involve merging more changes than you might think
IBM Software Group
32
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
IBM Software Group
33
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
IBM Software Group
34
REL2 ProjectREL1 Project
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
XZ
Y
M
N
IBM Software Group
35
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.
IBM Software Group
36
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”
IBM Software Group
37
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 activitiesCaused 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
H
G
F
I
IBM Software Group
38
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
IBM Software Group
39
UCM Deliver Mechanics
UCM always presents the abstraction that its deliver operation works at the activity level of granularity In this example, a user performs three distinct deliver
operations – one activity at a time Internally, UCM creates baselines on the source
stream for each deliver operation The operation actually delivers the baseline
containing the activity, rather than actually delivering the activity itself
The baselines created by the deliver operation are unlabeled baselines
Dev_stream1
trans1
BL1
Dev_stream1
BL1
Integration
Activity A
Activity B
Activity C
Deliver
Deliver
Deliver
Although this may seem like a subtle distinction, understanding the internal mechanics of UCM’s deliver operation becomes important when trying to understand
some of UCM’s deliver rules and behaviors.
IBM Software Group
40
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.
IBM Software Group
41
Source Stream is Integration StreamProj B Integration
BETA
REL 1
Dev_streamA
BL1
ProjA Integration
BL1
BL2
BL3
Activity A
Deliver…
Activity B
IBM Software Group
42
Delivering Baselines
This menu is inactive in
this context
IBM Software Group
43
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
IBM Software Group
44
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
IBM Software Group
45
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”)
IBM Software Group
46
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
IBM Software Group
47
Change Set Dependencies
Change set dependencies are probably the 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 branchBase CC would also make you include the
changes in version 1 when merging the changes from version 2 to the integration branch
IntegrationIntegration
77
88Joe DevJoe Dev
Activity A
Activity B
Integration
trans1BL3
Joe DevBL3
1
2
11
22
UCM’s deliver operation does not allow Base-ClearCase subtractive merge
operations under the covers (e.g. to break these kinds of change set dependencies by
subtracting out the delta from Activity A).
IBM Software Group
48
Fix 102Fix 102 Fix 103Fix 101
Feature X Feature YFeature Y
Fix 3Fix 3
Exhibit F: “Normal” (Self-Inflicted) Dependency
File1 File2 File3 File4 File5
IBM Software Group
49
Fix 103Fix 102Fix 101
UnfinishedUnfinished
RebaseRebase
Fix 3Fix 3
Exhibit G: “Forced” Dependency (Upon Rebase)
File1 File2 File3 File4 File5
IBM Software Group
50
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 associationA 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 rebaseBest case scenario will update config spec without requiring merges
Mitigating rebase merging may also mitigate rebase dependencies
IBM Software Group
51
Perils of Long-Lived StreamsIntegrationIntegration
77
deliverA88
Joe DevJoe Dev
Integration
trans1BL3
Joe DevBL3
Activity A
111
BL4
RebseBL4
22
33RebseBL5
BL5
1515deliverX
Deliver
1616deliverYDeliver
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
element will require (often trivial) merges – even if no further changes are ever made to that element
in the context of the development stream.
IBM Software Group
52
trans1BL4
Joe Dev2
Joe Dev2Joe Dev2
“Retiring” Dev StreamsIntegrationIntegration
77
88Joe DevJoe Dev
Activity A
RebseBL4
Integration
BL3
111
1515
deliverA
deliverX BL4
221616
deliverY
33RebseBL5
BL5
Alternatively, creating a new development stream to replace an old (long-lived) one will
reduce the likelihood of having to perform unnecessary trivial merges upon rebase.
Rebase to BL5
BL5
No merges!
trans1BL3
Joe Dev
IBM Software Group
53
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.
IBM Software Group
54
Exhibit H: “Explicit Baseline” Dependency
Sometimes users and/or project managers will intentionally create baselines in a development streamThis 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
IBM Software Group
55
Developers “join” the project by creating their development streams under their
respective sub-team’s stream
Jim_Core_Dev
BL1
Jill_Core_dev
BL1
Chris_GUI_dev
BL2
Core_Team
BL1
GUI_Team
BL2
Intermediate development streams act as
“integration” streams for individual teams
Sub-Team (Feature Stream) Example
Integration
BL1
The project integration stream is the eventual collection point
for inter-team integration
BL2
IBM Software Group
56
Jim_Core_Dev
BL1
Jill_Core_dev
BL1
Chris_GUI_dev
BL2
Core_Team
BL1
GUI_Team
BL2
Sub-Team (Feature Stream) Example
Integration
BL1 …And subsequently rebase from baselines created there
BL2
GUI_BL1
CORE_BL1
Developers deliver to their sub-team “integration” stream
IBM Software Group
57
Jim_Core_Dev
BL1
Jill_Core_dev
BL1
Core_Team
BL1
Sub-Team Example Simplified
Integration
BL1
BL2
CORE_BL1
deliverB
deliverA Activity A Activity B
Activity C
deliver C
Integ Act
Deliver
CORE_BL2
A baseline is intentionally created in this intermediate
stream as a checkpoint (for dev stream rebasing purposes)
Only “deliverC” and “Integ Act” (the two activities not already included in a baseline on the Core_Team stream) are eligible for
selective delivery from this stream
In this case, a developer could still (alternate target) deliver the original Activity B directly
from the development stream to the integration stream in order to achieve the desired effect.
IBM Software Group
58
Exhibit I: “Deliver Baseline” Dependency Two sibling development streams exist within a
UCM project Developer 1 works on several activities in the
context of Dev_stream1 Developer 1 delivers only a selected activity
(Activity A) to Dev_stream2 This is an alternate-target deliver scenario
Developer 1 now tries to deliver a different selected activity (Activity B) to the project’s integration stream A default-target deliver scenario
UCM complains that Activity B has dependencies on Activity A Developer 1 must include activity A when
delivering to the integration stream (because Activity A is now in a baseline)
Even though activity A and activity B have NO CHANGE SET DEPENDENCY!
Dev_stream1
trans1
BL1 Dev_stream2
trans1
Dev_stream1
BL1
Integration
Dev_stream2
BL1
Activity A
Activity B
Deliver
Deliver
The existence of this (unlabeled) deliver baseline forces the inclusion of Activity A for any subsequent
deliveries out of Dev_stream1
IBM Software Group
59
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 streamThis model introduces more overhead and potentially more complexity
Drop down into base ClearCase and do some subtractive mergingDave 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
IBM Software Group
60
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
IBM Software Group
61
One-Activity-Per-Stream Example
A new development stream is created for
each new activityFeature A
BL1BL1Feature B
BL1
Bugfix 123
BL1
Bugfix 456
BL2
Feature A
Feature B
Bugfix 123
Bugfix 456
Each activity is worked in isolation, independent of all
others
Activities may be delivered in any sequence
Integration
BL1
A single integration stream is usually the collection point for
all changes within a project
BL2
IBM Software Group
62
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
IBM Software Group
63
“Deliver Baseline” Dependency Workaround An original activity is created and delivered
(alt-target) to a sibling development stream Another activity is created, but when
attempting to deliver only this activity to the project’s integration stream, it is flagged as dependent (because of the deliver baseline)
Create a new (workaround) activity in the same source stream
Move the change set versions from the original activity to the workaround activity
Remove the original activity (this is possible because its change set is now empty)
Now attempt the delivery again Deliver will not complain about dependencies
because the original activity is no longer in the source stream
Dev_stream1
trans1
BL1 Dev_stream2
trans1
Dev_stream1
BL1
Integration
Dev_stream2
BL1
Original
Another
Deliver
Deliver
Workarnd
Deliver
Success!
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)
IBM Software Group
64
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
IBM Software Group
65
Mystery #3 – Can’t Rebase or Recommend Baseline
Can’t rebase in any direction or even recommend baselinesExhibit 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
K
L
M
N
IBM Software Group
66
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 userSubject to validation by the stream
Five cases:Advance to successor
Revert to predecessor*
Move “Sideways”*
Add new component
Drop component*
* Restricted operations
IBM Software Group
67
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
Advance
BL1
BL2
BL3
IntStream
BL1
DevStream BL1
BL2
BL3
Sideways
IntStream
BL1
DevStream
Project2
P2.1
P2.2
P2.3
BL2
BL3
BL1
Revert
IntStream
BL3
DevStreamDevStream
BL3P2.2
DevStreamDevStream
BL1
IBM Software Group
68
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
IBM Software Group
69
“Rules” for RebaseAdvance – 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
IBM Software Group
70
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
The development streams are only allowed to rebase to trans2_deploy after Build_stream has delivered its work to the integration stream
Dev_stream1
trans1
Rel_1.0
trans2Build_stream
trans2
trans1 Dev_stream2
trans1
Dev_stream1
trans1
Rel_1.0
trans2Build_stream
trans2
trans1 Dev_stream2
trans1
trans2_deploy
IBM Software Group
71
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 parentEnsures 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 rebaseUCM 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
IBM Software Group
72
Dev_stream1B
DEVBL1
Siblings
Stream Ancestry - Terminology
Integration
Dev_stream1
BL1
BL1
Parent
Child
Dev_stream1A
DEVBL1
DEVBL1
Child
Grandparent
Parent
IBM Software Group
73
Dev_stream2A
DEV2BL1
Cousins
Stream Ancestry – Terminology (cont.)
Integration
BL1
Dev_stream1A
DEV1BL1
Dev_stream2
BL1
Dev_stream1
BL1
DEV1BL1 DEV2BL1
IBM Software Group
74
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
IBM Software Group
75
Project N
Mainline Project
BL6
BL7
BLN4
Project Z
BLN3
BLZ1
BL8
BL9
Exhibit J: UCM Genealogy Lesson
Deliveries from other projects
This failed rebase scenario came up recently at a customer
deployment
BLN1
BLN2
Had Project Z been founded from a baseline created in the mainline project (and not a baseline created in
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 rebase operation to be successful.
IBM Software Group
76
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
IBM Software Group
77
Sharing via Alternate Target Delivery
Integration
Dev_stream1
BL1
BL1
My Bugfix
Dev_stream2
BL1
BL1
Developer1 and Developer2 want to share changes without going through the integration
stream
Deliver the activity directly from one development stream to the
other
IBM Software Group
78
Sharing via Rebase
Integration
Dev_stream1
BL1
BL1
My Bugfix
Dev_stream2
BL1
BL1
Developer2 creates a baseline in their development stream
with the intention that Developer1 can rebase to it
DEV_BL
First attempt to rebase will fail
because the BL is not included in Dev_stream1’s
parentDeliver the changes to the integration stream (the parent for both of
these dev streams)
IBM Software Group
79
Sharing via Rebase
Integration
Dev_stream1
BL1
BL1
My Bugfix
Dev_stream2
BL1
BL1
Developer2 creates a baseline in their development stream
with the intention that Developer1 can rebase to it
DEV_BL The rebase will now succeed
Deliver the changes to the integration stream (the parent for both of
these dev streams)
IBM Software Group
80
Exhibit K: Rebase and Imported Baselines
“Import Baselines” are a handy mechanism for creating a starting point for new UCM projectsFrom 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
IBM Software Group
81
LABZ
Rel4 Integration
LABY
Rel3 Integration
REL2_IntegrationREL2_Integration
11
1313 REL2
Imported Baselines as Stream Foundations
mainmain
77
88 REL1
REL1
REL1
Rel2 Integration
1616
1717LABZ
LABY
LABX1515
LABZ
LABY
Use imported baselines as the foundation for new UCM streams. This can save unnecessary merging between Base CC and UCM when
starting new UCM projects.
IBM Software Group
82
Imported Baselines are not “Full Service” Baselines
Rebase?
Imported baselines are not created within UCM streams
They can be used effectively as foundationsfor new UCM streams, but…
IBM Software Group
83
REL2_IntegrationREL2_Integration
11
Rebase Between Two Imported Baselines
mainmain
77
88 REL1
REL1
REL1
Rel2 Integration
LABX
LABX1515
Rebase LABX
These imported baselines were created from Base-CC labels and were not created within the context of a UCM stream (like a “normal” baseline). UCM has no context (e.g. streams, timelines, activities) within
which to compare these “baselines” in order to perform an actual UCM rebase operation
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”..
IBM Software Group
84
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).
IBM Software Group
85
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 rebasedRead-only streams can always be rebased backwards
According to UCM’s “rules”, backwards rebase is only permitted on streams with no modifications
IBM Software Group
86
Backwards Rebase Illustrated
A stream containing no changes is not restricted from rebasing backwards No branch instances for that stream exist
in any elements
Reverting in this case simply replaces the foundation baseline
A stream that contains changes may not revert to a predecessor baseline This is true whether the changes in the
stream conflict with the existing baseline or not
Dev_stream2
trans1
Dev_stream2
BL1
trans1BL1
Dev_stream1Dev_stream1
Activity A
Integration
BL1
Deliver 1
Deliver 2
BL2
BL2
BL2
Rev
ert
BL
1
BL1
Rev
ert
BL
1
Backwards rebase is not a silver bullet for removing unwanted changes from a stream that
contains other work
IBM Software Group
87
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
IBM Software Group
88
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 timeThis 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 rebasedBecause 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
IBM Software Group
89
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
IBM Software Group
90
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
B2 C1 E1
Gamma2
F2
C1
A1
Alpha1
C3
Mathlib1 C5C5
IBM Software Group
91
Overrides are Modifications Mathlib makes changes in F and needs a new baseline
Also: Components Alpha and Gamma
(Because there is a new member of component C visible)
Where are the changes?
Component F
B2 C1 E1
Gamma2
F2
A1
Alpha1
C3
Mathlib1
C1
C5C5
F2
C5C5
C5C5 Gamma2
Alpha1
Mathlib1
IBM Software Group
92
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
Alpha1
Gamma2
B2 C1 E1
F2
A1 C5
C5
Mathlib1
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.
IBM Software Group
93
Mystery #4: Deciphering Deliver/Rebase Messages
Exhibit O: Deliver can’t merge some elementsExhibit P: Deliver informed me that it was
“skipping” some elementsExhibit Q: Deliver errors during posted deliveries
PO
Q
IBM Software Group
94
Exhibit O: Deliver Non-mergeable Element Types
The ProblemUCM 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 caseClearCase also has no concept of “universally reserved” checkouts
• To ensure no one else is ever modifying a given element on any branch
The UCM SolutionUCM 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
IBM Software Group
95
The Problem Illustrated
IBM Software Group
96
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
IBM Software Group
97
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".
IBM Software Group
98
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”
IBM Software Group
99
Merge Type Attribute Example (cont.)
Start the delivery
IBM Software Group
100
Merge Type Attribute Example (cont.)
Observe the version history of the two “image” elements
IBM Software Group
101
Merge Type Attribute Example (cont.)
During the delivery…
IBM Software Group
102
Merge Type Attribute Example (cont.)
Manually merge the non-trivial image
IBM Software Group
103
Merge Type Attribute Summary
Merge type attributes can be used effectively in dealing with binaries and other non-mergeable element types in deliver/rebase scenariosUse 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 versionsHowever, 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
IBM Software Group
104
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
IBM Software Group
105
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
IBM Software Group
106
Skipping Elements Illustrated
Integration
trans1
Development
Same Foundation
n+1 nDeliver
rmname
IBM Software Group
107
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.
IBM Software Group
108
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.
IBM Software Group
109
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.
IBM Software Group
110
Can’t Post Delivery in a MultiSite Environment
Integration
Dev_stream2
BL1
BL1
Activity A
Dev_stream1
BL1
BL1
Site: India Site: USA
Activity C
Activity B
Delivery of Activity B is posted, but not
completed
Delivery of Activity A is completed
normally
Posted delivery of Activity C fails
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.
IBM Software Group
111
Mystery #5: Can’t Stabilize a Baseline
Exhibit R: Use Stabilization Streams Exhibit S: Selective Baseline Creation
R
S
IBM Software Group
112
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
IBM Software Group
113
Volatility of the Integration Stream
Two O'clock and all is wellA new baseline (BL2) is created on the
integration stream
This baseline represents the “tip” of the stream
Would like to test this baseline and potentially recommend it to other streams
Three O'clock and things have changedTesting reveals that minor changes must be
made to BL2
However, by this time, many new deliveries have cluttered up the integration stream
Integration
BL1
BL2
Deliver 1
Deliver 2
Deliver 3
IBM Software Group
114
Things Look Different Than They Used To…
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 even if I did, I still may have similar stabilization issues because deliveries could continue coming in
Consider These OptionsI. Lock the stream until the baseline can be stabilized
and recommended (potential bottleneck)
II. Create a new baseline but only include the old baseline plus the stabilization work (mkbl –act) without including the new deliveries (subject to dependencies)
III. Create a “stabilization stream”
Integration
BL1
BL2
Deliver 1
Deliver 2
Deliver 3
“I don’t recall seeing all of these activities here before”
Stabilization streams don’t have as many drawbacks as the first two options
IBM Software Group
115
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
IBM Software Group
116
Deliver to the integration stream
Stabilization
BL2
Create a stabilization stream from BL2 and make changes necessary to stabilize the BL
Using Stabilization Streams – An Illustration
Integration
Dev_stream1
BL1
BL1
BL2
BL1 is recommended
BL2 is created, but not stable
Deliver 1
Deliver 2
Deliver 3
Influx of new deliveries makes it nearly impossible to try to stabilize
BL2 directly on the integration stream
Stab
BL2-STAB
Create a stable baseline
BL2-STAB may be recommended once the changes are seen by the integration stream. The development stream can then rebase.
BL2-STAB
IBM Software Group
117
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” commandCreate 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 baselinesThis 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.
IBM Software Group
118
Create a selective stable baseline (mkbl –act)
BL2-STAB=
+
BL2
Stab
Creating Selective Baselines – An Illustration
Integration
Dev_stream1
BL1
BL1
BL2
BL1 is recommended
BL2 is created, but not stable
Deliver 1
Deliver 2
Deliver 3
Influx of new deliveries makes it difficult to stabilize
BL2 on the integration stream
BL2-STAB
This technique cannot be relied upon if there are any change set dependencies between the
activities that you wish to include in the selective baseline and the activities that you wish to
exclude from the baseline.
BL2-STAB
StabCreate a stabilization activity directly on the
integration stream
IBM Software Group
119
Selective Baseline Behavior (v2002 and v2003)
The default behavior for “mkbl –act” changed between v2002 and v2003The 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 baselinesThe 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.
IBM Software Group
120
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 booksHowever this is not the primary motivation of this session…
Just remember that different groups have different isolation and integration needsIt 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”
IBM Software Group
121
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
V
U
T
IBM Software Group
122
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
IBM Software Group
123
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
IBM Software Group
124
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
IBM Software Group
125
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 thisUse 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.
IBM Software Group
126
Exhibit V: Partial Change Sets During mkbl
An individual component baseline itself may contain partial change sets from included activitiesUCM 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
IBM Software Group
127
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.
IBM Software Group
128
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
IBM Software Group
129
Integration
UCM has no formal “undeliver” command
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
IBM Software Group
130
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)
IBM Software Group
131
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
The original activity does not really disappear from the stream, rather it’s changes are cancelled out by the presence 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.
Activity
Anti-ActivityX
IBM Software Group
132
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 operationTake 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
IBM Software Group
133
Integration
Will UCM Ever Provide “Un-Deliver”?
UCM could provide this functionality for trivial cases 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 baselinesDeliver 1
Deliver 2
Deliver 4
Deliver 3Deliver 3
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.
IBM Software Group
134
Break Time…
This appears to
be 2-ply
Let’s take a break now (because this is a “2-ply” session)
IBM Software Group
135
Change Flow
CompositeBaselines
SQUID
Other Topics
Intro X
You are here
Break
IBM Software Group
136
UCM Mysteries – Case #2
Composite Baselines A
A
AA
AA
IBM Software Group
137
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.
IBM Software Group
138
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.
IBM Software Group
139
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.
IBM Software Group
140
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 componentExhibit W: Because the stream has put a new baseline on the
composite component, it is not allowed to rebase sideways (or even backwards)
W
IBM Software Group
141
Exhibit W: Unable to rebase sideways after rebasing to a baseline of a read only component
Project X
Project A
A.BL1
A.BL2
A.BL3
Project B
B.BL1
B.BL2
B.BL3
R.BLX
A.BL2
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.
Project R
R.BL1
A.BL1
B.BL1
B.BL4A.BL4R.BL2
A.BL2
B.BL2
R.BL3
A.BL3
B.BL3
IBM Software Group
142
Mystery #2 – I can’t rebase nor deliver anything
Can’t rebase in any direction nor deliver activities/baselinesExhibit X: Because stream is based on a baseline not yet recommended
and project policy requires “rebase before deliver”.
X
IBM Software Group
143
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.
IBM Software Group
144
Composite Mystery #3 – Who Owns This Composite ? Me ? You ? Who ? Political issues on who owns a composite hierarchy in a
producer-consumer relationship of baselinesExhibit Y: Other teams are making baselines on components they don’t
own.
Y
IBM Software Group
145
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.
IBM Software Group
146
Mystery #4 – But it was in the foundation just a minute ago ?
Unable to create a development stream using the parent’s previous foundation setExhibit Z: Because the parent stream has no history of its previous
foundation baselines.
Z
IBM Software Group
147
DevStream X.2
BS.BL1
Exhibit Z: Why can I not create a stream using a baseline that was in my parent’s foundation previously ?
BootStrapProject
DevStream X.1
BS.BL1
BS.BL2
Project X
X.BL1
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.
IBM Software Group
148
UCM Mysteries – Case #3
CQ-Enabled UCM (a.k.a. “SQUID”)
IBM Software Group
149
SUM ClearQUest Integration Doodad
IBM Software Group
150
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.
IBM Software Group
151
(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.
IBM Software Group
152
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”
IBM Software Group
153
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
IBM Software Group
154
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 activitiesBut it would still have problems even if it did
IBM Software Group
155
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
IBM Software Group
156
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
IBM Software Group
157
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 streamThe 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
IBM Software Group
158
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
Dev_stream1
BL1
Dev_stream2
BL1
BL1
Activity B
User meant to work on this activity in Dev_stream1 instead
“Bound” by SQUID
IBM Software Group
159
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 streamThis 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”
IBM Software Group
160
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
Dev_stream1
BL1
Dev_stream2
BL1
BL1
Activity BNew Act
Remember that an activity cannot be removed unless its change set is empty and it is not
currently set in any view
IBM Software Group
161
Mystery #4: Disabling the integration
There are different techniques and procedures for disabling (and subsequently re-enabling) the SQUID integrationSome 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 recordsThis 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
IBM Software Group
162
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.
IBM Software Group
163
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
IBM Software Group
164
CQDB
PVOB
Using chproject vs. ucmutil to Disable SQUID
MyProject
Activity A
Activity B
Ucmutil cleanup_crm only removes CC associations (but leaves CQ
information intact)
Chproject –ncrmenable removes associations on BOTH sides, making
it difficult to re-establish links
IBM Software Group
165
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 levelThis 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
IBM Software Group
166
Close
Duplicate, Close
Duplicate, Validate
Postpone
Reject, Re-Open
Duplicate
Postpone
State Types and Default Actions
Waiting Ready Active
Complete
There are four state types included in the AMStateTypes package
All user-defined states must be mapped to one of these state types in order to UCM-enable the record type.
UCM-enablement also requires that a minimal set of default actions exist between states mapped to these types
Assign Open
Resolve
Postpone
Submitted OpenedAssigned
ResolvedClosed
Duplicate
Postponed
IBM Software Group
167
Waiting
Ready
Activity C
Jim_Core_Dev
BL1
Jill_Core_dev
BL1
Core_Team
BL1
SQUID Policies and Stream HierarchyIntegration
BL1
BL2
CORE_BL1
deliverB
deliverA Activity A Activity B
CORE_BL2
Currently, SQUID policies can only be defined at the project.
It would be preferable to define SQUID policies on streams.
deliver C
Integ Act
Complete
No transition (on Activity C)
occurs here
Activity C
Active
“WorkOn” Activity C
IBM Software Group
168
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
The UCM team is considering “out of the box” solutions to this problem for future releases.
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.
IBM Software Group
169
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 contributorsTracking 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).
IBM Software Group
170
Display Contributors from CQ Record
IBM Software Group
171
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.
IBM Software Group
172
Custom Contributors Solution
IBM Software Group
173
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.
IBM Software Group
174
SQUID Client Support: CQ-Initiated Use Cases
Native CQ Native CQ CQ EclipseCQ
EclipseCQ
Web CQ Web .NET
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
IBM Software Group
175
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*
IBM Software Group
176
Mystery #8: The SQUID “WorkOn” Action Distilled
There are actually two different flavors of this actionExplicit (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 actionsCreates 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
IBM Software Group
177
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
IBM Software Group
178
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.
IBM Software Group
179
Change Flow
CompositeBaselines
SQUID
Other Topics
Intro X
You are here
Break
IBM Software Group
180
UCM Mysteries – Case #4
Kitchen Sink
KI T
IBM Software Group
181
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
involvedDeeply 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 pathnamesE.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
IBM Software Group
182
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 v2003V2003 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.
IBM Software Group
183
“Cascading” Follow-on ProjectsREL1 Integration
BETA
REL 1
REL2 Integration
REL2 BL1
REL2 BL2
REL2
REL3 Integration
BETA
REL3 BL1
RELn Integration
RELn BL1
…
…
The version-extended pathname for a version in a developer’s stream in the
RELn project might look like this:
foo.java@@\main\REL1_Integration\REL2_Integration\
REL3_Integration\...RELn_Integration\Ralph_RELn_Dev\3
IBM Software Group
184
Creating “Follow-On” Projects is Easy, But…
There may be better ways to put this feature to use
IBM Software Group
185
REL2 Integration
REL1 Integration
REL1 BL1
BETA
Alternative: Using a “Mainline” ProjectMainline
MN_1
MN_2
BETA
REL2 BL1
REL1
MN_3
REL3 IntegrationMN_4
REL2REL3 BL1
MN_5
All projects have foundations from BLs
in Mainline project
MN_1
MN_3
MN_5
The version-extended pathname for a version in a developer’s stream in the
RELn project now looks like this:
foo.java@@\Mainline\RELn_Integration\Ralph_RELn_Dev\3
(this is some 47+ characters less)
IBM Software Group
186
And Now a Word From Our Sponsor…
The UCM graphical user interfaces are brought to you by… Camel brand cigarettes
Specifically,
Camel NON-FILTER!
IBM Software Group
187
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
IBM Software Group
188
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
IBM Software Group
189
Future Enhancements
The UCM development team is working on some of these types of GUI enhancements for the future
Better filtering…
Filtering to be available in more UCM object browsers
Include support for “shortcuts” in UCM Project Explorer
IBM Software Group
190
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 Today, customers must customize in order to
enforce the controls associated with the role
Next generation UCM should solve this problem more abstractly, however there isn’t much hope of getting more abstract
access control mechanisms in ClearCase/UCM as we know them today.
IBM Software Group
191
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
IBM Software Group
192
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 domainsE.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.
IBM Software Group
193
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
IBM Software Group
194
Congratulations!
You’ve survived this double-length session…
UCM Detective
IBM Software Group
195
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
IBM Software Group
196
5’
4’
3’
2’
6’
7’
5’
4’
3’
2’
6’
7’
1 2 3 4 5
®
© 2005 IBM Corporation
®
IBM Software Group
197
Solving UCM Mysteries
The End
Bryan Miller [email protected]
Ralph Capasso [email protected]
Maneesh Mehra [email protected]
