Solving Ucm Mysteries

®

®

IBM Software Group

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]

© 2005 IBM Corporation 1

IBM Software Group

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

13

light at the end of the tunnel…

A double-session on Thursday afternoon? You’ve got to be joking…

2

IBM Software Group

Solving UCM Mysteries… It’s “Elementary”  Unsolved Mysteries  Why did UCM do THAT ?!  Is this expected behavior? A known limitation? A bug?

 Further Inspection  Learning how to identify some of UCM’s behaviors and limitations  Understanding the finer points of UCM beyond the user documentation

• •

UCM’s “rules” for change flow UCM’s internal mechanics

 Mysteries Solved  Practical advice for diagnosing and working though UCM issues and mysterious behavior 3

IBM Software Group

Rookie Sleuths Need Not Apply (Intended Audience)  If you’re not already somewhat familiar with UCM, then you’re in the wrong place! This is not an introductory presentation It is intended primarily for technical folks who already know UCM

 This presentation will not try to teach you UCM internals UCM architecture is a topic unto itself and is not discussed herein Some of UCM’s internal mechanics are uncovered in order to explain certain UCM behaviors, but that’s as far as it goes

 Rather, this session will attempt to explain the unexplained by both expanding your current knowledge of UCM and by providing some practical advice 4

IBM Software Group

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

5

IBM Software Group

Just Some of the Mysteries We’ll Try to Solve  Can’t deliver… Anything Selected activities

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

6

IBM Software Group

General UCM Mystery Classifications  We’ll utilize the following “cases” to classify the different types of UCM mysteries we’ll be trying to solve: Change Flow (deliver and rebase) Composite Baseline issues CQ-enabled UCM (SQUID) issues The “K” Files (The kitchen sink – things that don’t fall into any of the above classifications) Time permitting…

7

IBM Software Group

This Session May Seem a Little “Lost”  Many different UCM topics are discussed in this presentation (It’s “all over the map”)

 It doesn’t try to focus in on one or two particular areas  It is intentionally broad Contains some depth and internals information But it could certainly contain more

 Primary goal of this presentation is to raise awareness to many UCM issues and behaviors

8

IBM Software Group

Finding Your Way  There is a lot of material contained within this presentation  Don’t expect to learn the finer details here in short order because we are going to move quickly  The important take-aways are highlighted along the way  For future reference

 More in-depth material is available and can be used to augment the material in this presentation  An advanced UCM topics course (with hands-on labs) is under development  This will provide more time and more detail (when it becomes available)

9

IBM Software Group

Tools of the Trade Police Line identifies potential danger areas Magnifying glass uncovers UCM clues and hints Microscope reveals UCM internal details

Decoder ring translates confusing UCM messages The “law” explains UCM’s rules and behaviors Handcuffs describe UCM’s policy enforcement

Ambulance is rescue vehicle for UCM casualties Pipe identifies areas for future product improvement 10

IBM Software Group

Change Flow (100 min) Intro (10 min)

SQUID (30 min) Other Topics

X

Break (10 min)

Composite Baselines (15 min)

(15 min)

e r e h e r a u o Y 11

IBM Software Group

UCM Mysteries – Case #1

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

12

IBM Software Group

Analyzing Deliver and Rebase Issues  Sometimes UCM deliver and rebase

Proj B Integration

operations do not succeed by design  A policy setting may be prohibiting the operation from succeeding

BETA

 A particular change flow may not be allowed due to UCM’s own “rules” for deliver and rebase

• •

ProjA Integration

Policy

BL1 Activity B

Some rules exist to prevent complete chaos and to reduce the potential for “foot shooting” Other rules exist to promote SCM best practices

Dev_streamA BL1

Deliver…

 Other scenarios may not be allowed

BL2

due to UCM’s implementation

Activity A

 These are less fortunate, but should still be viewed as “expected behavior” nonetheless REL 1

BL3 13

IBM Software Group

Components, Streams, and Baselines  Deliver operations migrate (merge) changes from one or more activities across streams  Rebase operations update a stream’s configuration, and only work at baseline (not activity) granularity

 Baselines are created: Along component boundaries Within the context of a stream

 Projects configure: Component visibility Component modifiability

 Bottom Line: Understanding the subtleties of deliver and rebase operations requires a solid understanding of UCM objects like components, streams, and baselines

14

IBM Software Group

Component Refresher  Generally speaking, a component it a set of related elements developed, integrated, and released together

 A UCM Component is a set of 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

str .h

i n c

Com pA

im p.h

li b a str .c

li b b tx t.c

flt .c

Reduces complexity Promotes sharing and reuse

15

IBM Software Group

Baseline Refresher  Generally, a baseline is a named, stable configuration that represents the integrated work of team members

 A UCM Baseline… Identifies one version of each element in a single component Is immutable Is created within the context of a UCM stream

•

str .h 1 2

im p.h

str .c

1

1

2

tx t.c 1 2

3

Except for special baselines (e.g. Initial, Imported baselines)

Is cumulative in that it always contains the contents of the last baseline plus some new activity(ies) 16

IBM Software Group

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

D

A C B

17

IBM Software Group

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

18

IBM Software Group

UCM Deliver Policies

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

19

IBM Software Group

UCM Deliver Policy Basics  Deliver Policies  Separate policies exist for inter-project and intra-project deliver  Policies apply to the target stream  Target stream decides what is acceptable to deliver

 Policy Control  Deliver policies are controlled at project AND stream  Project policies govern all streams in the project  Can enable or disable a policy for the entire project  Can defer setting to each individual stream  Stream can enable or disable – project takes precedence

20

IBM Software Group

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

In order to get the big picture of a given target stream’s policy settings, you must look at all of the settings on both the stream and its project

21

IBM Software Group

UCM Deliver Policy Specifics  The old standbys… Allow delivery with checkouts in the source stream Require rebase to recommended baseline(s) before delivery

 Intra-project deliveries Allow delivery of foundation in addition to activities from the stream Allow delivery despite source/target stream component mismatch

 Inter-project deliveries Allow inter-project delivery in general Allow delivery of foundation in addition to activities from the stream Allow delivery despite source/target stream component mismatch Allow delivery despite source/target stream component modifiability mismatch

 All deliver policies are DISABLED by default

22

IBM Software Group

Inter-Project Delivery Example REL1 Integration

Feature B did not make the cutoff for REL1

REL1_BL1

REL2 Integration Ralph_REL1_Dev REL1 BL1 Feature A

REL2_BL1

Developer delivers changes directly to their dev stream for REL2

Ralph_REL2_Dev REL2 BL1

REL1_FINAL

Feature B

23

IBM Software Group

Exhibit A: Inter-project Delivery Policy Violation

 Inter-project deliveries are governed by an over-arching UCM interproject deliver policy By default, inter-project deliveries are NOT permitted - so this error will pop up in those cases unless/until policies are opened up

24

IBM Software Group

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

X X

A A B B

25

IBM Software Group

Intra-Project Delivery: Same Foundation  Alternate target deliver operations can involve changes made in the source stream only

Integration

BL1 Dev_stream2 Dev_stream1

BL1

BL1 Activity B

26

IBM Software Group

Intra-Project Delivery: Different Foundation Integration

BL1 Dev_stream1

Act 1 Act 2

BL1

BL2 Dev_stream2 BL2

My Bugfix

Delivering “My Bugfix” from Dev_stream2 to Dev_stream1 will also deliver the foundation baseline (BL2) 27

IBM Software Group

Exhibit B: Foundation Baseline Mismatch

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

28

IBM Software Group

Tweak Deliver “Foundation” Policy Settings, OR… Integration

Alternatively, rebase Dev_stream1 first…

BL1 Dev_stream1 BL2 BL1 BL2 Dev_stream2 BL2

My Bugfix

And then deliver the activity when the foundations match This alternative approach accomplishes the same thing without opening up deliver policies 29

IBM Software Group

UCM Will Still Notify Users if Policy is Loosened

 Setting deliver policies is really a matter of a project manager’s preference – and is typically set based on users’ experience level

30

IBM Software Group

Consider These Alternate Target Deliver Scenarios Many alternate target deliver scenarios may involve merging more changes than you might think

