test

Sun WorkShop TeamWare 2.1 User's Guide

Default Configuring

TeamWare Configuring can be customized in ways that modify its default behavior; many of those customizations are discussed in Chapter 7, TeamWare Configuring Workspace". All source files in a Configuring project are maintained under the UNIX SCCS. TeamWare Configuring only copies files that are under SCCS. Within your workspaces, you use SCCS in the normal way. For example, you:

SCCS history files are in SCCS subdirectories, as they would be if the project were not using Configuring. When you copy files between workspaces and merge files that have changed, TeamWare Configuring manages SCCS history files for you, preserving all comments and deltas.

Workspace

The workspace is the basis of the Configuring system. The workspace provides the isolation in which developers work concurrently with other developers programming in other workspaces. Project files are propagated between workspaces by Configuring commands. The workspace is a directory and its subdirectory hierarchy. When the workspace is created, Configuring creates a special subdirectory under the workspace, called Codemgr_wsdata, to store workspace information.

A Configuring project is created in a top-level workspace from which all others are derived. When other workspaces are created from the original workspace, the original file system hierarchy is recreated to form the new workspace. In the following example, work is begun by a developer in a workspace whose top-level directory is boatspex. The workspace exists under the directory /usr/src/ws.

Figure 3-1 Project File System Hierarchy

Graphic

If you are assigned to work on the Boatspex project you create a copy of the original workspace in a file system of your choice; the workspace portion of the file system in the new workspace is identical to that of the original workspace. If you create the new workspace in your home directory, it appears something like Figure 3-2.

Note -

If you were only working on a portion of the project, you could copy only that portion.

Figure 3-2 Your New Workspace

Graphic

The directories previous the workspace directory (boatspex) are variable. They change depending on where in the file system you locate the workspace. Below the workspace directory, the file system is a duplicate of the original workspace

Parent and Child Relationship

When you copy files from a workspace to create a new workspace, a special relationship is created between the original workspace and the new one. The original workspace is considered the parent of the newly created child workspace. You can acquire files from any Configuring workspace in this manner, and workspaces can have an unlimited number of children. The portion of the file system that you copy from the parent workspace is determined at the time you copy it. You can copy the entire contents of the parent to the child, making it a clone of the parent, or you can copy only portions of the file system hierarchy that are of interest to you. The Configuring transaction used to copy files from a parent workspace to a child workspace is called Bringover.

Note -

If you use the Bringover transaction to copy files to a workspace that does not already exist, the transaction creates a new child workspace and then copies files to it. This special case is called a Bringover Create transaction. You use the Bringover Update transaction to update an existing child workspace.

The parent and child relationship is special because project data is exchanged only between parent and child workspaces. All files contained in a child workspace were either brought over from a parent workspace or created in the child workspace. When development and testing are complete in the child, you can copy the files that were modified or added in the child back into the parent workspace. Once the altered files are present in the parent, they can be copied by other children or passed up another level to the parent's parent workspace. The Configuring transaction for copying files from a child workspace to a parent workspace is called Putback.

Note -

Unless the child is itself a parent, in which case new files can also be copied to it from its children.

Workspace hierarchies are formed by repeating Bringover transactions to create child workspaces. The hierarchy of parent and child workspaces forms a pathway through which data is moved throughout the project.

In the following example, a project is originally created in a workspace and then a three-level workspace hierarchy is created by means of the Bringover transaction. The original workspace is considered to be the parent of the integration workspace and, conversely, the integration workspace is considered to be the child of the original workspace. Developers (Jon, Jack, and Jill) then use the Bringover Create transaction, shown in Figure 3-3 to create child workspaces from the integration workspace, which forms a three-tiered hierarchy of workspaces.

Figure 3-3 Using the Bringover Create Transaction to Create a Workspace Hierarchy

Graphic

In this hierarchy, files can be disseminated from Jon's workspace to its "sibling" workspaces owned by Jack and Jill. Jon uses the Putback transaction to copy modified files from his workspace into the common parent (step 1) and then Jack and Jill use the Bringover Update transaction to copy the files from the parent into their workspaces (step 2), shown in Figure 3-4.

Figure 3-4 Copying Files between Workspaces

Graphic

Reparenting

Parent and child relationships can be changed. Configuring permits child workspaces to be "reparented" to new parent workspaces. Reasons that you might want to reparent a workspace include the following:

Refer to "Reparenting a Workspace"" for more information

Codemgr_wsdata Directory

