Floating Items

Floating is a StarTeam feature that needs careful management. Floating is a configuration option available for all items on the Configuration tab of the Item Behavior dialog box.

The alternative is a pinned configuration. Items can be pinned to a label, promotion state, or a point of time in the past. The StarTeam field named Configuration Time shows you the configuration of an item. The field is blank when the item is floating. The field contains a date and time if the item is pinned. That date and time may be the time that the view was created, the time the item was shared by a VCM operation, a time selected by a user on the Configuration tab in the Item Behavior dialog box, the time of the promotion state to which the item was pinned, or the time of the label to which the item was pinned.

Effects on an Item Caused by a Floating Configuration

The effects on an item caused by a floating configuration depend on the item’s behavior, for example if it is an item type that can branch: folder, file, or change request, and on the behavior of the folder in which it resides. The StarTeam field named Branch State shows you whether an item that can branch is a Root, Branched, or Unbranched item.

A Root item is the root of a reference tree. It always has the dot notation 1.x.
A Branched item is not the root reference in the reference tree and it has branched in the location where it resides. In its history, you should be able to see at least one place where its dot notation changed form 1.x to 1.x.y.0. Every time that an item branches two more digits are added to its dot notation. An item branches only once in each location, but it may have been shared to many locations. The reference tree shows those locations.
An Unbranched item is not the root reference in the reference tree, and it has not yet branched in the location where it resides. The StarTeam field name Branch On Change displays a Yes or No for unbranched items indicating whether the item is set to branch when it is changed. There is a check box on the Behavior dialog named Branch on change which is selected when an item is set to branch on change.

The following dialog shows that an item is set to branch on change. Its behavior can be changed from this dialog, but “Branch On Change” = yes is the preferred behavior:

If this item’s Branch State had been Root or Branched, the check box would be disabled.

Floating Shares

In general, floating shares are considered bad practice, especially for items that branch (folders, files, and change requests) because synchronization and propagation can happen automatically and may be unwanted.

Changes from the parent item will automatically propagate to a child item if the child item’s configuration is set to float. You can see this in the reference tree for either item. This behavior happens regardless of whether the Branch On Change option is selected or not. Once the child item branches, the floating stops. In order to branch, the item’s behavior must be set to Branch On Change.
Changes from the child item will automatically propagate to the parent only if the child item’s configuration is set to float and the ‘branch on change’ option is not selected.

For floating folders, there are additional consequences:

New items added to the parent folder can float into the child folder until the child folder branches.
New items added to the child folder can float into the parent folder if the child folder’s configuration is set to float and the ‘branch on change’ option is not selected.

Notice that floating can occur uni-directionally (parent reference to child reference) or bi-directionally (parent to child and child to parent). Also notice that a floating folder affects what happens to items newly added to it. As a result of floating, the parent and child items can be identical. Actually, they are the same item because no branching has occurred.

When this happens, a View Compare/Merge session reports the difference type Unchanged. This can be surprising if you know that you have changed the item recently, or if you compare labels within a view and see that this particular item has changed since the label was made. Understand that Unchanged can mean Same item in both locations in addition to Unchanged.

While floating is generally considered a bad practice, this feature is allowed because it can be useful in certain circumstances, particularly for items that cannot branch (requirements, tasks, and topics). When items that cannot branch have a pinned (non-floating) configuration, they are also read-only.

Note: An item that can branch is read-only if it is both pinned and set to branch on change. This is because the item cannot branch and the change cannot float to another location.

Some customers put items that cannot branch in a floating folder so that the can float from one view to another. They also set each item’s configuration to floating so that it can be changed from any view in which it can be seen. Those changes, in turn, can be seen in all views where the item is visible.

VCM has a few of ways of finding floating items. It looks for the following item difference types:

Floating Child Share (Row 1210 in the Action Decision Table)
Floating Child Share, Source On Root Branch (Promote) (Row 1230)
Target Folder Has Floating Share In Source (Row 200)

All of these are discussed in the topic Understanding VCM Difference Types. Difference types 1210 and 1230 only occur if the VCM option Fix Floating Child Shares is used in the session. VCM can correct for these differences. When difference type 200 occurs, it results in a Fail condition. To commit the VCM session, a manual change must be made to the floating folder in the target view, followed by a refresh of the view. Then the VCM session must be redone. It might be wise to check other foldersin the problem folder's reference tree. VCM only detects the problem between the two views being compared in the VCM session. There may be other floating references.

Floating Items in a VCM Session

VCM has a few of ways of finding floating items It looks for the following item difference types:

Floating Child Share (Row 1210 in the Action Decision Table)
Floating Child Share, Source On Root Branch (Promote) (Row 1230)
Target Folder Has Floating Share In Source (Row 200)

All of these are discussed in the topic “Understanding VCM Difference Types”.

Difference types 1210 and 1230 only occur if the VCM option Fix Floating Child Shares is used in the session. VCM can correct for these differences. When difference type 200 occurs, it results in a Fail condition. To commit the VCM session, a manual change must be made to the floating folder in the target view, followed by a refresh of the view. Then the VCM session must be redone. It might be wise to check other folders in the problem folder's reference tree. VCM only detects the problem between the two views being compared in the VCM session. There may be other floating references.