Project Integration

BL1

DevB BL1 DevA

BL1.1

BL1

DevB2 BL1.1

DevC

BL2

BL2 BL2.1

DevC2 BL2.1

31

IBM Software Group

Component Visibility and Modifiability  UCM allows a project manager to make distinctions as to how UCM projects make use of components Producer (modifiable) Consumer (read-only)

 These settings are visible at the project level

32

IBM Software Group

Visibility/Modifiability Impact on Change Flow Change flow operations may involve changes in components from the source stream that are not visible in the configuration of the target stream, or are visible in the target, but not modifiable UCM’s deliver policies provide an effective way to prevent deliver operations when there is a mismatch between the source and target streams’ component configuration

• Separate policies exist for visibility mismatch and •

modifiability mismatch Separate policies govern intra-project and inter-project deliveries

33

IBM Software Group

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

N

Y X Z REL1 Project

M

REL2 Project 34

IBM Software Group

Exhibits C,D: Component/modifiability mismatch

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

IBM Software Group

Why does UCM care about these mismatches?  Because loosening these policies enables the possibility of partial change sets to creep into some configurations  UCM allows a single activity’s change set to span component boundaries – this is a product feature  If component mismatch policies are loosened willly-nilly, then beware of the possibility for partial changes to be delivered  Deliver Scenario (Partial Change Sets):  Activity123 may have versions in its change set from both components A and B  A developer delivers Activity123 to another project’s integration stream  The other project only has visibility/modifiability of component B, but the deliver policy settings that check component visibility are loosened to allow this  Oops! Now the deliver target only picked up part of the change for Activity123 UCM project managers should fully understand the consequences of loosening these policies (potential flexibility vs. consistency tradeoff) or else they “shouldn’t go there” 36

IBM Software Group

Mystery #2: Can’t Deliver Selected Activities  Can’t deliver activity(ies) due to UCM’s deliver “rules” Exhibit E: Individual activities from integration stream

 Can deliver activity(ies) due to dependencies: Caused by overlapping change set versions

• •

Exhibit F: Created explicitly by development activities Exhibit G: “Forced” by rebase activities

Caused by existence of baselines in the source stream

• •

Exhibit H: Created explicitly using mkbl in the source stream Exhibit I: Created implicitly by the deliver operation

G

E F

I H 37

IBM Software Group

Under the Microscope – UCM’s Deliver Operation  UCM’s deliver operation attempts to

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

 In reality, the mechanics of deliver work slightly differently than this

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

 The end result is the same, but the

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

IBM Software Group

UCM Deliver Mechanics  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

Integration

BL1 Dev_stream1

 Internally, UCM creates baselines on the source

trans1 BL1

stream for each deliver operation  The operation actually delivers the baseline containing the activity, rather than actually delivering the activity itself

Activity A

Deliver

 The baselines created by the deliver operation are unlabeled baselines

Activity B

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.

Activity C

Deliver

39

IBM Software Group

Exhibit E: Integration Stream is Source Stream  Deliver selected baselines only  UCM does not allow activity-level granularity when the source stream in a deliver operation is a project’s integration stream

 Integration streams must deliver using selected baselines  Integration stream is typically the place where many UCM baselines are created by the integrator and/or project manager  UCM limits deliveries out of an integration stream to baselines that have already been created in that stream Now that we understand how the deliver operation actually works behind the scenes, we can better understand why UCM limits deliveries out of an integration stream to baselines. Project managers probably would not want arbitrary baselines (caused by deliveries) being created in an integration stream, so UCM – by rule – prohibits this from ever happening by not allowing individual activities to be delivered from an integration stream. 40

IBM Software Group

Proj B Integration

BETA

Source Stream is Integration Stream ProjA Integration

BL1 Activity B

Dev_streamA BL1

Deliver…

BL2 Activity A

REL 1

BL3 41

IBM Software Group

Delivering Baselines

This menu is inactive in this context

42

IBM Software Group

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

For activity-level granularity, always deliver using a development stream as the source stream

43

IBM Software Group

Delivering Selected Activities  In source streams where there exist multiple activities with undelivered work, UCM gives users an option: Deliver all activities in the source stream (the default) Deliver only selected activities in the source stream

 In the case of selective activity deliveries, UCM may enforce the delivery of other “dependent” activities

44

IBM Software Group

Can’t Deliver Selected Activities  I’m sure you’ve probably seen this dialog box before

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

45

IBM Software Group

Deliver Dependencies  Activity dependencies take two forms: Overlapping activity change sets

• •

Dependencies can be created knowingly by users who work on the same files simultaneously across different activities in the same stream These dependencies can also be forced on users by rebase operations that are performed while work is still pending in a source stream

Baselines in the source stream

• •

In multi-tier stream strategies, baselines may be purposely created in development streams (that act as intermediate collection points) Under the covers, baselines are created by deliveries out of the stream − These dependencies are unfortunate, and often misunderstood − This is known limitation of UCM and can cause some customer heartburn when they encounter this scenario

46

IBM Software Group

Change Set Dependencies Integration

 Change set dependencies are probably the most common (and most understandable) form of activity dependencies  In this case, Activity B cannot be delivered without also including Activity A  This is really no different than a Base-CC findmerge operation from branch to branch

Integration Integration

BL3

Base CC would also make you include the changes in version 1 when merging the changes from version 2 to the integration branch 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).

77

88

Joe Dev

trans1 BL3 Joe Joe Dev Dev

11

Activity A 1

22

Activity B 2

47

IBM Software Group

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

File1

File2

File3

Feature X Fix 101

File4

File5

Feature Y Fix 102

Fix 103

Fix 3

48

IBM Software Group

Exhibit G: “Forced” Dependency (Upon Rebase)

File1

File2

File3

File4

File5

Unfinished Rebase Fix 101

Fix 102

Fix 103

Fix 3

49

IBM Software Group

Hint: Mitigating Merges upon Rebase  Even though there is no guarantee against having to do

merges upon rebase, it is never a bad idea to “retire” a dev stream every so often in favor of a new dev stream  Every stream has a distinct branch type association A long-lived stream will have a branch instance for any element ever modified within the context of that stream A new stream won’t have any branch instances for elements not modified in the stream since the stream was created

 Retiring old streams in favor of new ones will reduce the likelihood of merges upon rebase

Best case scenario will update config spec without requiring merges Mitigating rebase merging may also mitigate rebase dependencies

50

IBM Software Group

Perils of Long-Lived Streams 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.

Integration

Integration Integration

deliverA

77

BL3

Joe Dev

trans1 BL3 Joe Joe Dev Dev

88

11 Deliver Deliver

deliverX

deliverY

15 15 16 16

Activity A 1

BL4

BL5

22 33

RebseBL4

RebseBL5

51

IBM Software Group

“Retiring” Dev Streams

Integration

Integration Integration 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.

deliverA

77

BL3

Joe Dev

trans1 BL3 Joe Joe Dev Dev

88

11 Joe Dev2

deliverX

trans1 BL4 BL5 Joe Joe Dev2 Dev2

No merges!

deliverY

Rebase to BL5

15 15 16 16

Activity A 1

BL4

BL5

22 33

RebseBL4

RebseBL5

52

IBM Software Group

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

53

IBM Software Group

Exhibit H: “Explicit Baseline” Dependency  Sometimes users and/or project managers will intentionally create baselines in a development stream This isn’t common in a relatively flat stream hierarchy But this can be very common in a nested stream hierarchy

• •

Feature stream model Sub-team model

 When activity dependencies occur in these scenarios, they are more understandable to end users

54

IBM Software Group

Sub-Team (Feature Stream) Example Integration

The project integration stream is the eventual collection point for inter-team integration Developers “join” the project by creating their development streams under their respective sub-team’s stream

BL1 Core_Team BL1 BL2

Jim_Core_Dev

Jill_Core_dev

BL1

BL1

Intermediate development streams act as “integration” streams for individual teams

GUI_Team BL2

Chris_GUI_dev BL2 55

IBM Software Group

Sub-Team (Feature Stream) Example Integration

Developers deliver to their sub-team “integration” stream …And subsequently rebase from baselines created there

