9.8 Serial Development Scenario

This section describes an example of serial development using requests for mastership.

Planning the Implementation

The company PurpleDoc develops documentation at three sites. There are two VOB families:

• /vobs/doc contains binary files. This VOB has three replicas: boston_hub, tokyo, and sanfran_hub.

The writers working in /vobs/doc use serial development because the files are in binary format. However, a team of writers at the Boston site needs control of a certain set of files at all times.

• /vobs/html contains html files and scripts. This VOB has three replicas: boston_hub, tokyo, and sanfran_hub.

The writers working on HTML files in /vobs/html use site-specific branch types: boston_main, tokyo_main, and sanfran_main. Writers at a particular site cannot use branch types mastered by the other sites.

The tool developers working on scripts use the main branch. Because the scripts can be merged, the developers can use nonmastered checkouts to do their work.

Setting Up Access Controls

The administrators and project managers at the Boston, San Francisco, and Tokyo sites make the following decisions:

• Writers are allowed to request mastership of all branches in /vobs/doc, except for the branches plans.doc@@/main, schedule.doc@@/main, and roadmap.doc@@/main.

• Writers are not allowed to request mastership of any branches of type boston_main, tokyo_main, or sanfran_main in /vobs/html.

• Tool developers are allowed to request mastership of all branches of type main in /vobs/html.

Each administrator completes the following steps on the replica's VOB server host. (This example takes place at the Boston site.)

1. Add writers at other sites to the ACL for /vobs/doc.

1. Place the following lines in the file /tmp/doc_acl:

# Replica boston_hub@/vobs/doc

# Request for Mastership ACL:

User:boston.purpledoc.com/msadm Full

User:tokyo.purpledoc.com/masako Change

User:tokyo.purpledoc.com/sato Change

User:tokyo.purpledoc.com/ito Change

User:sf.purpledoc/jcole Change

User:sf.purpledoc/marni Change

User:sf.purpledoc/david Change




2. Use the file to set the replica's ACL:

multitool reqmaster -acl -set /tmp/doc_acl vob:/vobs/doc




2. Add tool developers at other sites to the ACL for /vobs/html.

1. Place the following lines in the file /tmp/html_acl:

# Replica boston_hub@/vobs/html

# Request for Mastership ACL:

User:boston.purpledoc.com/ccadmin Full

User:tokyo.purpledoc.com/masako Change

User:sf.purpledoc/david Change




2. Use the file to set the replica's ACL:

multitool reqmaster -acl -set /tmp/html_acl vob:/vobs/html




NOTE: After you set the ACL, you can delete the temporary ACL files you created.

3. Deny mastership requests for specific branches and branch types:

multitool reqmaster -deny /vobs/doc/planning/plans.doc@@/main \
/vobs/doc/planning/schedule.doc@@/main /vobs/doc/planning/roadmap.doc@@/main

multitool reqmaster -deny -instances brtype:boston_main@/vobs/html

multitool reqmaster -deny brtype:boston_main@/vobs/html

4. Enable requests for mastership at the replica level.

multitool reqmaster -enable vob:/vobs/doc vob:/vobs/html

Writing Config Specs

In this scenario, the writers use the config specs listed below. Each location has rules for creating site-specific branches in /vobs/html and selecting the latest version on that branch. The /main/LATEST rule is used in all the config specs for development in /vobs/doc and all other VOBs.

Boston

element * CHECKEDOUT
element /vobs/html/scripts/... /main/LATEST
element /vobs/html/files/... /main/boston_main/LATEST
element /vobs/html/files/... /main/LATEST -mkbranch boston_main
element * /main/LATEST

San Francisco

element * CHECKEDOUT
element /vobs/html/scripts/... /main/LATEST
element /vobs/html/files/... /main/sanfran_main/LATEST
element /vobs/html/files/... /main/LATEST -mkbranch sanfran_main
element * /main/LATEST

Tokyo

element * CHECKEDOUT
element /vobs/html/scripts/... /main/LATEST
element /vobs/html/files/... /main/tokyo_main/LATEST
element /vobs/html/files/... /main/LATEST -mkbranch tokyo_main
element * /main/LATEST

Requesting Mastership

The following sections describe how the writers use mastership requests to do their work.

Serial Development of a File That Cannot Be Merged

1. Masako, in Tokyo, tries to check out the file \doc\ref\update.fm, but the checkout fails because the Tokyo replica doesn't master the main branch:

cleartool checkout -c "new command options" \doc\ref\update.fm
cleartool: Error: Unable to perform operation "checkout" in replica "tokyo" of VOB "\doc".
cleartool: Error: Master replica of branch "\main" is "boston_hub".
cleartool: Error: Unable to check out "\doc\ref\update.fm".

2. She requests mastership of branch \doc\ref\update.fm@@\main:

cleartool reqmaster -c "Tokyo needs mastership" \doc\ref\update.fm@@\main

3. Periodically, she retries the checkout or displays properties of the branch to determine whether mastership has been received.

cleartool checkout -c "new command options" \doc\ref\update.fm
cleartool: Error: Unable to perform operation "checkout" in replica "tokyo" of VOB "\doc".
cleartool: Error: Master replica of branch "\main" is "boston_hub".
cleartool: Error: Unable to check out "\doc\ref\update.fm".

After mastership is received at her replica, the describe command shows that her replica masters the branch and her checkout succeeds:

cleartool describe -fmt "%[master]p\n" \doc\ref\update.fm@@\main
tokyo@\doc

cleartool checkout -c "new command options" \doc\ref\update.fm
Checked out "\doc\ref\update.fm" from version "\main\30".

Serial Development of a File That Can Be Merged

1. John, in San Francisco, needs to change an HTML script. He can't check out the file using a reserved checkout because the branch is mastered by the Boston replica:

cleartool checkout -c "option to suppress status msgs" /vobs/html/scripts/conv_fm.pl
cleartool: Error: Unable to perform operation "checkout" in replica "sanfran_hub" of VOB "/vobs/html".
cleartool: Error: Master replica of branch "/main" is "boston_hub".
cleartool: Error: Unable to check out "/vobs/html/scripts/conv_fm.pl".

2. He requests mastership of the branch:

cleartool reqmaster -c "SF: add new option" /vobs/html/scripts/conv_fm.pl@@/main

3. He checks out the file with the -unreserved and -nmaster options and proceeds to edit the file:

cleartool checkout -c "option to suppress status msgs" -unreserved \
-nmaster /vobs/html/scripts/conv_fm.pl
Checked out "/vobs/html/scripts/conf_fm.pl" from version "/main/15".

4. Until mastership is received at the San Francisco replica, he cannot check in his changes:

cleartool checkin -nc conv_fm.pl
cleartool: Error: Unable to perform operation "checkin" in replica "sanfran_hub" of VOB "/vobs/html".
cleartool: Error: Master replica of branch "/main" is "boston_hub".
cleartool: Error: Unable to check in "conv_fm.pl".

5. When mastership is received at the San Francisco replica, he attempts to check in the file, but finds that he must perform a merge:

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

6. He performs the merge, and checks in the file:

cleartool merge -to conv_fm.pl -c "merging from LATEST" -version /main/LATEST
********************************
<<< file 1: /vobs/html/conv_fm.pl@@/main/15
>>> file 2: /vobs/html/conv_fm.pl@@/main/16
>>> file 3: conv_fm.pl
********************************
. . .
Moved contributor "conv_fm.pl" to "conv_fm.pl.contrib".
Output of merge is in "conv_fm.pl".
Recorded merge of "conv_fm.pl".

cleartool checkin -nc conv_fm.pl
Checked in "conv_fm.pl" version "/main/17".