1.2 Enabling Independent VOB Development: Mastership

Because changes to the VOB are made independently at multiple replicas, these changes may conflict. This section describes the mechanism that prevents most conflicts, and Conflict Resolution describes the facilities for resolving the unavoidable conflicts.

If the development work done in different replicas were truly independent, the result would be chaos. Suppose version 17 of file project.c is created on the main branch in three replicas at the same time. Which is the real version 17, and what ought to happen to the other two versions?

An exclusive-right-to-modify scheme, called mastership, avoids such conflicts. Certain VOB-database objects are assigned a master replica (or master). The initial master of an object is the replica where the object is created, and mastership can be changed subsequently (see Chapter 8, Managing Mastership). In general, an object can be modified or deleted only at its master replica.

For example, this command fails because it is entered at the boston_hub replica, for a type object mastered by the sanfran_hub replica:

SUSHI> cleartool rename lbtype:SF_V2.0 SANFRAN_V2.0
cleartool: Error: Unable to perform operation "rename type" in replica "boston_hub" of VOB "/vobs/dev".
cleartool:Error:Master replica of label type "SF_V2.0" is "sanfran_hub".
cleartool:Error:Unable to rename type from "SF_V2.0" to "SANFRAN_V2.0".

Replica Mastership

When you create a new replica, its replica object (the VOB database object that records the replica's existence) is mastered by the creating replica. Therefore, you can modify or delete the replica object only at the creating replica.

To facilitate replica maintenance, we recommend that each replica be self-mastering, which means that it is the master of its own replica object. For more information, see Transferring Mastership of a Replica Object.

NOTE: To perform certain procedures on a replica object, you must make the replica self-mastering. This requirement is documented in those procedures.

Branch Mastership

Branch mastership is the scheme that supports independent development work at different sites. By default, every branch type defined in a VOB (including the main branch type) is mastered by one replica in a VOB family. By default, branches can be created and modified only at the replica that masters the branch type. Checking out a version is considered a branch modification. (The exception to the creation rule is the creation of the main branch; for more information, see Creation of the main Branch of an Element.)

NOTE: Remember that a branch is an instance of a branch type. For example, main is a branch type, and acc.c@@/main and resource.h@@\main are branches.

The branch mastership strategy works with the standard ClearCase strategy of using branches to isolate changes for particular development tasks. (For example, fixing a defect may require changes to 5 elements, where each change is made on a branch named v1.0_bugfix.) With MultiSite, work on various tasks can be done at different sites, each using its own branch. The work on different branches can be propagated among sites, and then merged, as often as required by an organization's development strategy. Because the branches of an element are independent, changes made at different sites do not conflict.

Figure 1 illustrates branch mastership strategy: each replica masters a branch type and can create versions only on the branch of that type.

Figure 1 Branch Mastership

Branch mastership is implemented at both the branch type level and the branch level:

• By default, the replica in which a branch type is created masters the branch type and all instances of that branch type. For example, the sanfran_hub replica masters the branch type object named v1.0_integration and owns the right to modify v1.0_integration branches in all of the elements in the VOB.

• An administrator or developer can transfer the mastership of an individual branch (an instance of a branch type) to another replica. This feature enables serial development. For example, if a developer at the Boston site needs to work on the v1.0_integration branch for the element main.c, the San Francisco administrator can transfer mastership of the branch main.c@@/main/v1.0_integration to boston_hub, or the developer can request mastership of the branch.

For more information on supporting serial development with MultiSite, see Supporting Serial Development in Replicas.

Creation of the main Branch of an Element

There is an exception to the rule that a branch can be created only at the master replica of the branch type. When you add a file to source control or create a new directory element, the main branch is created even if your current replica does not master the main branch type. By default, the main branch of a new element is mastered by the replica that masters the main branch type, and you cannot create new versions on the branch. During element creation, you can specify an option to have your current replica master all newly created branches. For more information, see Assigning Branch Mastership During Element Creation.

Synchronizing Development on Different Branches

Development of an element with multiple branches can take place in different replicas concurrently, with occasional synchronizations. (The more frequently you update, the easier it is to track and reconcile the changes on different branches of elements. To reconcile changes, you use the ClearCase version-comparison and merge facilities.)

For example, before the Boston site starts using MultiSite, the element cmdsyn.c has two branches, main and v1.0_integration:

When the Boston site starts using MultiSite, the administrator creates a new replica for the San Francisco site. Because integration for Version 1.0 will be done at the San Francisco site, the sanfran_hub replica must master the v1.0_integration branch type. The administrator transfers mastership of the v1.0_integration branch type to the sanfran_hub replica.

Developers in San Francisco can now create versions on the v1.0_integration branch of cmdsyn.c and can create instances of the v1.0_integration branch type for other elements. Work continues on the main branch in Boston:

The administrators at the Boston and San Francisco sites decide to merge some of the work on the v1.0_integration branch with the work done on the main branch. The San Francisco administrator sends an update packet to the boston_hub replica, and the Boston administrator imports it:

The Boston administrator then merges from the v1.0_integration branch to the main branch by checking out the latest version on the main branch, merging from the latest version on the v1.0_integration branch, and checking in the result of the merge:

Default and Explicit Branch Mastership

Branches can have default mastership or explicit mastership. When a branch is created, it is mastered by the replica that masters the branch type (default mastership). When you transfer mastership of a branch to another replica, that replica masters the branch explicitly. The output of describe shows how a branch is mastered.

For example, the branch type v2.0_port was created at, and is mastered by, the sanfran_hub replica. The test2.txt@@/main/v2.0_port branch has default mastership, as shown by the (defaulted) annotation:

multitool describe test2.txt@@/main/v2.0_port
branch "test2.txt@@/main/v2.0_port"
created 18-Aug-00.10:50:34 by John Cole (jcole.user@goldengate)
branch type: v2.0_port
master replica: sanfran_hub@/vobs/dev (defaulted)
...

The administrator at the sanfran_hub replica transfers mastership of this branch to the boston_hub replica:

multitool chmaster -nc boston_hub test2.txt@@/main/v2.0_port
Changed mastership of branch "/vobs/dev/test2.txt@@/main/v2.0_port" to "boston_hub"

The output of describe shows that this branch is now mastered explicitly by the boston_hub replica; the (defaulted) annotation is not present:

multitool describe test2.txt@@/main/v2.0_port
branch "test2.txt@@/main/v2.0_port"
created 18-Aug-00.10:50:34 by John Cole (jcole.user@goldengate)
branch type: v2.0_port
master replica: boston_hub@/vobs/dev
...

When you transfer mastership of a branch type, mastership is transferred for all branches of that type with default mastership. Mastership of branches with explicit mastership is not transferred.

For more information, see the chmaster reference page and Transferring Mastership of a Branch.

Type Object Mastership

By default, you can create an instance of a type only in the replica that masters the type object. For example, if the sanfran_hub replica masters the TESTED_BY attribute type, you can create a TESTED_BY attribute only in the sanfran_hub replica.

Often, however, developers at different sites must create instances of the same type. For example, quality engineers at the bangalore replica may also use the TESTED_BY attribute. Therefore, the mkattype, mkhltype, and mklbtype commands can create two kinds of type objects:

• Instances of an unshared type object can be created only in its master replica. (The instances are propagated to and seen in all replicas.) Thus, there are no issues with conflicting changes made in different replicas. By default, the mkattype, mkhltype, and mklbtype commands create unshared type objects.

• Instances of a shared type object can be created in multiple replicas. To prevent cross-replica conflicts, the following restrictions apply:

• The current replica must master the target object (the object to which the annotation is being attached).

• The ClearCase-level instance restrictions (if any) on the type object must allow creation of the instance.

NOTE: If a hyperlink type is shared, you can create a hyperlink of that type between any two objects, at any replica.

ClearCase restrictions that prevent instance creation in an unreplicated VOB also prevent instance creation in a replica; for example, if there is a lock on the type object, instance creation fails. However, because locks are not replicated (except for locks created with -obsolete), a lock on a shared type object in one replica does not prevent instance creation in another replica.

An unshared type object can be converted to shared, but a shared type cannot be converted to unshared. Instance restrictions (for example, once-per-branch use of a label type) for a shared type object cannot be changed.

Figure 2 illustrates the restrictions on creating an instance of a shared type object. For all target objects except versions and branches, the current replica must master the target object. This is slightly different for versions and branches:

• For a version, the current replica must master the branch on which the version is located.

NOTE: When you apply a label whose instance restriction is one per branch, your current replica must master the branch. When you apply a label whose instance restriction is one per element, your current replica must master the element.

• For a branch with default mastership, the current replica must master the branch type.

• For a branch with explicit mastership, the current replica must master the branch object.

Figure 2 Creating an Instance of a Type

For example, the administrator at boston_hub creates an attribute type with the following command:

cleartool mkattype -shared -vpbranch -nc TESTED

This attribute type is defined to be shared across replicas, with the restriction that at most one instance can be created on each branch of an element. You can create an attribute of that type on a version if both of the following are true:

• Your current replica masters that version's branch.

• No attribute of that type already exists on a version on that branch (assuming no other ClearCase restrictions).

Additional mastership restrictions exist when you use administrative VOBs and global types. If a global type is shared, ClearCase can create a local copy of the type only if the type is mastered by the administrative VOB replica at the current site. If the shared global type is not mastered at the current site, you can create instances of the type only if the client VOB replica contains a local copy of the type. This restriction applies even if your current replica masters the object to which you are attaching the instance. This mastership restriction prevents conflicting, simultaneous creation of a given type with a given name at multiple sites. For more information, see Administrator's Guide for Rational ClearCase.

For more information about changing type mastership, see Chapter 8, Managing Mastership.

Mastership Restrictions

Table 2 describes the restrictions for VOB objects.