BL1

Core_Team BL1 BL2

CORE_BL1

Jim_Core_Dev

Jill_Core_dev

BL1

BL1

GUI_Team BL2 GUI_BL1

Chris_GUI_dev BL2 56

IBM Software Group

Sub-Team Example Simplified 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.

Integration BL1 Core_Team BL1 CORE_BL1 deliverA

BL2

Deliver

deliverB

Jim_Core_Dev

Jill_Core_dev

BL1

BL1

Activity A

Activity B

Activity C

CORE_BL2

deliver C

Integ Act

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

IBM Software Group

Exhibit I: “Deliver Baseline” Dependency  Two sibling development streams exist within a UCM project Integration  Developer 1 works on several activities in the context of Dev_stream1  Developer 1 delivers only a selected activity BL1 (Activity A) to Dev_stream2

Dev_stream2 trans1 BL1

 This is an alternate-target deliver scenario

 Developer 1 now tries to deliver a different

Dev_stream1

selected activity (Activity B) to the project’s integration stream

trans1 BL1 Activity A

 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!

Deliver Deliver

Activity B

The existence of this (unlabeled) deliver baseline forces the inclusion of Activity A for any subsequent deliveries out of Dev_stream1 58

IBM Software Group

Solving the Mysteries of Activity Dependencies  Obvious solution – deliver everything or minimally the selected activity and its dependents (not ideal if that’s not what you want to do)  Working in a one-activity-per-stream model will always avoid this particular problem by isolating work on each activity in its own stream This model introduces more overhead and potentially more complexity

 Drop down into base ClearCase and do some subtractive merging Dave Bellagio’s cset script is capable of doing this today

 Will the product itself ever offer relief in this area?

• •

There are no current plans to offer subtractive merges via the UCM deliver operation in order to break change set dependencies Baseline dependencies are a big limitation and a known problem for customers – and it would be highly desirable to “fix” this problem − However, there are some clever workarounds to this problem Longer term, the next-generation UCM solution won’t suffer from these types of limitations 59

IBM Software Group

One-Activity-Per-Stream Model  Create a new stream for each new activity  No development stream ever contains more than one activity  Pros  Complete activity independence

•

Won’t be forced to combine activities if not desired

 Ability to create configurations with arbitrary combinations of activities

 Cons  “Porcupine” models are high-overhead

•

These models require many streams (and merges)

 UCM provides few conveniences to work this way

• •

“Join Project” wizard may not apply − Probably favor a straight “create stream” approach for new activities − New activity must be created as an additional step Not SQUID-friendly out of the box − The WorkOn action cannot create a new stream on the fly

60

IBM Software Group

One-Activity-Per-Stream Example Integration

A single integration stream is usually the collection point for all changes within a project

BL1

A new development stream is created for each new activity

Feature A Bugfix 123

Feature B

BL1

BL1

BL1 BL1

Each activity is worked in isolation, independent of all others

Feature A

BL2 Feature B

Bugfix 123

Bugfix 456 BL2

Activities may be delivered in any sequence

Bugfix 456

61

IBM Software Group

Workaround to Deliver Baseline Dependency Issue  Can’t deliver selected activity because of a previous delivery from the source stream to an alternate target  Create a new activity in the development stream This activity will be “beyond” the deliver baseline that is causing the dependency problems

 Move the changes from the originally delivered activity’s change set to the new activity that was just created  Remove the original activity from the source stream  Attempt to deliver the selected activity again This delivery will succeed without delivering the changes in the original activity’s change set The new activity – even though it contains the same changes, is no longer a dependency because it is not included in a baseline

62

IBM Software Group

“Deliver Baseline” Dependency Workaround  An original activity is created and delivered 

   

(alt-target) to a sibling development stream Integration 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) BL1 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

Deliver Deliver

Success!

Dev_stream2 trans1 BL1 Dev_stream1 trans1 BL1 Original

Deliver Another

Workarnd

Be aware, however, that when you use rmact, you may see strange reporting when using diffbl and/or lsact – contrib (because the original activity is no longer there) 63

IBM Software Group

Using cset.pl to Move Changes (when deliver won’t)  As a last resort (if all other workarounds aren’t acceptable for a given case), you can use the cset.pl script – obtained internally  This script is not officially part of the ClearCase product (it is custom script)  Using this script is really just an automated equivalent to dropping down into base ClearCase and using fancy merging techniques (e.g. merge -insert)  Be aware that by doing this you may be inhibiting your ability to track your changes back to the original activity

 In this illustration, cset.pl –move is used to effective “move” a single activity’s changes from Project_2’s integration stream into Project_1’s integration stream  UCM’s deliver operation would prohibit this operation because it only allows baselines (not individual activities) to be delivered between integration streams

Always beware of the side-effects of using baseCC merge techniques within a UCM environment 64

IBM Software Group

Mystery #3 – Can’t Rebase or Recommend Baseline  Can’t rebase in any direction or even recommend baselines Exhibit J: Because baseline is not contained in parent Exhibit K: Import baselines are not “real” baselines

 Can’t rebase backwards and/or “sideways” Exhibit L: Because changes exist in the stream Exhibit M: Identical baselines were created in the stream Exhibit N: Baselines were implicitly created by composites

J

N

L K

M 65

IBM Software Group

Rebasing Streams: A Refresher  Normally rebase to recommended baselines This is always the default rebase behavior

 Can also rebase to arbitrary baselines selected by the user Subject to validation by the stream

 Five cases: Advance to successor Revert to predecessor* Move “Sideways”* Add new component Drop component* * Restricted operations

66

IBM Software Group

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

BL1

IntStream

DevStream

BL1

BL3 BL1

IntStream

DevStream

BL1

BL2

BL2

BL2

BL3

BL3

BL3

Revert

DevStream

P2.1

P2.2 BL1

BL3 BL1

Advance

Project2

P2.2

P2.3

Sideways 67

IBM Software Group

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

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

68

IBM Software Group

“Rules” for Rebase Advance – New baseline already contains current foundation

• • •

Rebase in this direction is always allowed Changes are merged in the view if needed Many cases have no merge, rebase just updates the config spec

Revert – New baseline is an ancestor

• •

Allowed if there are no changes to the component in the stream Always allowed on read-only streams

 Sideways – Neither ancestor nor descendent  Allowed if component is non-modifiable and there are no baselines (ident baselines) on it, OR  If the new baseline would not strand changes in the stream (or its child streams) AND the stream would only be delivering its own changes to its parent

69

IBM Software Group

Sideways Rebase Rules Explained 

This confusing Verbiage:  No (child) stream would have stranded changes  Stream would only be delivering its own changes



Can be more clearly restated as:

The new baseline must be contained in the parent stream

Rel_1.0

trans1 Build_stream trans2

Dev_stream2 trans1

trans2

Dev_stream1 trans1

trans2_deploy

The development streams are only allowed to rebase to trans2_deploy after Build_stream has delivered its work to the integration stream 70

IBM Software Group

The “Contained In Parent” Rebase Rule  Rebase allows a stream to pick up changes from another stream provided those changes have been delivered to its own parent Ensures that the default deliver to a parent stream delivers changes from your stream Requires integration one level higher than you

 The rules for recommending baselines are consistent with the rules for rebase UCM will allow a parent stream to recommend a baseline that was not created in that parent …As long as the parent stream also sees those changes

71

IBM Software Group

Stream Ancestry - Terminology Integration

Grandparent Parent

BL1

Parent Child Dev_stream1 BL1 DEVBL1

Child Dev_stream1A

Dev_stream1B

DEVBL1

DEVBL1

Siblings

72

IBM Software Group

Stream Ancestry – Terminology (cont.) Integration

BL1 Dev_stream1

Dev_stream2

BL1

BL1

DEV1BL1

DEV2BL1 Dev_stream1A

Dev_stream2A

DEV1BL1

DEV2BL1

Cousins

73

IBM Software Group

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

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

IBM Software Group

Exhibit J: UCM Genealogy Lesson Mainline Project

BL6

BL7

Project N

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.

Deliveries from other projects

BL8

BLN3 Project Z BLN4

BL9

BLZ1