Every Configuring workspace contains a directory named Codemgr_wsdata that is a subdirectory of the workspace top-level (root) directory. This directory contains text files that Configuring uses to log its actions, and store temporary and permanent data. You can view and alter these files using standard text utilities. Refer to "The Workspace Metadata Directory "" for more information.

Modifying Files

Since Configuring workspaces are simply directories within the SunOS file system, all your usual tools and utilities can be used on files and directories in workspaces. Your normal edit/compile/debug process is not altered by Configuring.

Copying Files between Workspaces

Once you make and test modifications in a child workspace, you must disseminate them to the rest of the developers working on the project and ultimately to an integration/release workspace.

Every developer in a project needs up-to-date data with which to work. If a modification is made to a module in one part of the project, it could have profound implications for the testing of a different module in another part of the project. Perhaps even more important is the sharing of information between developers working on the same or closely related modules.

Newly modified files (or groups of files) are transferred between parents and children up and down the workspace hierarchy in order to keep workspaces consistent. The decision as to when the data is ready for dissemination is, of course, left to the developer's discretion.

The Putback and Bringover transactions are generally applied to groups of files so that files need not be specified individually. Configuring provides the means for you (or your project administrator) to specify groupings of files that should logically be copied together. Three examples of this type of grouping are as follows:

How files are grouped for Bringover and Putback transactions between workspaces is discussed in detail in Chapter 8, Copying Files between Workspaces."

Bringover and Putback transactions are always initiated from within the child workspace. Both transactions are viewed from the perspective of the child workspace--not the parent's.

Source Code Control System Files

When considering Bringover and Putback transactions, remember that source files are derived from SCCS deltas and are identified by SCCS delta IDs (SIDs). When a file is copied by either a Putback or Bringover transaction, Configuring is manipulating the file's SCCS history file (also known as the s-dot-file).

When a file is copied from one workspace to another, Configuring decides how to manipulate the SCCS history file used to derive the file. If the file does not exist in the target workspace, Configuring copies the history file from the source workspace to the target. In the more complicated case--when the file (and thus the SCCS history file) exists in both the source and the target--the SCCS history files must be merged to maintain the file's delta, administrative, and comment history.

Remember, files consist of both the file derived from the latest delta and its predecessors by the SCCS get command and the SCCS history file from which it is derived. When files are copied from workspace to workspace, SCCS history files are adjusted appropriately.

Bringover and Putback Transactions

When you initiate a Bringover Update or Putback transaction, Configuring must make a number of determinations before taking any action. Copying files indiscriminately from one workspace to another could overwrite work that you or another developer want to keep. Configuring must check all files specified for transfer to determine where they stand in relationship to each corresponding file in the other workspace.

For example, suppose a file was modified in the parent (perhaps put back from another child) since it was last brought over into your child. You have modified your copy of the same file in your child workspace. When you attempt to put back that file (or a group of files that contains that file) from your child workspace to the parent, Configuring will not allow your Putback transaction to proceed because it would cause the revised version of the file in the parent to be overwritten by the version of the file from your child. In this case, Configuring blocks your attempt to put back the files into the parent and informs you of the conflicting change.

When a Putback or Bringover Update transaction is blocked, none of the files in the group are copied, even those that don't conflict.

The conflicts between your versions of the files and the versions in the parent must be resolved in your (child) workspace. Conflicts are always resolved in the child workspace to preserve the integrity of the parent.

You use the Bringover Update transaction to copy the conflicting files from the parent to your workspace, and using Configuring's merge tool, you merge your changes with those made by the other developer. After testing the changes you then put back the merged files to the parent workspace.

Table 3-2 Keeping Work Synchronized
Graphic

  • Both you and Developer x bring over the same file to your workspaces.
Graphic

  • Developer x changes the file and puts the changed file back into the parent.
Graphic

  • You change the same file in your workspace and attempt to put the file back into the parent. Configuring blocks the Putback.
Graphic

  • Configuring notifies you of the conflicting changes and you bring the file over to your workspace (actually, the SCCS history files are merged).
Graphic

  • You resolve the conflict, test the changes and successfully put back the file back to the parent workspace.

Relationships between Files in Parent and Child Workspaces

The previous example describes only one of four possible states of relationship that can exist between corresponding files in parent and child workspaces. The relationship between files in parent and child workspaces governs the way that Configuring behaves when you attempt to copy files via Putback and Bringover Update transactions. Following are descriptions of the four cases and the action Configuring takes in each case:

Case 1

Neither the files in the parent nor the corresponding files in the child have been modified since they were put back into the parent or brought over into the child

