Working On a Team

The development cycle presented so far is a fairly simple one in which everyone in an organization contributes to the same development project. But a software development cycle often involves several concurrent development projects. For example:

You may want to experiment with some changes to the graphic user interface as a result of feedback from usability testing, but are not yet sure whether to include your changes in official builds.

Another team may try to optimize the database schema without upsetting the current one.

Another group may need to get a head start on a feature for the next release of the product.

This chapter describes the functions that Rational ClearCase provides to support parallel development. Parallel development is a style of working in which teams use the same set of source files for different, concurrent development projects:

Version trees

Working on branches

Merging

Sharing control of a branch in an environment by using Rational ClearCase MultiSite

(You do not need to read the section about sharing control of a branch with developers at other sites unless your project manager or MultiSite administrator directs you.)

The Version Tree

Each time you revise and check in an element, ClearCase creates a new version of the element in the VOB. This linear progression is illustrated by Figure 39.

ClearCase can organize the different versions of an element in a VOB into a version tree. Like any tree, a version tree has branches. Each branch represents an independent line of development. Changes on one branch do not affect other branches unless you merge. In Figure 40, main, pat_usability, and db_optimize are branches being used to develop different releases of the file element prog.c concurrently.

Under the Hood: The Initial Version on a Subbranch

When you create a subbranch for an element, which is any branch below the main branch, the initial version contains the same data as the version from which you start the branch (Figure 41). (The initial version on the main branch contains no data. For more information, see Excluding Elements from Loading.)

Working on Branches

The policies of your organization may dictate that each development project use its own branch to isolate its changes from other development projects. To adhere to this policy, each member of a project team uses a view whose config spec specifies the following information:

The versions to select in the specific branch of the development project. As Figure 42 illustrates, some or all source files for the project have at least one version on the specified branch. If an element does not have a version on the specified branch, other rules in the config spec select a version of the element. In Figure 42, because lib.c does not have a version on the pat_usability branch, the view selects the version on the main branch.

A special make branch rule. When this view checks out a version, the make-branch rule creates the branch of the development project (if it does not already exist).

For example, each member of the project team that is optimizing the database schema uses a view that selects versions on the db_optimize branch and creates new versions on that branch.

For more information about branches, see Managing Software Projects and the mkbranch reference page in the Command Reference.

The Version-Extended Path

ClearCase commands and documentation use a notation to specify a version of an element on a branch. For example, util.h@@/main/2 specifies version 2 of util.h on the main branch; util.h@@/main/r1_bugs/bug404/1 specifies version 1 of util.h on the bug404 subbranch below the r1_bugs subbranch, which is below the main branch (Figure 43).

From a command-line interface, you can use version-extended paths to access versions other than the ones currently selected by your view. To view the contents of a version that is not currently in a snapshot view, you must use the cleartool get command in addition to version-extended paths.

For information about the syntax for version-extended paths, see the pathnames_ccase reference page in the Command Reference.

Merging

In a parallel development environment, the opposite of branching is merging. In the simplest scenario, merging incorporates changes on a subbranch into the main branch. However, you can merge work from any branch to any other branch. ClearCase includes automated merge facilities for handling almost any scenario.

One of the most powerful of ClearCase features is source control of directories. Each version of a directory element catalogs a set of file elements, directory elements, and VOB symbolic links. In a parallel development environment, directory-level changes may occur as frequently as file-level changes. All the merge scenarios discussed in this chapter apply to both directory and file elements.

Merging all changes made on a single subbranch (see Scenario: Merging All Changes Made on a Subbranch)

Merging selectively from a single subbranch (see Scenario: Selective Merge from a Subbranch)

Removing the contributions of some versions on a single subbranch (see Scenario: Removing the Contributions of Some Versions)

Recording merges that occur outside ClearCase (see Recording Merges That Occur Outside ClearCase)

ClearCase also supports merging work from many branches to a single branch; this is typically a project manager’s or integrator’s task (see Managing Software Projects).

Under the Hood: How ClearCase Merges Files and Directories

A merge combines the contents of two or more files or directories into a new file or directory. The merge algorithm uses the following files during a merge (Figure 44):

Contributors, which are typically one version from each branch you are merging. (You can merge up to 15 contributors.) You specify which versions are contributors.