This failed rebase scenario came up recently at a customer deployment 75

IBM Software Group

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

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

IBM Software Group

Sharing via Alternate Target Delivery Integration

Developer1 and Developer2 want to share changes without going through the integration stream

BL1 Dev_stream1 Dev_stream2

BL1 BL1

BL1

My Bugfix

Deliver the activity directly from one development stream to the other

77

IBM Software Group

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

Integration

BL1 Dev_stream1 Dev_stream2 BL1

My Bugfix

Deliver the changes to the integration stream (the parent for both of these dev streams)

DEV_BL

BL1 BL1

First attempt to rebase will fail because the BL is not included in Dev_stream1’s parent

78

IBM Software Group

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

Integration

BL1 Dev_stream1 Dev_stream2

BL1 BL1

BL1

My Bugfix

Deliver the changes to the integration stream (the parent for both of these dev streams)

DEV_BL

The rebase will now succeed

79

IBM Software Group

Exhibit K: Rebase and Imported Baselines  “Import Baselines” are a handy mechanism for creating a starting point for new UCM projects From past Base-ClearCase labeled configurations From past history imported form a conversion tool

 Imported baselines are not so handy when used as “general purpose” UCM baselines Import baselines are special-cased – they are not “real” baselines Import baselines are not recorded in a stream’s “timeline”

 Imported baselines were only designed to be UCM “starting points” (foundations of a new stream)  Any other use of import baselines (e.g. rebase) will likely have some functional limitations

80

IBM Software Group

Imported Baselines as Stream Foundations 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.

main main

77 REL1

88

REL1

Rel2 Integration REL1

REL2_Integration REL2_Integration

15 15

16 16

LABX

LABY LABY LABZ

17 17

11

LABZ

Rel3 Integration

13 13

LABY

REL2 Rel4 Integration LABZ

81

IBM Software Group

Imported Baselines are not “Full Service” Baselines

They can be used effectively as foundations for new UCM streams, but…

Imported baselines are not created within UCM streams

Rebase? 82

IBM Software Group

Rebase Between Two Imported Baselines main main

77 REL1

88

REL1

Rel2 Integration

These imported baselines were created from BaseCC 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

REL1

REL2_Integration REL2_Integration

15 15

LABX

11

LABX

Rebase LABX

Use the least common denominator (Base CC) to move changes between Base-CC branches and UCM streams. Findmerge, for example, could be used in this scenario to effectively “rebase”.. 83

IBM Software Group

Rebase Between Two Imported Baselines (cont’d)

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

IBM Software Group

Exhibit L: Changes Exist in the Stream  UCM baselines are immutable and their contents are cumulative (inclusive of all previous baselines)  Therefore, rebase in any direction other than advancing is subject to validation by the stream  “Backwards” rebase is the most constrained rebase direction because it is prohibited if changes exist in the stream being rebased  Under the “rules” of rebase, backwards rebase is only permitted when no changes exist in the stream being rebased Read-only streams can always be rebased backwards

According to UCM’s “rules”, backwards rebase is only permitted on streams with no modifications

85

IBM Software Group

Backwards Rebase Illustrated restricted from rebasing backwards  No branch instances for that stream exist in any elements

Integration

BL1

 Reverting in this case simply replaces the foundation baseline

Deliver 1

 A stream that contains changes may

Deliver 2

not revert to a predecessor baseline  This is true whether the changes in the stream conflict with the existing baseline or not

Dev_stream2 BL1 BL2 trans1 BL1

Dev_stream1

Revert BL1

 A stream containing no changes is not

trans1 BL1 BL2

BL2

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

Revert BL1

Activity A

86

IBM Software Group

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

87

IBM Software Group

Why mkbl –ident can be a dangerous thing  Some customers use mkbl –ident in order to force a common naming scheme across baselines that were created at the same time This may seem like a clever solution to this problem Composites and/or templates are probably a better solution

 Gratuitous usage of mkbl –ident can prevent cases of sideways and backwards (revert) rebase – even when there are no changes on the stream being rebased Because mkbl –ident force-creates new baselines in a stream, even when new baselines are not required You can really paint yourself into a corner and take away a lot of rebase flexibility if your UCM process involves frequent usage of mkbl –ident. Even if there are no changes in a stream, identical baselines will make the UCM rebase operation behave as if there are changes in the stream 88

IBM Software Group

Sidebar: Recommending Baselines  UCM attempts to enforce the notion that users should always be successful rebasing to recommended baselines  UCM will not allow a parent stream to recommend a baseline to which its children cannot successfully rebase  Therefore, the act of recommending baselines validates the baseline(s) that a parent recommends to its children A child stream may be configured with any of: • A baseline created in its parent stream • A baseline in the parent’s foundation • A baseline created in a stream other than its parent (in the same project), and is contained in the parent

89

IBM Software Group

Exhibit N: Nested Composite Baseline Override  Mathlib, Alpha, and Gamma are composite baselines  Alpha and Gamma both contain a baseline of component C, and these are 

in conflict with one another User must override component C (with C5) to resolve this conflict Mathlib1

C5 C5

Alpha1

A1

F2

C3 Gamma2

B2

C1 C1

E1 90

IBM Software Group

Overrides are Modifications  Mathlib makes changes in F and needs a new baseline Mathlib1

C5 C5

Alpha1 F2 A1

C5 C5 C3

Gamma2

B2

C1 C5 C5

E1

 Where are the changes? Component F Also: Components Alpha and Gamma (Because there is a new member of component C visible) 91

IBM Software Group

Rootless Changes Won’t Restrict Rebase  Project delivers a single (composite) baseline  Root of this baseline is on a rootless component  Greater flexibility for customer-projects

Mathlib1 Alpha1 F2 A1

C5

Gamma2 B2

C1 C5

E1

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

IBM Software Group

Mystery #4: Deciphering Deliver/Rebase Messages

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

O

P Q 93

IBM Software Group

Exhibit O: Deliver Non-mergeable Element Types  The Problem UCM can’t generate a config spec to do the potentially easiest thing

• • •

E.g. Never branch non-mergeable elements This is a one-line addition to a config spec in base CC Adding custom config spec rules to UCM won’t help in this case

ClearCase also has no concept of “universally reserved” checkouts

•

To ensure no one else is ever modifying a given element on any branch

 The UCM Solution UCM can only support a “branch and never merge” or “branch and copy merge” model, it can’t support a “never branch” model. Choices:

• •

Branch all non-mergeable elements and leave them hanging Branch all non-mergeable elements and “copy-merge” them

94

IBM Software Group

The Problem Illustrated

95

IBM Software Group

A Solution: Use Merge Type Attributes    

Merge type attributes are supported by deliver and rebase Implemented via element type attribute called mergetype Merge types are created on custom element types using mkeltype The currently supported merge type attributes are:  Auto (default)

•

deliver/rebase will automatically merge elements using the element’s specified ClearCase type manager (this is why deliver/rebase won’t work by default) • Probably want to try to avoid these scenarios when dealing with binaries and other non-mergeables as deliveries will always require manual intervention • Only use this attribute on mergeable element types  User

• • •

deliver/rebase will automatically perform trivial merges by “copy-merging” non-trivial merges must still be done manually Example: user this attribute on VB Forms (*.frm, *.frx) and .NET artifacts  Never

• •

deliver/rebase does not merge these files at all Example: use this attribute on type on staged DO elements

96

IBM Software Group

Merge Type Attribute Example  Create a new element type called “image” and attribute the new element type with the “user” merge type: O:\class_comps\compA\junk>cleartool mkeltype -nc -super compressed_file -mergetype user image Created element type "image".

97

IBM Software Group

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

Binaries of element type “image”

98

IBM Software Group

Merge Type Attribute Example (cont.)  Start the delivery

99

IBM Software Group

Merge Type Attribute Example (cont.)  Observe the version history of the two “image” elements

100

IBM Software Group

Merge Type Attribute Example (cont.)  During the delivery…

101

IBM Software Group

Merge Type Attribute Example (cont.)  Manually merge the non-trivial image

102

IBM Software Group

