► ► ► Module 7

Integrating Parallel Development

IBM Software Group

Essentials of Rational ClearCase

Module 7: Integrating Parallel Development

Topics
Objectives............................................................................................................ 7-2
Branching............................................................................................................. 7-3
Why Branch? ....................................................................................................... 7-5
Types of Branches: Integration Branches............................................................... 7-6
Viewing Branch Types ........................................................................................ 7-13
Creating Branch Instances Using the Config Spec ................................................ 7-14
Multiple-Level Auto-Branching ........................................................................... 7-15
Merging an Unreserved Checkout....................................................................... 7-19
Selective Merge.................................................................................................. 7-21
Subtractive Merge .............................................................................................. 7-23
Merging Non-ClearCase Files.............................................................................. 7-25

© Copyright IBM Corp. 2003 7-1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Objectives

Objectives
Upon completing this module, you should be able to:
Š Discuss when it is advantageous to branch
Š List common branch types and explain when
you might use them
Š Perform advanced merges
Š Merge and compare non-ClearCase files

7-2 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Branching

Topics
Š Branching
ƒ Branching — review
ƒ Why branch?
ƒ Types of branches
ƒ Instantiating branch types
Š Merging
ƒ Performing special types of merges
• Unreserved checkout
• Selective merge
• Subtractive merge
ƒ Merging and comparing non-ClearCase files

© Copyright IBM Corp. 2003 7-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Branching: Review

Branching: Review
Š Branching is a technique to isolate change and
enable parallel development
Š Branching controls the public and private nature of
work
Š Branch only when you want to make changes
Š Typically, parallel branches are eventually merged
into a resulting product
Š Configuration managers, ClearCase administrators,
or project leads typically define the organization
branching and merging policies

Branching is the ClearCase mechanism that enables parallel development and allows
you to control the public and private nature of development work. Eventually, the
changes made on parallel branches are merged to create a product. In general, the
configuration manager, ClearCase administrator, or project lead makes branching and
merging policies for an organization.
Branches are used for specific tasks — such as fixing defects, prototyping new
functionality, or promoting reliability — and are created only for artifacts that are
changed as part of that task.

7-4 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Why Branch?

Why Branch?
Š When you need project level parallel development of
a common base (ports, spin-offs)
Š When you want to isolate aspects of the product’s
evolution (release area, patch area, development
area)
Š When you work on a long-range task and want to
save and baseline your own work (private branches)
Š When you are working on a new feature and don’t
want to have an impact on other developers
Š When you need to organize your work by location for
use with ClearCase MultiSite
5

In general, you should branch when you need to make changes, but want to isolate
those changes from other development efforts.
List some reasons to branch:
•

© Copyright IBM Corp. 2003 7-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Types of Branches: Integration Branches

Types of Branches: Integration Branches

Š Branches designated for integrating development work
Š Allows you to work on multiple development threads
concurrently
Š Examples include
ƒ /main
ƒ Project branches
ƒ Release branches
ƒ Feature branches

Integration branches are generally designated for integrating development work.

7-6 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Integration Branch Example: Project Branch

Integration Branch Example: Project Branch

Š Branch used for each separate releasable product
Š All development for a
particular project occurs
only on the project branch
Š Can be just /main in
simple environments

The project branch is a common use of an integration branch. Project branches can be
used for each separate releasable product. All development for a particular project
occurs only on that project branch.
In simple environments, it may be sufficient to have a single project branch.
For example, a project needs to port a product to Windows NT, but doesn’t want that
work to be on /main because it might interfere with other development. The project
leader can create a project branch for the Windows NT porting work.

© Copyright IBM Corp. 2003 7-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Integration Branch Example: Release Branch

Integration Branch Example: Release Branch

Š Branch designated for holding official releases of a
product
Š Facilitates tracking changes
among releases
Š Keeps version trees compact

Release branches are designated for official releases of the product. Merging the final
deliverable versions to a release branch allows you to easily diff changes among
releases.

7-8 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Integration Branch Example: Feature Branch

Integration Branch Example: Feature Branch

