Previous Next Contents Index Doc Set Home


Introduction to TeamWare Configuring

3

This chapter contains the following sections:

Coordinating the Work of Software Developers

page 15

Copy-Modify-Merge Model

page 16

Default Configuring

page 19

Coordinating the Work of Software Developers

Managing large programming projects involves coordinating the work of developers who share common and interdependent files.

If developers have private copies of the source code, the changes they make to the source base are difficult to track when all of the code is finally (or even periodically) merged. Often the incompatible changes are subtle, and they can affect the entire project. Preparing the code for a final build and release can be difficult.

One solution is to allow serial access to the common files, one developer at a time. This approach eliminates conflicts due to changes that are made simultaneously. Unfortunately, this approach produces a productivity bottleneck because only one programmer at a time has access to the code.

Developers often change the way source files are grouped and used to build the intermediate and final product. A developer must know what source files, header files, and libraries are required to build a particular program. Often a developer copies a set of files, then later finds that it is incomplete. Only after repeated failed attempts to build the program is the developer able to determine which files are required to successfully build the program. Also, changes not only occur to files, but often to the file system structure as well. New files and directories are constantly created, renamed, and deleted.

Maintaining a consistent, buildable set of sources in preparation for a product release is also difficult on a large software project. When developers integrate their work directly into the mainline source hierarchy, a set of sources that built correctly one day can be made incompatible the next.

Another problem common to large software projects is the inability to recreate the product at a certain stage of development (for example, a past release). Preserving source code deltas becomes difficult when different copies of files are changed concurrently. Developers generally do not take the time to apply more than one delta. To accurately represent concurrent development, SCCS branch deltas must be used. When deltas are collapsed together, or when parallel deltas are represented sequentially, the true history of the file is lost.

Sometimes development of a feature is begun for a given release and later (often quite near the release date) a decision is made to include the feature in a different release. Backing out the changes and then including them in a different release can be difficult.

Copy-Modify-Merge Model

Sun WorkShop TeamWare assists in the development and release of large software projects. TeamWare is based on a concurrent development model called Copy-Modify-Merge. Isolated (per developer) workspaces form the basis of the TeamWare Configuring model. With TeamWare Configuring, you (the developer) copy source you want to change from a central workspace into your own workspace, modify the source to your liking, and then merge your changes with changes made by other developers in the central workspace.

Note - A workspace is simply a specially designated SunOSTM directory and its subdirectories.
The inconvenience of merging changes is outweighed by the productivity increase that results from developers working concurrently. TeamWare Configuring is designed to minimize (and in some cases, eliminate) the inconvenience of merging changes.

Besides providing isolated workspaces, TeamWare Configuring enables you to easily and "intelligently" copy files between workspaces and then merge changes that exist between corresponding files. Configuring's "intelligent" copy feature enables you to copy project files in groups that you (or the project administrator) determine are logically linked; it also automatically determines for you whether differences exist between the files in the originating workspace and the destination workspace.

You copy project files from a central workspace into your own private workspace, make changes to files (or the file system), and then copy your changes back to the central workspace. You can group source files, header files, libraries, and so on, together in logical units that are copied in unison; TeamWare Configuring further assists the concurrent development process by determining whether differences exist between the files in the originating workspace and the destination workspace. If differences are found to exist, Configuring prevents you (or another developer) from copying over those changes. Configuring then provides sophisticated window-based tools that help you to merge these differences.

Copy-Modify-Merge Example

The following is a Copy-Modify-Merge concurrent development model employed by TeamWare Configuring. This example describes a common software development scenario where two developers are working simultaneously on the same or related parts of a project.

Table  3-1

  • Both you and Developer x copy the same file from the project integration area to your separate work areas.

  • Developer x changes the file and copies the changed file back into the integration area.

  • You modify the same file in your work area and attempt to copy the file back into the integration area. TeamWare Configuring blocks your attempt to copy since it would overwrite Developer x's changes.

  • Configuring informs you of the conflicting changes and you copy the file containing Developer x's changes from the integration area to your work area.

  • With Configuring's assistance, you resolve the conflicts, merge the changes, test the changes, and successfully copy the file back to the integration area.

    • 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
    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
    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 on page 24 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
    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

    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.

    Figure  3-5  Keeping Work Synchronized

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

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

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

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

  • You resolve the conflict, test the changes and successfully put back the file back tothe 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.

    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.

    Case 3
    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.

    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 the next section.

    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-2 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-3 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 conflict

    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:

    Note - All conflicts are resolved from within the child workspace and from the perspective of the child workspace.
    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.



    Previous Next Contents Index Doc Set Home