Merge Type Attribute Summary  Merge type attributes can be used effectively in dealing with binaries and other non-mergeable element types in deliver/rebase scenarios Use the “user” merge type to automatically “copy-merge” trivial changes Use the “never” merge type to ignore changes altogether Use the “auto” merge type for all element types that can be merged by a known type manager

 As we saw, some of these merge types can help automate the delivery of non-mergeable element versions However, there are no guarantees of fully-automated merges in all cases

 Caveats: Prior to v2003, there were some scenarios whereby the “user” merge type did not work as advertised because of bugs in the deliver operation (not properly identifying some trivial merges) These were fixed in v2003

103

IBM Software Group

Exhibit P: Skipping Elements Upon Deliver/Rebase  Sometimes deliver and/or rebase will notify the user that some elements are being “skipped”  These warnings are most visible when running the operations from the CLI  From the GUIs, rebase warnings tend to be more visible than deliver warnings

 Typically, this is caused by directory changes (e.g. rmname) in one stream that conflict with changes in another  Take care to understand the details of what it being skipped so that changes don’t “fall on the ground”  Or else you may experience the “now UCM (you see ‘em), now you don’t” phenomenon

104

IBM Software Group

Skipping Elements Scenario  A versioned directory in a modifiable

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

 Upon rebase to a baseline that includes a

version of the directory with the element removed, rebase will warn the user that it is “skipping” the element

105

IBM Software Group

Skipping Elements Illustrated Development

Integration

trans1

Same Foundation

n+1

Deliver

n

rmname

106

IBM Software Group

Skipping Elements (cont’d)

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

107

IBM Software Group

Skipping Elements (Rebase)

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

IBM Software Group

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

Wait a minute… The deliver operation is supposed to detect when the target stream is remotely mastered and “post” the delivery. Isn’t that a UCM feature? It is, but that’s not exactly what’s happening in this case. This scenario can be as confusing as the error message itself. In this case, UCM is actually trying to tell you that there is already a posted delivery in progress, and that this new delivery cannot be posted until the first one has been completed. 109

IBM Software Group

Can’t Post Delivery in a MultiSite Environment Integration

Site: India

Site: USA

BL1 Dev_stream2 Dev_stream1

BL1 BL1

BL1

Delivery of Activity A is completed normally

Activity A

Activity B

Delivery of Activity B is posted, but not completed Activity C

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. 110

IBM Software Group

Mystery #5: Can’t Stabilize a Baseline

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

R S

111

IBM Software Group

Integration Streams are “Moving Targets”  Baselines contain changes from many streams  Developers can rebase to recommended baseline(s) before delivering their changes, but new changes keep arriving  The larger the project, the larger the volume (and frequency) of new deliveries to the integration stream

 Desire to stabilize a baseline from the integration stream,  But that may involve making more changes on top of the baseline  This cannot easily be done when new changes have already been introduced to the integration stream

 The integration stream wants to recommend a baseline that contains changes from its stream, plus any changes needed to fix problems in that baseline

112

IBM Software Group

Volatility of the Integration Stream Integration

 Two O'clock and all is well A new baseline (BL2) is created on the integration stream This baseline represents the “tip” of the stream Would like to test this baseline and potentially recommend it to other streams

BL1

BL2 Deliver 1

Deliver 2

Deliver 3

 Three O'clock and things have changed Testing reveals that minor changes must be made to BL2 However, by this time, many new deliveries have cluttered up the integration stream

113

IBM Software Group

Things Look Different Than They Used To… Integration



BL1

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



BL2

Consider These Options I.

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)

Deliver 1

Deliver 2

Deliver 3

III. Create a “stabilization stream” Stabilization streams don’t have as many drawbacks as the first two options

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

IBM Software Group

Exhibit R: Using Stabilization Streams  Stabilize configurations by isolating the work in one or more    

component baselines to a different stream This stream can then be used for build stabilization or for QE testing Fix errors or testing defects in the stabilization stream Create a baseline in the stabilization stream Deliver that baseline to the integration stream  This is a key step  The project’s integration stream can only recommend this baseline to its child streams if the baseline is contained within the stream itself

 Recommend the baseline from stabilization stream  Development streams may then rebase to the more stable baseline rather than one created on the integration stream 115

IBM Software Group

Using Stabilization Streams – An Illustration Integration

BL1 is recommended BL2 is created, but not stable

BL2-STAB may be recommended once the changes are seen by the integration stream. The development stream can then rebase.

BL1 Dev_stream1 BL2-STAB BL1 BL2

Influx of new deliveries makes it nearly impossible to try to stabilize BL2 directly on the integration stream Deliver to the integration stream

Deliver 1

Stabilization BL2

Deliver 2

Deliver 3

Stab

Create a stabilization stream from BL2 and make changes necessary to stabilize the BL

BL2-STAB

Create a stable baseline 116

IBM Software Group

Exhibit S: Creating “Selective” Baselines  Stabilization streams provide much flexibility, but also impose the overhead of a new stream, recommending baselines, etc…  Alternatively, in some cases it may be possible to create selective baselines using the “mkbl –act” command Create a baseline that includes the last baseline plus selected activities The activities included in a selective baseline are subject to change set dependencies (similar to selective activity delivery)

 Many customers have tailored their UCM processes around using mkbl –act to create their baselines This technique has its advantages, but it also has its limitations

Whether to employ a selective baseline technique vs. creating stabilization streams vs. some other method is really a matter of preference. Each solution has its own set of pros and cons.

117

IBM Software Group

Creating Selective Baselines – An Illustration Integration

BL1 is recommended BL2 is created, but not stable

BL1

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. Dev_stream1 BL2-STAB BL1

BL2

Influx of new deliveries makes it difficult to stabilize BL2 on the integration stream Create a stabilization activity directly on the integration stream BL2-STAB

BL2 Deliver 1

+

Stab

Deliver 2

Deliver 3

=

BL2-STAB

Stab

Create a selective stable baseline (mkbl –act) 118

IBM Software Group

Selective Baseline Behavior (v2002 and v2003)  The default behavior for “mkbl –act” changed between v2002 and v2003 The change was introduced to fix a defect with the “diffbl” command Unfortunately, the fix to the diffbl problem further restricts “mkbl –act” in v2003

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

IBM Software Group

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

 Just remember that different groups have different isolation and integration needs

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

120

IBM Software Group

Mystery #6 My Baseline is Lying to Me  Exhibit T: Partial Change Sets Upon Delivery (Recap)  Exhibit U: Partial Change Sets Upon Rebase  Exhibit V: Partial Change Sets When Creating Baselines

U T

V 121

IBM Software Group

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

122

IBM Software Group

Exhibit T: Partial Change Sets Upon Delivery  Earlier we discussed the value of UCM’s deliver policies and how tightening those policies can decrease the likelihood of creating configurations with partial change sets  Deliver Scenario (Redux from earlier):  Activity123 may have versions in its change set from both components A and B  A developer delivers Activity123 to another project’s integration stream  The other project only has visibility/modifiability of component B, but the deliver policy settings that check component visibility are loosened to allow this  Oops! Now the deliver target only picked up part of the change for Activity123

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

123

IBM Software Group

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

 Rebase Scenario (Partial Change Sets)  Activity123 may have versions in its change set from both components A and B  A developer delivers Activity123 to the integration stream

•

An integrator creates new baselines for both components A and B

 Another developer rebases their dev stream just to the new component A baseline

•

Oops! Now they’ve only picked up part of the change for Activity123

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

124

IBM Software Group

Deliver Policies Don’t Mitigate All Potential Risks!  Other (non-deliver) scenarios can also expose partial change sets  UCM provides NO policies to govern partial change sets for the following: Changing a project’s recommended baselines Rebasing to baselines other than recommended Setting up the foundation of a new project/stream

 In addition to tightening deliver policies, a PM might also consider: Avoiding activities whose change sets gratuitously span components

•

And potentially writing triggers to enforce this

Use composite baselines to ensure that related baselines of components are always used together whenever change sets do span component boundaries Avoiding partial change sets when new baselines are created Tight deliver policies are only one mechanism that may be employed to mitigate the risk of partial change sets. Project managers and users alike must employ other techniques for avoiding partial change sets during baseline creation and during rebase. 125

IBM Software Group