Š Branch designated for work on a specific feature
Š Facilitates tracking the development of individual
modules and integration of the modules into project
development branches

In some cases, you may want to isolate work on a new feature from the main line of
development. In that case, you can create a feature branch. One or more developers
can work directly on a feature branch. Eventually, the feature branch can be merged
back into the project integration area.

© Copyright IBM Corp. 2003 7-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Types of Branches: Maintenance Branches

Types of Branches: Maintenance Branches

Š Branch to track bug fixes
and integrate them into
project or release
branches
Š Can generate patch
versions
Š Several maintenance
efforts in parallel may
require a maintenance
Integration

10

The most common use for maintenance branches are bug fixes. Bug fix branches can
generate patch versions and may evolve into patch release versions. They can be also
be merged into other release branches. For example, work on r1_bugfix may
eventually need to be merged into the r2_int branch.

7 - 10 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Types of Branches: Developer Branches

Types of Branches: Developer Branches

Š Branch designated for long-range or high-risk
individual development
Š Facilitates tracking the
development of
individual modules and
integration of the
modules into project
and release branches

11

Developer, or private, branches provide an isolated environment where an individual

developer can work. The development branch can then be merged back to the
integration branch.
For long-range work, changes to the integration branch can be merged to the developer
branch. This is called a “rebase” of the developer branch, and allows developers to
keep their view current with work produced by the rest of the team.

© Copyright IBM Corp. 2003 7 - 11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

MultiSite Branches

MultiSite Branches
Š ClearCase MultiSite replicates and synchronizes
VOBs across distant sites
Š Branches support parallel development across sites
Š Branches are ‘mastered’ by individual sites
Š Some integration may
occur at replicated sites
Š One site is usually
responsible for ‘release’
branch

12

When you are using MultiSite, each branch is mastered by one site. Each site must have
its own branch. Each site may modify only branches that it masters.

7 - 12 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Viewing Branch Types

Viewing Branch Types

13

Typically, ClearCase administrators or project leads define branch types. For the most
part, developers create instances of existing branch types.
To see a list of existing branch types, use the Branch Type Browser. You can access the
Branch Type Browser by clicking Admin > Branch type.
CLI Procedure
Usage:
cleartool lstype –kind brtype
Example:
cleartool lstype -kind brtype
20-Jan.17:32 alex branch type "bug_404"
20-Jan.14:00 pat branch type "main"
"Predefined branch type used to represent the main branch of
elements."
20-Jan.17:17 pat branch type "rel2_bugfix"
"branch to isolate bugfix work from the REL2 baseline."

© Copyright IBM Corp. 2003 7 - 13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Creating Branch Instances Using the Config Spec

Creating Branch Instances Using the Config Spec

Š Once a branch type exists, you can create instances
of that branch type
Š Preferred method of instantiating branch types is
using the –mkbranch clause in the config spec
Š The -mkbranch clause can be used to implement
complex branching policies and to ensure consistent
branching of elements

14

The preferred method of creating an instance of a branch on an element is to use the

config spec to automate branch creation. You learned to use the config spec to create
branches earlier in the course. Now, we show how using multiple –mkbranch clauses
in the config spec can implement complex branching schemes.

7 - 14 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Multiple-Level Auto-Branching

Multiple-Level Auto-Branching
Š A config spec can include a “cascade” of
-mkbranch rules:

element * CHECKEDOUT
element * /main/r2_int/pat_r2/LATEST
element * /main/r2_int/LATEST -mkbranch pat_r2
element * R1 -mkbranch r2_int

Š Check out continues to create branches until

version zero on the new pat_r2 branch is created

15

Multiple-level auto-branching uses config spec rules to create a hierarchy of branches

for an element. Imagine a file selected by the label R1. When that file is checked out,
ClearCase fires the –mkbranch clause, creating branch r2_int. Because the element
version tree has changed, ClearCase re-evaluates the config spec rules top-to-bottom,
still trying to complete the checkout. When it matches on the new branch, it fires the
next –mkbranch clause and re-evaluates the config spec. It continues to create
branches until version 0 on a branch is not followed by a –mkbranch clause.
This example is continued on the next slide.