The base contributor, which is typically the closest common ancestor of the contributors. (For selective merges, subtractive merges, and merges in an environment with complex branch structures, the base contributor may not be the closest common ancestor.) If all the contributors are versions of the same element, ClearCase determines which contributor is the base contributor (but you can specify a different one). For more information about determining a base contributor, see Determination of the Base Contributor.

The target contributor, which is typically the latest version on the branch that will contain the results of the merge. You determine which contributor is the target contributor.

The merge output file, which contains the results of the merge and is usually checked in as a successor to the target contributor. By default, the merge output file is the checked-out version of the target contributor, but you can choose a different file to contain the merge output.

It identifies the base contributor.

It compares each contributor against the base contributor (Figure 45).

It copies any line that is unchanged between the base contributor and any other contributor to the merge output file.

For any line that has changed between the base contributor and one other contributor, ClearCase accepts the change in the contributor; depending on how you started the merge operation, ClearCase may copy the change to the merge output file. However, you can disable the automated merge capability for any given merge operation. If you disable this capability, you must approve each change to the merge output file.

For any line that has changed between the base contributor and more than one other contributor, ClearCase requires that you resolve the conflicting difference.

File Merge Algorithm

A merge is a straightforward extension of a file comparison. Instead of displaying the differences, Diff Merge analyzes them (sometimes with your help) and copies sections of text to the output file:

Sections in which there are no differences among the contributors are copied to the output file.

When one contributor differs from the base contributor, Diff Merge accepts the change and copies the modified section of the contributor to the output file:

------------[changed 3-4]----\|--------[changed to 3-4 file 2]--- now is the thyme \| now is the time for all good men \| for all good people -\|- *** Automatic: Applying CHANGE from file 2 [lines 3-4] ============

------------[changed 3-4]----|--------[changed to 3-4 file 2]---
now is the thyme                     | now is the time
for all good men                     | for all good people
                                    -|-
*** Automatic: Applying CHANGE from file 2 [lines 3-4]
============

(You can turn off automatic acceptance of this kind of change.)

When two or more contributors differ from the base contributor, Diff Merge detects the conflict, and prompts you to resolve it. It displays all contributor differences and allows you to accept or reject each one.

[changed 10] \| [changed to 10 file 2]--- cent \| sent -\|- [changed 10] \| [changed to 10 file 3]--- cent \| scent \|- Do you want the CHANGE made in file 2? [yes] no Do you want the CHANGE made in file 3? [yes] yes Applying CHANGE from file 3 [line 10] ============

               [changed 10]        |          [changed to 10 file 2]---
cent                               | sent
                                  -|-
               [changed 10]        |          [changed to 10 file 3]---
cent                               | scent
                                   |-
Do you want the CHANGE made in file 2? [yes] no
Do you want the CHANGE made in file 3? [yes] yes
Applying CHANGE from file 3 [line 10]
============

Be sure to verify that the changes you accept produce consistent merged output. For example, after performing a merge involving file util.h, you can compare files util.h.contrib (which contains its previous contents) and the new util.h (which contains the merge output).

Determination of the Base Contributor

If all the contributors are versions of the same element, Diff Merge determines the base contributor automatically. It examines the version tree of the element, which includes all the merge arrows created by previous merge operations. This examination reveals the relationships among versions from the standpoint of their contents (which versions contributed their data to this version?), rather than their creation order (which versions were created before this version?). Diff Merge selects as the base contributor the closest common ancestor in this enhanced version tree.

Figure 46 illustrates a common case of merging. If no merges have been performed in the element, the actual common ancestor (5) of the contributors (test/4 and windows/1) in the version tree is selected to be the base contributor.

If the contributors are not all versions of the same element, there is no common ancestor (or other base contributor). In this case, ClearCase turns off automated merging, and you must resolve all discrepancies among the contributors.

Recording of Merge Arrows

Under the following conditions, the merge is recorded by creating one or more merge arrows (hyperlinks of type Merge):

All contributor files must be versions of the same file element.

One of the contributors must be a checked-out version, and you must specify this version as the target to be overwritten with the merge output (the –to option in the merge command). (Alternatively, you can optionally create merge arrows without performing a merge; in this case, you do not need to check out any of the contributors.)

You must not perform the merge but suppress creation of merge arrows.

You must not use any of these options: selective merge, subtractive merge, or base contributor specification (the –insert, –delete, and –base options in the merge command).