Exhibit V: Partial Change Sets During mkbl  An individual component baseline itself may contain partial change sets from included activities UCM does not validate whether an entire activity is physically included in a baseline at the time when the baseline is created

 Example – running mkbl while a delivery is in progress may capture only part of a delivered activity  A baseline that contains only a partial change set will still report that it contains a certain activity, however only some of the versions in its change set might actually be labeled by the baseline

126

IBM Software Group

Avoiding Partial Change Sets During mkbl  The mkbl command is not an “atomic” operation  Tips to mitigate the risk of partial changes in baselines: Lock the integration stream before creating baselines

• •

This is something that the UCM documentation recommends Not always possible or feasible in some shops due to the inconvenience it may cause on the integration stream

If the stream cannot be locked efficiently, check the consistency of baselines with a trigger or some other mechanism – post baseline creation Deliver and rebase aren’t the only operations to watch out for. Baseline creation should also be an area of concern.

127

IBM Software Group

Mystery #7: Can’t “Back Out” Deliveries  Deliver and rebase can be cancelled before completion  Cancellation effectively nullifies the operation and reverts to “old” configuration  Once completed, UCM provides no out-of-box way to “undeliver” changes from the target stream’s configuration

 This is a frequent customer complaint

128

IBM Software Group

UCM has no formal “undeliver” command Integration

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

Deliver 2

Deliver 3

Deliver 4

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

129

IBM Software Group

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

 Non-trivial cases could also be effectively cancelled out with scripting  Create an “anti-activity” that effectively removes the offending changes  Subtractive merges would have to be performed in cases of dependent changes

•

The cset.pl script can be used in this capacity

 Start a new “integration” stream that effectively “backs up” to the last good baseline that does not include the offending changes

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

IBM Software Group

Using cset.pl to Effectively “undeliver”  Earlier, we saw an example of how “cset.pl –move” could be used to effectively move changes across streams  In this case, we can use “cset.pl –undo” to effectively remove changes from a stream  The script actually subtracts the changes by adding an “anti-activity” to the stream which effectively removes the change set of the offending activity  The original activity does not really disappear from the stream, rather it’s changes are cancelled out by the presence of its alter-ego

X Activity

Anti-Activity

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

IBM Software Group

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

IBM Software Group

Will UCM Ever Provide “Un-Deliver”?  UCM could provide this functionality for trivial cases  However, many cases would not likely be trivial

Integration

 Other deliveries may have arrived in the stream (which may have dependencies on the offending activity – requiring subtractive merge)  New baselines may have already been created in the stream

•

And other streams may have potentially rebased to those baselines Deliver 1

Deliver 2

Deliver 3

Deliver 3

Deliver 4

It is still possible that UCM could someday provide some limited undeliver operation in the future (for trivial cases). Longer term, next generation UCM will not be subject to such limitations. 133

IBM Software Group

Break Time… This appears to be 2-ply

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

IBM Software Group

SQUID Change Flow Intro Break

X Composite

Other Topics

Baselines

e r e h e r a u o Y 135

IBM Software Group

UCM Mysteries – Case #2

Comp o Base site line s A A

A A

A A

136

IBM Software Group

Composite Baselines  Introduced in v2002 as a means of aggregating multiple disparate baselines into a     

single entity Fulfilled the requirement of a single object to define a common development environment Simplified baseline management because only one baseline needs to be specified for the entire set of baselines Provided a mechanism to tie together multiple related/unrelated development components into a hierarchy – either as a flat structure or as a complex geometry Helped clear up the clutter of multiple baselines in the stream’s foundation by providing implicit selections of dependent baselines Supported the use of baseline overrides to supersede the changes brought by another implicit foundation baseline or to resolve conflicts of a common component in multiple composite hierarchies Although composite baselines are a great mechanism for streamlining changes, they are based on a set of rules which must be understood clearly and completely to do successful parallel development. Thus, it is imperative that a good deal of thought must be provided in deciding development strategies including component hierarchies, project policies, stream hierarchies. rootless/rooted components, release machinery etc. 137

IBM Software Group

Composite Baselines (continued)  Creation of composite dependency is possible through both the GUI and the CLI  Creation requires a new baseline on the top-level component of the hierarchy to denote the    

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

It is important to understand that the composite dependency relationship is between baselines and not components. This dependency may last for the life of a given project but it might be different for other projects and the dependency graph itself may change as more components are added/dropped. 138

IBM Software Group

Rooted vs. Rootless Composites  A composite baseline fulfills multiple roles – identifying a set of versions,     

aggregating members, changes in member components It is an expensive operation to determine which reason caused the creation of a new composite baseline A rootless component does not have an associated root directory (thus no elements) and need not be concerned with the role of identifying its own versions A new rootless composite baseline indicates either dependency relationship changes or new baselined versions of member components A rooted composite dictates a strict dependency relationship between components - an attribute not achievable using rootless composites UCM is less restrictive in terms of movement of foundation baselines (forward/backward/sideways) for rootless composites than it is for rooted composites Use rootless composites to combine components that do not require strict dependency relationships. These help projects adopt composite baselines quickly and successfully. Use rooted composites to ensure a close synchronization of related components. This prevents most baseline conflicts but is likely to be feasible for projects with a small number of shared components.

139

IBM Software Group

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

W

140

IBM Software Group

Exhibit W: Unable to rebase sideways after rebasing to a baseline of a read only component Project A

Project B

Project R R.BL1

Project X

A.BL1 B.BL1

R.BL2

A.BL1

B.BL1

A.BL2

B.BL2

A.BL3

B.BL3

A.BL4

B.BL4

A.BL2 B.BL2

R.BL3

R.BLX

A.BL3

A.BL2

B.BL3

B.BL4

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

IBM Software Group

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

X

142

IBM Software Group

Exhibit X: Project Policy Requires Rebase But Stream Ahead Of Current Recommended  A Classic case of when developers are over-enthusiastic in selecting “The Latest       

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

IBM Software Group

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

Y

144

IBM Software Group

Exhibit Y: Why is the other team making baselines on OUR components ?  This problem relates to an age-old quest of human kind on display of authority.  Team A creates a composite hierarchy on component CompA owned by the team.  The composite hierarchy on CompA contains:  components produced by the team (Aplus, Aminus)  read-only components produced by other teams (Oplus, Ominus).

 Team B consumes baselines of CompA but prefers a different version of Oplus and so overrides a baseline to suit its needs.  Team B plugs this composite hierarchy (with overrides) into its own bigger composite hierarchy on component CompB.  The composite hierarchy on CompB contains:  components produced by the team (Bplus, Bminus)  read-only components produced by other teams (Aplus, Aminus, Oplus, Ominus)

 Team B makes baselines on CompB which has a side effect of making baselines on CompA to capture the override on Oplus.  Team A is infuriated to see new baselines on CompA created by Team B. The bottom line here is that in this kind of producer-consumer relationship no one “owns” the composite component. If you are particular about who owns what, then share your stuff outside of a composite hierarchy. Alternatively, do it using a rootless component as it imposes fewer restrictions. 145

IBM Software Group

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

 Unable to create a development stream using the parent’s previous foundation set Exhibit Z: Because the parent stream has no history of its previous foundation baselines.

Z

146

IBM Software Group

Exhibit Z: Why can I not create a stream using a baseline that was in my parent’s foundation previously ? BootStrap Project BS.BL1

Project X DevStream X.1 BS.BL1 X.BL1

BS.BL2

DevStream X.2 BS.BL1

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

IBM Software Group

UCM Mysteries – Case #3

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

148

IBM Software Group

SUM ClearQUest Integration Doodad

149

IBM Software Group

These are the only SQUID guts you’ll see today! Remember that this is primarily a tips/tricks presentation. It was not intended to be an internals session. An advanced UCM class will be available for all those interested in learning about SQUID internals.

150

IBM Software Group

(One Reason) Why We Won’t Cover SQUID Internals  04/16/2004 10:08 PM  ID: 38836  Squid May Be Dangerous Work Hazard  3 crew members of a South Korean freighter (that washed ashore) may have died after breathing in toxic gas coming from rotting squid organs. The captain of the vessel is being questioned by the Coast Guard.

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

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

