5.4 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. You do not need to 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 that replica's site 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:

• In the graphical interface:

Branch '\main' is not mastered by the current replica. Master replica of branch is 'raleigh'. Only unreserved, nonmastered checkout is allowed at the current replica.

• On the command line:

cleartool: Error: Cannot checkout branch 'main'.
The branch is mastered by replica 'raleigh'.
Current replica is 'lexington'.
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 through the graphical interface or 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 check out the branch immediately, using a nonmastered checkout. You may have to perform a merge before you can check in your work.

The following sections describe both methods.

To Request Mastership of a Branch and Wait for the Transfer

From the command line:

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

2. 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: doc_lex@\doc
...

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

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

For detailed information about requesting mastership from the graphical interface, see ClearCase online help:

1. From ClearCase Explorer, click Help > Help Topics.

2. In the ClearCase Help window, click Help Topics.

3. On the Contents tab of the Help Contents window, select Developing Software with Base ClearCase > Requesting mastership of a branch > To request mastership of a branch.

You can request mastership from the Find Checkouts window, the Merge Manager, or the Version Tree Browser.

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.

To use this method from the graphical interface:

1. In ClearCase Explorer, right-click the element you want to check out and click Check Out on the shortcut menu.

2. In the Check Out dialog box, select the Unreserved if already reserved check box.

3. If the Confirm Version to Check Out dialog box is open, select the Request mastership of the branch check box and click Yes.

4. In the Request Mastership dialog box, click Request Mastership.

5. Make changes to the element.

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

1. Right-click the element and click Version Tree on the shortcut menu.

2. In the Version Tree, right-click the branch icon and click Properties on the shortcut menu.

3. Click the Mastership tab.

7. Check in the element. If the checkin succeeds, you're finished. If the checkin fails because you have to perform a merge, proceed to Step #8.

8. Use the Merge Manager to merge from the latest version on the branch to your checked-out version.

9. Check in the file.

To use this method from the command line:

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

cleartool reqmaster -c "fix bug #28386" prog.c@@\main\integ

2. Use cleartool checkout -unreserved -nmaster to perform a nonmastered checkout.

cleartool checkout -c "fix bug #28386" -unreserved -nmaster prog.c@@\main\integ

3. Make changes to the element.

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

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

5. 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".

6. 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".

7. Check in the element.

Requesting Mastership After the Checkout

You can perform a nonmastered checkout, but not request mastership at the time of the checkout. You can request mastership at any time by using the reqmaster command, or by clicking Request Mastership on the shortcut menu for nonmastered checkouts available in Find Checkouts or the Merge Manager.

Setting the Default for Nonmastered Checkouts

You can set the default behavior of the Check Out dialog box so that you always perform a nonmastered checkout if a reserved or unreserved checkout would fail.

1. Click Start > Programs > Rational ClearCase > User Preferences.

2. Click the Operations tab.

3. Select the Unreserved, nonmastered if branch is mastered by another replica check box.

When you check out an element in a replicated VOB, the Check Out dialog box opens with the Unreserved, nonmastered check box selected. When you check out an element in an unreplicated VOB, this setting is ignored.

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.