In this case no action is required by Configuring in either case. The files are exactly the same in both the parent and child.

Graphic

Case 2

The specified files were not modified in the parent since they were brought over from the parent into the child or put back from the child into the parent. The corresponding files were modified in the child.

In this case when you use the Putback transaction to copy the file to the parent, the changed files are updated from the child into the parent, replacing the corresponding files in the parent. This new data is available for acquisition by other children of that parent or to be further propagated up to the parent's parent workspace.

When you use the Bringover Update command in this case, no action is taken because copying the file from the parent would overwrite changes made in the child.

Figure 3-5 Case 3

Graphic

One or more files in the parent were modified since their corresponding files were brought over into the child or put back into the parent from that child. The corresponding files in the child were not modified.

In this case the parent's copy of the file being put back from the child was modified (probably by one of its other children) since it was last brought over to the child; the corresponding file in the child was not modified since it was last brought over into the child.

When Configuring detects this situation during the Putback transaction, it cannot update the parent workspace until the child workspace is updated by means of the Bringover Update transaction. Even if the changes are in files that you have not altered (remember you're copying groups of files), they might impact the changes you have made. In this case, the Putback transaction is blocked and the user is notified. It is the user's responsibility to execute the Bringover Update transaction in order to update the child workspace.

Graphic

Case 4

Corresponding files were modified in both the parent and child workspaces.

This is the most complicated of the four cases. Configuring cannot allow the file to be put back from the child into the parent because the transaction will obscure modifications there. Likewise, Configuring cannot allow the file to be brought over from the parent into the child because the transaction will overwrite modifications there.

As in case 3 above, Configuring blocks the Putback transaction and notifies the user. When the user attempts to update the child workspace by means of the Bringover transaction, Configuring detects that the file in the child has also been changed; the file cannot be updated without overwriting the newly created work in the child. In this case Configuring merges the parent and child SCCS history files for the conflicting file in the child workspace.

Configuring merges the parent and child SCCS history files together in the child workspace; the SIDs that were created in the child are renamed and placed on an SCCS branch off of the current line of work brought down from the parent. Although it is a branch, the child's SCCS version tree remains the default for any additional deltas so that work on the file may proceed in the child as if nothing had changed.The merge process places all needed deltas in the SCCS history file so that the conflicting files can be merged at the user's discretion. All SCCS comments are preserved in this process since the entire SCCS delta history is preserved.

At this point the conflict between the parent and child versions of the file is still open. Work can continue on the branch that contains the deltas created in the child; any new deltas will be added to the branch. However, the user must resolve the conflict before the group of files that contain the conflicting file(s) can successfully be put back to the parent. Conflict resolution is discussed in "Resolving Conflicts".

GraphicGraphic

Summary

The following two tables summarize, first, the action taken by Configuring during a Putback transaction in each of the four cases described above and secondly, for the Bringover transaction.

Table 3-3 Putback Transaction

Case 

File in Parent 

File in Child 

Action by Configuring 

1 

Unchanged 

Unchanged 

None 

2 

Unchanged 

Changed 

Update file in parent 

3 

Changed 

Unchanged 

Block Putback, notify user 

4 

Changed 

Changed 

Block Putback, notify user 

Table 3-4 Bringover Transaction

Case 

File in Parent 

File in Child 

Action by Configuring 

1 

Unchanged 

Unchanged 

None 

2 

Unchanged 

Changed 

None 

3 

Changed 

Unchanged 

Update child (extend SCCS files) 

4 

Changed 

Changed 

Merge SCCS history files and notify user of conflicts 

Resolving Conflicts

During the Putback transaction, Configuring may determine that a file in the parent has been modified since it was last put back from that child or brought over into the child. In that case it blocks the Putback so that the changes are not overwritten and then notifies the user of the potential conflict.

Generally the owner of the child workspace will then attempt to update the child by bringing over the changed file. If, during the Bringover Update transaction, Configuring determines that the corresponding file in the child has also been modified since it was last brought over, a conflict exists.

Conflicts arise when corresponding files in both the parent and child have been modified. If Configuring were to overwrite either of the files, a loss of data would result. Before the specified file can be put back or brought over the user must resolve any conflicts.

When Configuring detects a conflict during the Bringover Update transaction, as described in the previous section, it then does the following:

In the case of most conflicts, the options available to the user for resolving conflicts are:

Configuring provides tools that aid in resolving conflicts, however, the conflicts must be resolved by the user. Refer to Chapter 9, Resolving Conflicts," for a detailed discussion about conflict resolution.