151

IBM Software Group

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

 This can cause problems if a given operating system user needs to perform SQUID operations with more than one CQ identity E.g. Operating system user “rcapasso” used the SQUID integration as CQ user “ralph”, but now wants to use the integration as CQ user “admin”

152

IBM Software Group

Mystery Solved: Clear the CQ User Cache  Unix and Windows use different mechanisms for implementing this cache  Registry setting on Windows  “Hidden” home directory file on Unix

 In either case, removing the cached CQ user value will force a CQ login dialog upon next use

153

IBM Software Group

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

154

IBM Software Group

Obstacles to Supporting Multiple CQ DBsets  CQ DBset names are not fixed. Users can name them whatever they want, and later change the name. There is no concept of a “universal selector” for CQ DBsets. CQ automatically changes the connection (or dbset) names when replicating a CQ database through CQ/MultiSite

 CQIntSvr currently creates a single file (on Unix) or one registry entry (on Windows) per user, containing dbset login information for the last dbset accessed by SQUID.

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

155

IBM Software Group

Working with Multiple CQ Dbsets Today  The current implementation of the SQUID depends on the “default” connection recognized by CQIntSvr as the dbset of the UCM project The one that is set from the CQ db maintenance tool

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

There are planned changes to support multiple DBsets (concurrently) in an upcoming new release

156

IBM Software Group

SQUID Mystery #3: Can’t re-assign an activity  A developer works on an activity in the context of one stream, but realizes that they really meant to work on that activity in another stream  The developer wants to “move” the activity to another stream The information in the CQ record is important, so creating a new activity in the other stream isn’t a good enough workaround

 Problem #1: UCM doesn’t allow such movement of activities across streams  Problem #2: The CQ record is already bound to an activity in the “wrong” stream

157

IBM Software Group

Re-assign an Activity that is Already “Bound”  A developer “Works On” an activity in the context of one UCM, but realizes that they should have indicated a different stream

Integration

BL1 Dev_stream2 Dev_stream1

BL1

BL1

“Bound” by SQUID

Activity B

User meant to work on this activity in Dev_stream1 instead 158

IBM Software Group

CC-Only vs. CQ-Enabled UCM  By UCM “rule”, an activity may not be moved from one stream to another after it has been created. The workaround in a CC-only UCM environment would simply be to create a new activity in the desired stream and work there In CQ-enabled UCM, this case is not as trivial because there is an associated CQ record (with information, history, etc…) that the user still wants to associate with a different activity in a different stream

 As long as the activity has an empty change set, then it is possible to “re-assign” the “activity” (e.g. the CQ record) to a new UCM activity in the desired stream This is accomplished by removing the original UCM activity (and its associations to the CQ record), creating a new activity – and associating that activity with the CQ record. In the future, SQUID may provide a more automated way to do this ‘re-association” 159

IBM Software Group

Re-assign an Activity that is Already “Bound”  Remove the UCM activity using “rmact”  This will also remove the association to CQ

 Associate the CQ record with a new activity in the desired stream Integration

BL1 Dev_stream2 Dev_stream1

BL1

BL1 New Act

Activity B

Remember that an activity cannot be removed unless its change set is empty and it is not currently set in any view 160

IBM Software Group

Mystery #4: Disabling the integration  There are different techniques and procedures for disabling (and subsequently re-enabling) the SQUID integration Some solutions are well known and well documented Some are only available through internal tooling Which one you should use depends upon the desired outcome

 An earlier presentation this week discussed the mechanics of the linkages between CC activities and CQ records This presentation does not get into those details, or details about backup, restore, and recovery of CQ-enabled UCM environments It will, however, provide some tips for achieving desired results

161

IBM Software Group

Permanently Disabling the Integration  SQUID has always provided a way to both enable and disable the integration “on-the-fly”  The checkbox on the right is the most obvious way to enable/disable SQUID  The chproject command is an alternate way of doing the same thing

 Disabling the integration in this fashion is a good way to remove all linkages of CQ from the CC project  This function not only disables the integration, but removes all record/activity associations  This is the best solution for permanently CQdisabling a project

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

IBM Software Group