Diff Merge draws an arrow from each contributor version (except the base contributor) to the target version. You can see merge arrows with the Version Tree Browser.

Locating Versions with Merge Hyperlinks

The find and lsvtree –merge commands can locate versions with Merge hyperlinks. The describe command lists all of the hyperlinks of a version, including merge arrows:

Directory Merge Algorithm

Each version of a ClearCase directory element contains the names of certain file elements, directory elements, and VOB symbolic links. Diff Merge can process two or more versions of the same directory element, producing a directory version that reflects the contents of all contributors. The algorithm is similar to that for a file merge. Diff Merge prompts for user interaction only when two or more of the contributors are in conflict.

One of the directory versions—the merge target—must be checked out. (Typically, it is the version in your view.) Diff Merge updates the checked-out directory by adding, removing, and changing names of elements and links.

Note: A directory merge does not leave behind a .contrib file, with the pre-merge contents of the target version.

Merging Directories

Ensure that all contributor versions of the directory are checked in.

Check out the target version of the directory.

Perform the directory merge immediately, without making any other changes to the checked-out version.

If you follow this procedure, it easier to determine exactly what the merge accomplished. Enter a diff –predecessor command on the checked-out version, which has just been updated by merge.

Using ln and rmname in Diff Merge

ClearCase uses VOB hard links to implement directory merges. You can use the ln and rmname commands to perform full or partial merges manually. See the ln and rmname reference pages in the Command Reference.

Scenario: Merging All Changes Made on a Subbranch

Merging all changes made on a subbranch is the simplest and most common scenario (Figure 47).

Bug fixes for an element named opt.c are being made on branch r1_fix, which was created at the baseline version RLS1.0 (/main/4). Now, all the changes made on the subbranch are to be incorporated into main, where a few new versions have been created in the meantime.

Task Overview

Access your dynamic view (see In a Dynamic View) or snapshot view (see In a Snapshot View).

The view must select the target version, which, in Figure 47, is opt.c@@/main/8.

If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in. To make it easier to find this checkpoint, consider labeling the version.

Use the Merge Manager or cleartool findmerge –merge –gmerge to find elements with versions on a specific subbranch and automatically merge any nonconflicting differences. For example, in Figure 47, you find elements with versions on the r1_fix subbranch. To start the Merge Manager, enter the following command:

clearmrgman

In your project, several elements might have versions on the r1_fix branch. With the Merge Manager, you can choose for which elements you merge changes from one branch to another.

Use Diff Merge to resolve any conflicting differences between merge contributors.

Test the merge results in the view you set in Step 1. Then check in the target version (which contains the results of the merge).

Getting More Information

For detailed information about completing this task, see the findmerge reference page in the Command Reference or ClearCase Help. For information about starting Help, see To Access Online Information.

Scenario: Selective Merge from a Subbranch

In the selective merge scenario, the project manager wants to incorporate into new development several lines of code that were added in version /main/r1_fix/4 (Figure 48).

It is critical that you merge only the lines of code as written in this version: it was used and verified to fix a specific bug that prevents further development on the new project.

Selective merges can be tricky: versions you exclude as contributors to the merge may contain needed revisions. For example, if the function you added in /main/r1_fix/4 relies on a variable definition that was added in /main/r1_fix/2, you must include version 2 in the merge.

Merging a Range of Versions

You can also specify a single range of consecutive versions to contribute to the merge. For example, if you need the variable definitions added in /main/r1_fix/2 as well as the code added in /main/r1_fix/4, you can include versions 2 through 4 in the merge.

Task Overview

Merging selective versions from the r1_fix branch involves the following tasks:

Access your dynamic view (see In a Dynamic View) or snapshot view (see In a Snapshot View).

The view must select the target version, which in Figure 48 is opt.c@@/main/8.

If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in.

To determine which versions contain changes that you want to merge to the target version, use the Version Tree Browser and the History Browser. In a snapshot view, use the cleartool get command to see the contents of versions not loaded into your view. (For information about opening a version not currently in your view, see To Compare with a Version in a Dynamic View or Accessing Elements Not Loaded into a Snapshot View.)

To start the merge, check out the target version, and then issue the cleartool merge command with the –insert –graphical arguments. (You cannot start a selective merge from Diff Merge.)

For example, the following commands merge only the changes in version 4 on the r1_fix branch:

cleartool checkout opt.c
cleartool merge –graphical –to opt.c –insert –version /main/r1_fix/4

These commands merge only the changes in versions 2 through 4 on the r1_fix branch:

cleartool checkout opt.c
cleartool merge –graphical –to opt.c –insert –version /main/r1_fix/2 /main/r1_fix/4

In Diff Merge, complete the merge. Then save the results and exit. For information about using Diff Merge, see the Help.

Test the merge results in the view you set in Step 1. Then check in the target version.

Note: In a selective merge, ClearCase does not create a merge arrow. A merge arrow indicates that all the data of a version has been merged, not parts of it.

Getting More Information

For detailed information about completing this task, see the merge and version_selector reference pages in the Command Reference or see Help. For information about starting Help, see To Access Online Information.

Scenario: Removing the Contributions of Some Versions

The project manager has decided that a new feature, implemented in versions 14 through 16 on the main branch, will not be included in the product. You must perform a subtractive merge to remove the changes made in those versions (Figure 49).

Task Overview

A subtractive merge is the opposite of a selective merge: it removes from the checked-out version the changes made in one or more of its predecessors. Performing a subtractive merge involves the following tasks:

Access your dynamic view (see In a Dynamic View) or snapshot view (see In a Snapshot View).

The view must select the branch from which you want to remove revisions.

If the target version is checked out to your view for other revisions, create a pre-merge checkpoint by checking it in. In Figure 49, the target version is opt.c@@/main/18.

To determine which versions contain changes you want to remove, use the Version Tree Browser and the History Browser. From a snapshot view, use the cleartool get command to see the contents of versions not loaded into your view. (For information about opening a version not currently in your view, see To Compare with a Version in a Dynamic View or Accessing Elements Not Loaded into a Snapshot View.)

To perform the merge, check out the target version, and then use the cleartool merge command with the –delete –graphical arguments. (You cannot start a subtractive merge from Diff Merge.)

For example, the following commands remove revisions to versions 14 through 16 on the main branch:

cleartool checkout opt.c
cleartool merge –graphical –to opt.c –delete –version /main/14 /main/16

In Diff Merge, complete the merge. Then save the results and exit. For information about using Diff Merge, see the Help.

Test the merge results in your view. Then check in the target version (which contains the results of the merge).

Note: In a subtractive merge, ClearCase does not create a merge arrow. A merge arrow indicates that data has been merged, not removed.

Getting More Information

Recording Merges That Occur Outside ClearCase

You can merge versions of an element manually or with any available analysis and editing tools. To update the version tree of an element with a merge that occurs outside ClearCase, do the following:

Check out the target version.

Perform the merge with your own tools.

Check in the target version.

Then record the merge by drawing a merge arrow from the contributors to the new version that contains the result of the merge.

After you draw the merge arrow, your merge is indistinguishable from one performed with ClearCase tools.

For example, use the following commands to merge a version of nextwhat.c on the enhance branch to the branch currently selected by your view:

cleartool checkout nextwhat.c
Checkout comments for "nextwhat.c":
merge enhance branch
.
Checked out "nextwhat.c" from version "/main/1".

<use your own tools to merge data into checked-out version>

cleartool merge –to nextwhat.c –ndata –version .../enhance/LATEST
Recorded merge of "nextwhat.c".

The –ndata option suppresses the merge but creates merge arrows as if ClearCase had merged the versions.

Getting More Information

Sharing Control of a Branch with Developers at Other Sites

Note: This section describes how to request control of a branch from another development site. Do not read this section unless your project manager or MultiSite administrator directs you to.

If your company uses MultiSite to distribute development among multiple geographical sites, you may share source files with developers at other sites. Each site has its own replica of the VOB, and developers work in their site-specific replica (known as the current replica). Each replica controls (masters) a particular branch of an element, and only developers at the site of that replica can work on that branch. In this scenario, MultiSite branch mastership does not affect you, and you can do your work as usual.

However, sometimes elements cannot have multiple branches. For example, some file types cannot be merged, so development must occur on a single branch. In this scenario, all developers must work on a single branch (usually, the main branch). MultiSite allows only one replica to master a branch at any given time. Therefore, if a developer at another site needs to work on the element, she must request mastership of the branch.

Note: The developer can also request mastership of branch types. For more information, see the Administrator’s Guide for Rational ClearCase MultiSite.