© Copyright IBM Corp. 2003 7 - 15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Multiple-Level Auto-Branching (cont.)

Multiple-Level Auto-Branching (cont.)

Rule 1: element * CHECKEDOUT
Rule 2: element * /main/r2_int/pat_r2/LATEST
Rule 3: element * /main/r2_int/LATEST -mkbranch pat_r2
Rule 4: element * R1 -mkbranch r2_int

util.c before checkout util.c after checkout with

the above config spec

16

In this example, upon checkout of the version with an R1 label:

1. Branch of type r2_int is created at the REL1 version.
2. Rule 3 now selects the new version /main/r2_int/0, so branch of type pat_r2 is
created at that version.
3. Version /main/r2_int/pat_r2/0 is selected by rule 2 and the checkout is
performed.
4. Rule 1 selects the checkout and displays this version in the directory (or loads it
into the snapshot view).
5. Once the new version is checked in, rule 2 selects it.

Rules 3 and 4 in this config spec are not evaluated again for this element; however,
they are used on other elements when they are checked out, ensuring a consistent
branch structure for all elements.

7 - 16 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Multi-Level Auto-Branching: Write Config Specs

Multi-Level Auto-Branching: Write Config Specs

1. 2.

17

© Copyright IBM Corp. 2003 7 - 17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Topics

Topics
Š Branching
ƒ Branching — review
ƒ Why branch?
ƒ Types of branches
ƒ Instantiating branch types

Š Merging
ƒ Performing special types of merges
• Unreserved checkout
• Selective merge
• Subtractive merge
ƒ Merging/comparing non-ClearCase files

18

7 - 18 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Merging an Unreserved Checkout

Merging an Unreserved Checkout

Š You cannot check in an unreserved checkout if there are
successor versions
Š The unreserved checkout must be merged with LATEST
before you can check in

19

Earlier in this course, you learned about unreserved checkouts. If you want to check in
an unreserved checkout, but successor versions have been created since you checked
out, then you must merge your check out with the LATEST version before you can
check in.
ClearCase prompts you to merge changes if there are successor versions.
CLI Procedure
Usage:
cleartool merge { -out output-pname | -to contrib-&-result-pname }
Example:
Merge the latest version on the main branch to the unreserved checkout selected in this
view:
cleartool merge -to new.cpp -version /main/LATEST

© Copyright IBM Corp. 2003 7 - 19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Merging an Unreserved Checkout (cont.)

Merging an Unreserved Checkout (cont.)

There are two checkouts: one

reserved and one unreserved

After Pat checks in her

reserved checkout

After Alex merges Pat’s

changes into his version
and checks in

20

This slide demonstrates the merging process for an unreserved checkout.

Before the merge, there is an unreserved checkout of new.cpp. The predecessor
version of the unreserved checkout is new.cpp @@/main/r2_int/0. However, there is a
successor version, new.cpp@@/main/r2_int/1, which is LATEST . Before the unreserved
checkout can be checked in, it must be merged with new.cpp@@/main/r2_int/1. The
Diff Merge tool merges the unreserved checkout with /main/r2_int/1 leaving an
unreserved checkout. Check in the file to complete the merge. The merged version is
new.cpp@@/main/r2_int/2.

7 - 20 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Selective Merge

Selective Merge
Š Selects changes from
specific versions from a
branch to merge
Š Use the –insert option with
merge command
Š No merge arrow in Version
Tree Browser

21

You can only perform a selective merge from the command line.
CLI Procedure
Example:
cleartool checkout hello.c
cleartool merge -to hello.c -insert
-version /main/branch/4
You can also specify a range of versions. For example, to merge data from version 3
through 5 (inclusive) along the branch:
cleartool merge -to hello.c -insert
-version /main/branch/3 /main/branch/5
The version to be merged to must be checked out prior to issuing the cleartool merge
command.

© Copyright IBM Corp. 2003 7 - 21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Selective Merge: Example

Selective Merge: Example

Scenario: Integrate bug fix changes of /r1_bugfix/3 into /r2 branch

22

In this example, development continues on two branches: a release 2 development