Temporarily Disabling the Integration  If you only want to temporarily disable the integration (and subsequently reenable 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 reestablish the links between CQ and CC

163

IBM Software Group

Using chproject vs. ucmutil to Disable SQUID PVOB CQDB

MyProject Activity A

Activity B

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

IBM Software Group

Mystery #5: Deliver Transition Policy Not Granular  In ClearCase v4.x, all UCM policies (for deliver and for SQUID) were only granular at the project level This was the appropriate level of granularity for v4.x because it was not possible to create stream hierarchies in v4.x

 In ClearCase v2002, UCM introduced the notion of stream hierarchies, alternate-target delivery, etc… As a result, all of the deliver/rebase policies were changed such that they could be defined at either the project or stream granularity Unfortunately, the SQUID policies were not changed to be more granular than a UCM project

 This could lead to problems if project managers want finegrained control over automatic state transitions

165

IBM Software Group

State Types and Default Actions

There are four state types included in the AMStateTypes package

Postpone

Postpone

Waiting

Assign

Ready

Open

Active

Postpone

Submitted

Duplicate, Close

Postponed

Duplicate

Assigned Close

Opened Resolve Reject, Re-Open

Duplicate, Validate

All user-defined states must be mapped to one of these state types in order to UCMenable the record type.

Complete Resolved Closed Duplicate

UCM-enablement also requires that a minimal set of default actions exist between states mapped to these types

166

IBM Software Group

SQUID Policies and Stream Hierarchy Integration

Currently, SQUID policies can only be defined at the project. It would be preferable to define SQUID policies on streams.

BL1

Core_Team BL1 CORE_BL1 deliverA

BL2

Jim_Core_Dev

Jill_Core_dev

BL1

BL1

Activity A

Activity B

deliverB

Activity C

“WorkOn” Activity C

CORE_BL2

deliver C

No transition (on Activity C) occurs here

Activity C

Waiting

Integ Act

Ready

Active

Complete 167

IBM Software Group

SQUID Policies and Stream Hierarchy  Enabling SQUID policies at the stream granularity may only be one part of a complete solution  One can imagine introducing one or more additional state types as well  Another key part of a more complete and flexible solution would be for the integration to understand and track the “contributors” relationship within ClearQuest Some clever hook and/or trigger writing can get you part way there today, however this is something that would best be solved internally within the products and the integration.

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

IBM Software Group

Mystery #6: Want to track contributors within CQ  For some stakeholders, tracking changes can be just as important as migrating changes  Because UCM deliver operations always create new activities, tracking changes through deliver operations often involves understanding a change’s contributors Tracking deliveries across projects Tracking changes through more complex stream hierarchies within projects

 This relationship is visible/navigable from CC in many places The compare baselines (diffbl) operation always tracks through contributors Users can also use “show contributors” (lsact –contrib) for any activity

 It would be nice if this relationship was navigable from within CQ Changes were added in v2003 to make this relationship visible from ClearQuest, but it is not navigable (using CQ record links).

169

IBM Software Group

Display Contributors from CQ Record

170

IBM Software Group

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

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

171

IBM Software Group

Custom Contributors Solution

172

IBM Software Group

Mystery #7: Using CQ-enabled UCM over a WAN  The relative performance of native CC clients (and some CQ clients) over a WAN sucks!

 This is a well-known and undisputed fact…

 Web clients are absolutely no help whatsoever  Neither CCweb nor CQweb (ASP or java) were engineered to support SQUID use cases

 Citrix/WTS can be a viable workaround for individual remote users, but these probably can’t support large teams  MultiSite could still be the best solution for geographically distributed “teams”

 Both CC/MS and CQ/MS are required in order to make this work  The combined CC and CQ MultiSite solution can be cost prohibitive for customers to both buy and support

 CCRC may potentially be another solution to the SQUID WAN issue (but not necessarily in v2003 SR4)

CCRC will support some (but not all) SQUID use cases In v2003 SR4, CCRC is not a sliver bullet for all SQUID customers with remote access needs. MultiSite may still be the better solution for many customers. 173

IBM Software Group

SQUID Client Support: CQ-Initiated Use Cases Native CQ

Native CQ CQ Eclipse

CQ Eclipse

CQ 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

174

IBM Software Group

SQUID Client Support: CC-Initiated Use Cases Native CC

Native CC CC Eclipse CC Eclipse CC Web

CCRC

.NET

Windows

Unix

Windows

Unix

CC checkout/in dropdown list

yes

yes

yes

yes

yes

yes

yes

CC checkout/in “Browse” button

yes

no

yes

no

no

no

yes

CC checkout/in “New” button

yes

yes*

yes

yes

no

no

yes

Display CQ form as property sheet

yes

yes

yes

yes

no

no

yes

CQ actions from property sheet (CQ form)

yes

yes

yes

yes

no

no

yes

Check before CC delivery hook

yes

yes

yes

yes

no

yes

yes

Do CQ action after delivery hook

yes

yes

yes

yes

no

yes

yes

Perform transition after delivery

yes

yes

yes

yes*

no

yes*

yes

Do CQ action before chact (finish)

yes

yes

yes

yes

no

yes

yes

Do CQ action after chact (finish)

yes

yes

yes

yes

no

yes

yes

Perform transition after chact (finish)

yes

yes

yes

yes*

no

yes*

yes

UCM project creation

yes

yes

no

no

no

no

yes*

Changing CQ policies from CC

yes

yes

no

no

no

no

yes*

175

IBM Software Group

Mystery #8: The SQUID “WorkOn” Action Distilled  There are actually two different flavors of this action Explicit (CQ-initiated) WorkOn from CQ pulldown Action list Implicit (CC-initiated) WorkOn from CC checkout when a CQ record is being associated with a CC change for the first time

 Both flavors perform the same actions Creates a new UCM activity in the specified project/stream and “binds” the activity to the CQ record Fills in the UCM project/stream/view fields in the CQ record Transitions the CQ record from a “ready” state-type to an “active” state-type by taking the default action defined by the record type’s state machine Optionally runs the CQ policy hook (if the UCM policy is set)

• •

By default this hook does a validation of the user’s identity However, this hook can be further modified by users to do other sorts of validations before allowing the association to occur 176

IBM Software Group

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

177

IBM Software Group

More CC Context Available  Note that the past several ClearCase releases and service releases have made more CC context available from within the SQUID hook environment (which could be handy for further customization)  More ClearCase information is actually passed to the hook itself  Stream where a change request is being worked on  Stream/View where a change request is being delivered to  Project/Stream Information where a change request is being modified

 More API support (both CAL and CtCmd) is also available to retrieve information from CC from within VB and Perl hook scripts  WorkOn Hook Validation Examples:  Validate that the user working on the activity is the assigned CQ user  Validate that the activity is not already in a completed state  Validate that user is not working directly on an integration stream

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

IBM Software Group

SQUID Other Topics

Change Flow Intro Break

Composite Baselines

X

e r e h e r a u o Y 179

IBM Software Group

UCM Mysteries – Case #4

Kitc hen Sink

K

I

T

180

IBM Software Group

Misc. Mystery #1: Long Pathnames on Windows  Windows enforces a MAXPATH value of 260 characters  This can be a problem in and of itself even when ClearCase is not involved Deeply nested directory depth can be a problem in Windows – and there isn’t much you can do about it except to avoid it.

 ClearCase can complicate this problem due to the way in which it creates version-extended pathnames E.g. \vob\subdir\element.suf@@\branchname\nestedbranchname\versionid Even if a ClearCase user doesn’t reference versions directly in this manner, many ClearCase operations will (e.g. findmerge, deliver, rebase, etc…) This will cause ClearCase operations to fail on Windows if pathnames are over 260 characters in length

181

IBM Software Group

Solutions: Long Pathnames on Windows  If using v2002 or earlier… In a mixed Windows/Unix shop, you can perform the offending operation on Unix (if possible) to avoid the problem altogether Manually shorten directory and/or branch names

•

Be careful when doing this in a UCM environment due to the way that UCM streams reference branches

If possible, adopt a technique that does not encourage “cascading” branches/streams atop one another

 If using v2003 V2003 GA has “fixed” this problem in the ClearCase core, therefore if an operation fails from the Windows GUI, it can be worked around by running the same operation from the CLI V2003 SR3 actually fixes this problem from the Windows GUIs as well as the CLI.

182

IBM Software Group

REL1 Integration

BETA

REL 1

“Cascading” Follow-on Projects REL2 Integration

REL2 BL1 REL2 BL2

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_Int egration\Ralph_RELn_Dev\3

BETA

… RELn Integration

REL3 Integration

REL2

REL3 BL1

RELn BL1

… 183

IBM Software Group

Creating “Follow-On” Projects is Easy, But… There may be better ways to put this feature to use

184

IBM Software Group Mainline

Alternative: Using a “Mainline” Project The version-extended pathname for a version in a developer’s stream in the RELn project now looks like this:

MN_1 REL1 Integration MN_1 REL1 BL1

foo.java@@\Mainline\RELn_Integration\ Ralph_RELn_Dev\3

BETA

MN_2

REL1 REL2 Integration

(this is some 47+ characters less)

MN_3

MN_3 REL2 BL1 MN_4

MN_5

BETA

REL3 Integration MN_5

REL2

All projects have foundations from BLs in Mainline project

REL3 BL1

185

IBM Software Group

And Now a Word From Our Sponsor…  The UCM graphical user interfaces are brought to you by… Camel brand cigarettes

 Specifically,

 Camel NON-FILTER!

186

IBM Software Group

Misc. Mystery #2: GUI Usability and Filtering  Currently, UCM GUIs don’t offer enough filtering options  This can lead to usability problems in larger environments

187

IBM Software Group

GUI Filtering Workarounds – Not Ideal  There is some filtering available today  Project Explorer allows filtering by PVOB  In some baseline selection GUIs, it is possible to filter by stream  The vtree and component tree browsers also offer some filtering parameters

 These are helpful, but not nearly sufficient  Some customers have found it useful to employ the ClearCase lock/obsolete command in order to filter uninteresting objects from GUI displays  Many GUIs will not display objects that are locked as obsolete  This can reduce clutter, but can also introduce undesired side-effects

 Ideally, the product would offer more filtering parameters in all of its GUIs such that customers can tailor their environment to their needs

188

IBM Software Group

Future Enhancements  Better filtering…

 Filtering to be available in more UCM object browsers  Include support for “shortcuts” in UCM Project Explorer

The UCM development team is working on some of these types of GUI enhancements for the future 189

IBM Software Group

Misc. Mystery #3: Abstract Access Controls  UCM is an abstraction built atop ClearCase  Irony: UCM doesn’t support any abstract (e.g. role-based) access controls

 UCM also doesn’t do a great job at enforcing any default behaviors at the group level  Even though all UCM objects have explicit user and group ownership

 These factors make it difficult to create access controls at the right level of granularity (without having to resort to trigger-writing and/or wrappers)  E.g. Many customers have the notion of an integrator role for creating and recommending baselines in an integration stream  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. 190

IBM Software Group

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

 Each has its advantages and disadvantages 191

IBM Software Group

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

 CoP is working on harvesting solutions that have already been implemented in the field

This is NOT an area of focus for any future product releases, so homegrown solutions will continue to be the norm. 192

IBM Software Group

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

193

IBM Software Group

Congratulations!

UCM Detective

You’ve survived this double-length session… 194

IBM Software Group

Have an Unsolved UCM Mystery on Your Hands?

 Round up the “usual suspects” Kent Seith – UCM Product Manager Tom Milligan - Tech Marketing Dweeb (CC) Jim Tykal – Tech Marketing Dweeb (CQ)

 Call the “CoPs” Dave Bellagio – Community of Practice lead Bryan Miller – Community of Practice lead

195

IBM Software Group

1

2

3

4

5

7’

7’

6’

6’

5’

5’

4’

4’

3’

3’

2’

2’

196

®

®

IBM Software Group

Solving UCM Mysteries The End Bryan Miller Ralph Capasso Maneesh Mehra

[email protected] [email protected] [email protected]

© 2005 IBM Corporation 197