For example, the file doc_info.doc cannot be merged because it is a file type for which you do not have a type manager, but developers at different sites need to make changes to it. If the branch is mastered by your current replica, you can check out the file. If the branch is mastered by another replica, you cannot check out the file. If you try to check out the file, ClearCase presents an error message:

cleartool checkout –c "command changes" doc_info.doc 
cleartool: Error: Cannot checkout branch "/main".
The branch is mastered by replica "sanfran_hub".
Current replica is "boston_hub".
cleartool: Error: Unable to check out "doc_info.doc".

For you to check out the file reserved or to check in the file after a nonmastered checkout, your current replica must master the branch. You can request mastership with a cleartool command.

If you have permission to request mastership from the master replica of the branch, if mastership requests are enabled, and if there are no blocking conditions, then the mastership change is made at the master replica, and a MultiSite update packet that contains the change is sent to your current replica. When your current replica imports the packet, it receives mastership of the branch and you can check out the file.

Note: Authorizing developers to request mastership and enabling mastership requests at a replica are tasks performed by the MultiSite administrator. For more information, see the Administrator’s Guide for Rational ClearCase MultiSite.

When you use mastership requests to transfer control of a branch, you can use either of two methods to do your work:

Request mastership of the branch and wait for mastership to be transferred to your current replica; then perform a reserved checkout. You must use this method if you cannot or do not want to merge versions of the element.

Request mastership of the branch and use a nonmastered checkout to check out the branch immediately. You may have to perform a merge before you can check in your work.

To Request Mastership of a Branch and Wait for the Transfer

At a command prompt, enter a cleartool reqmaster command for the branch you need to check out.

cleartool reqmaster –c "add info re new operating systems" 
read_me_first.doc@@/main 
read_me_first.doc@@/main: Change of mastership at sibling replica 
"sanfran_hub" was successful.
Mastership is in transit to the new master replica.

Wait for mastership to be transferred to your current replica. To list the master replica of a branch, use describe:

cleartool describe read_me_first.doc@@/main 
branch "read_me_first.doc@@/main"
  created 15-May-99.13:32:05 by sg.user
  branch type: main
  master replica: boston_hub@/doc
...

In this example, your current replica is boston_hub in the VOB family /doc. The output of the describe command shows that boston_hub is the master replica of the branch, which means that you can check out the branch as reserved.

Perform a reserved checkout, edit the file, and check in your work.

To Check Out the Branch Before Mastership Is Transferred

If you can merge versions of the element you need to check out, you can work on the file while you wait for mastership to be transferred to your replica.

Enter a reqmaster command for the branch you need to check out.

cleartool reqmaster –c "fix bug #28386" prog.c@@/main/integ 
prog.c@@/main/integ: Change of mastership at sibling replica 
"lib_lex" was successful.
Mastership is in transit to the new master replica.

Use cleartool checkout –unreserved –nmaster to perform a nonmastered checkout.

cleartool checkout –c "fix bug #28386" –unreserved –nmaster 
prog.c@@/main/integ

Make changes to the element.

Wait for mastership to be transferred to your current replica. To list the master replica of a branch, use describe:

cleartool describe /vobs/lib/prog.c@@/main 
branch "/vobs/lib/prog.c@@/main"
  created 15-May-99.13:32:05 by nlg.user
  branch type: main
  master replica: lib_london@/vobs/lib
...

Check in the element. If the checkin succeeds, you are finished.

cleartool checkin –nc prog.c 
Checked in "prog.c" version "/main/65".

If the checkin fails because you have to perform a merge, proceed to Step 6:

cleartool checkin –nc prog.c 
cleartool: Error: The most recent version on branch "/main" is not 
the predecessor of this version.
cleartool: Error: Unable to check in "prog.c".

Merge from the latest version on the branch to your checked-out version.

cleartool merge –to prog.c –version /main/LATEST 
(if necessary, you are prompted to resolve conflicts) 
Moved contributor "prog.c" to "prog.c.contrib".
Output of merge is in "prog.c".
Recorded merge of "prog.c".

Check in the element.

Troubleshooting

If the request for mastership fails because there are checkouts on the branch at the master replica, try your request again later or ask the other developer to check in the file or directory and then try again. If you receive other errors, contact your project manager or MultiSite administrator.