branch (/r2_int) and a release 1 bugfix branch (/r1_bugfix). A bug fix created for release
1 is needed in release 2 right away. In this case, you can perform a selective merge that
merges only the contents of /r1_bugfix/3 back to the /r2_int branch.

Procedure
Before you start the merge you must:
1. Prepare a destination view. Your view must select the target version, LATEST on
the branch that will contain the results of the merge.
2. Check out the target version.
To start the merge:
cleartool merge -to hello.c –insert -version
/main/r1_bugfix/3
Note: selective merges are not indicated by merge arrows in the Version Tree Browser.

7 - 22 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Subtractive Merge

Subtractive Merge
Š Removes changes made in one
or more of its predecessors from
a checked-out version
Š The –delete option indicates the
version or range of versions to
subtract
Š No merge arrow in Version Tree
Browser

23

You can only perform a subtractive merge from the command line.
To subtract a single version, you need only specify the version ID.
CLI Procedure
Example:
cleartool checkout hello.c
cleartool merge -to hello.c -delete -version /main/5 /main/6

© Copyright IBM Corp. 2003 7 - 23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Subtractive Merge: Example

Subtractive Merge: Example

Scenario: The multi-thread algorithm
implemented in element versions 2 and
3 contains a fatal flaw. How do you
back out those changes, but retain
subsequent good changes?

Back out only these changes

24

In this example, development continues along /main.

• Version 1 contains the initial code.
• Versions 2 and 3 implement a new, multi-thread algorithm in the lock-manager
code.
• Version 4 implements a lock-manager performance statistics calculation.
• Versions 5 and 6 fix bugs in the handling of multi-record locks.
A senior engineer reviews the cumulative collection of versions and discovers a fatal
flaw in the multi-thread algorithm. A subtractive merge would allow him to back out of
versions 2 and 3 without losing the unrelated good code from versions 4, 5, and 6.
CLI Procedure
Example:
cleartool> merge -to hello.c -delete -version
\main\r2_int\pat_r2\2 \main\r2_int\pat_r2\3
********************************
<<< file 1: M:\Pat_r2_view\..\hello.c@@\main\r2_int\pat_r2\3
>>> file 2: …\Hardware\src\hello.c@@\main\r2_int\pat_r2\1
>>> file 3: hello.c
********************************
…
*** Automatic: Applying DELETION from file 2 [deleting base
lines 10-11]
Output of merge is in "hello.c.merge".

7 - 24 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Merging Non-ClearCase Files

Merging Non-ClearCase Files

Š Use the ClearCase Diff Merge tool to merge files not
under ClearCase control
Example:
cleartool merge –out newfile.c
/usr/file1.c /usr/file2.c
Š Use the Diff Merge tool to merge non-ClearCase
files with ClearCase elements
Example:
/vobs/Hardware/src% cleartool merge -g
-to util.c /usr/testutil.c

25

You can explicitly specify a base contributor if you want the merge to be automatic
rather than manual.

© Copyright IBM Corp. 2003 7 - 25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Comparing Non-ClearCase Files

Comparing Non-ClearCase Files

Š Use the ClearCase Diff Merge tool to compare files
not under ClearCase control
Example:
cleartool diff -g /usr/file1.c /usr/file2.c

Š Use the Diff Merge tool to compare non-ClearCase

files with ClearCase elements
Example:
/vobs/Hardware/src% cleartool diff -g util.c
/usr/testutil.c

26

7 - 26 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 7 - Integrating Parallel Development

Module Review

Module Review
Š Why might you want to create a branch?
Š How do you know what branch types are available?
Š What is the recommended way to create branch
instances?
Š What do you do if you want to check in an
unreserved checkout, but there are successor
versions?
Š What is a selective merge? Why would you perform
one?
Š What is a subtractive merge? Why would you
perform one?
27

© Copyright IBM Corp. 2003 7 - 27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Module Lab

Module Lab
Š In this lab, you perform the following tasks:
ƒ Use the ClearCase GUI to view branch types
ƒ Perform a selective merge
ƒ Use the command line interface to
• Compare and merge non-ClearCase files
• Perform a subtractive merge

28

7 - 28 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.