Sun WorkShop TeamWare User's Guide

Chapter 12

Sun WorkShop TeamWare Architecture

This chapter describes the underlying files that Sun WorkShop TeamWare uses to track workspaces and files. It also describes the ways Configuring manipulates SCCS history files when you copy files between workspaces and resolve conflicts.

This chapter discusses the following topics:

• Workspace Metadata Directory
• Configuring Defaults Files
• How Configuring Merges Files
• About SCCS Mergeable IDs

Workspace Metadata Directory

A Configuring workspace is a directory hierarchy that contains a directory named Codemgr_wsdata in its root directory. The Configuring program stores data (metadata) about that workspace in Codemgr_wsdata. Configuring commands use the presence or absence of this directory to determine whether a directory is a workspace.

Configuring provides the tools necessary to maintain the information kept in the Codemgr_wsdata directory. Although not recommended, it might be necessary to modify certain files manually; however, you must be very careful to preserve the format of each file you edit. TABLE 12-1 briefly describes each of the files and directories contained in the Codemgr_wsdata directory. Information regarding the format of these files is available in the man(4) page for each file.

TABLE 12-1   Contents of the Codemgr_wsdata Metadata Directory 

File/Dir Name	Description
access_control	Contains information that controls which users are allowed to execute Configuring transactions and commands for a given workspace. When workspaces are created, a default access control file is also created. See Chapter 4 and The access_control File.
args	Contains a list of file, directory, and FLP arguments and is maintained by the Configuring, Bringover, and Putback transaction commands. Initially, the args file contains the arguments specified when the workspace was created. If you explicitly specify arguments during subsequent Bringover or Putback transactions, the commands determine if the new arguments are more encompassing than the arguments already in the args file; if they are, the new arguments replace the old. See Creating Customized Bringover/Putback File Lists.
backup/	Stores information that Configuring uses to "undo" a Bringover or Putback transaction. See Undoing Changes to a Workspace.
children	Contains a list of the workspace's child workspaces. The names of child workspaces are entered into the workspace's children file during the Bringover Create transaction. Configuring consults this file to obtain the list of child workspaces. When you delete, move, or reparent a workspace, Configuring updates the children file in its parent.
conflicts	Contains a list of files in that workspace that are currently in conflict. See Chapter 6 for more information about conflicts and how to resolve them.
description	Contains a descriptive name and detailed description of a TeamWare workspace created by the user. See Giving a Workspace a Descriptive Name.
Freezepoints/	Created when you set up auto-freezepoints. See Automatically Generating Freezepoints.
history	An historical log of transactions and updated files that affect a workspace. See Viewing Workspace History for more information.
locks	To assure consistency, Configuring locks workspaces during Bringover, Putback, and Undo transactions. Locks are recorded in the locks file in each workspace; Configuring checks that file before acting in a workspace. See Removing Workspace Locks.
nametable	Contains a table of SCCS file names (path names relative to that workspace) and a unique number represented as four 32-bit hexadecimal words. Each entry in the table is terminated by a newline character. The nametable file is used by Configuring during bringover and putback to accelerate the processing of files that have been renamed. If this file is not available, Configuring rebuilds it automatically during the next Putback or Bringover transaction. See Renaming, Moving, or Deleting Files.
notification	Permits Configuring to detect events that involve that workspace and to send email in response to the event. See Notifying Users of Transactions.
parent	The parent file contains the path name of the workspace's parent workspace and is created by the Bringover Create transaction, or by the reparent command if the workspace was originally created with the create workspace command (and thus had no parent). Configuring consults this file to determine a workspace's parent. When you delete, move, or reparent a workspace, Configuring updates the parent file in its children.
putback.cmt	A cache of the text of the comment from the last blocked Putback transaction. Configuring caches the comment in putback.cmt so that you can retrieve the original text when you re-execute the transaction.

Configuring Defaults Files

When you change Configuring behavior using the Tool Properties window, click the Apply button to preserve the changes in runtime configuration files in your home directory. The runtime configuration files are consulted by Configuring when it starts; your changes are used as the default values.

Changes made in the Configuring and Bringover/Putback panes of the Tool Properties window are written to the file ~/.codemgrtoolrc. This file is an XWindows resource file.

Changes made in the Resolve pane of the Tool Properties window are written to the runtime configuration file ~/.codemgr_resrc.

You can also control which workspaces are loaded by default using environment variables (see Configuring Environment Variables). You can save a default list of files to bringover/putback (see Generating a Customized List of Files).

The access_control File

Chapter 4 introduces the concept of controlling who can perform which transactions on a workspace. When you set permissions in the Access Control tab (under Workspace Properties), TeamWare writes the permission in the access_control file. TABLE 12-2 shows the default contents of access_control after you create a workspace.

TABLE 12-2   Default Access Control Permissions

Operation	Default Permission
bringover-from	all users
bringover-to	creator
putback-from	all users
putback-to	all users
undo	all users
workspace-delete	creator
workspace-move	creator
workspace-reparent	creator
workspace-reparent-to	all users

You can manually edit the access_control file to control which users have access to a workspace. TABLE 12-3 shows all of the value types you can specify to control access to your workspaces and what the entries mean.

TABLE 12-3   Workspace Access Control Values 

Value	Meaning
@engineering	All users in the net group named engineering can execute this operation.
-@engineering	No users from the net group named engineering can execute this operation. "-" denotes negation.
@special -user2 @engineering	All users in the net groups special and engineering can execute the operation; user2 cannot (unless user2 is in the special netgroup). "-" denotes negation.
user1 user2	The users user1 and user2 can execute the operation.
"-"	No user can execute the operation.
creator	Only the user who created the workspace can execute the operation. Note that the creator's login name actually appears.
(no entry)	Any user can execute the operation.

How Configuring Merges Files

This discussion assumes that you are familiar with SCCS, including the concept of branching. Branching is defined in How To Read a File's History: Deltas, Branches and Versions. SCCS is described in detail in the Solaris Programming Utilities manual.

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, the Configuring program must manipulate the file's SCCS history file (also known as the "s-dot-file").

When a file is copied (using a Bringover or Putback transaction) from a source workspace to a destination workspace, it appears that a single file has been transferred. In fact, all of the SCCS information for that file (deltas, comments, and so on) must be merged into the destination SCCS history file. By merging the information from the source into the destination history file, the current version (delta) can be derived, and the file's entire delta and comment history are available. The exception is when the file does not exist in the destination workspace. In this case, the entire history file is copied from the source workspace to the destination workspace.

Merging Files That Do Not Conflict

If the file in the destination workspace is being updated (the file has changed in the source of a Bringover or Putback transaction and has not changed in the destination), the new deltas from the destination are added to the history file in the destination. SCCS history files are merged in this case (rather than the source history file being copied over the destination history file) to prevent administrative information (for example, flags and access lists) stored in the destination history file from being overwritten.

To accomplish the merger, the Configuring program determines where the delta histories diverge and adds (to the destination workspace) only the deltas that were created in the source workspace since they diverged. To determine where the histories diverge, the Configuring program compares the delta tables in both the parent and child history files; information used in this comparison includes comments and data, such as who created the delta and when.

FIGURE 12-1 contains an example of a Putback transaction where the Configuring program adds deltas 1.3 and 1.4 from the child workspace to the SCCS history file in the parent.

FIGURE 12-1   Updating a File in the Destination Workspace That Has Not Changed

Merging Files That Conflict

When you propagate files between parent and child workspaces, both the version of the file from the parent and the version in your child often change since they were last updated. When that is the case, the parent and child versions of the file are in conflict.

When file contents conflict, Configuring helps you to resolve the potentially conflicting changes that were made to the file and preserves the file's delta, administrative, and comment history. Configuring merges the SCCS deltas from the parent into the history file in the child. Configuring's Resolve transaction is then used to resolve the conflict in the child. For details on resolving conflicts, see Resolving Differences.

How Merging Tracks Deltas

This merge example involves an integration workspace and two child workspaces owned by different developers, Ian and Ramona. The developers bring over copies of the same file from the integration workspace, and independently change the file. The illustrations show how the SCCS history file is manipulated when conflicts occur and when they are resolved. Some notes regarding the following figures:

• The default delta (the point at which the next delta is added to the SCCS delta tree) is identified by an unattached descending line.
• You can use Versioning to graphically display SCCS delta trees in much the same way they are depicted here.

Both Ian and Ramona copy the same file from the integration workspace with the Bringover transaction. The file is new in both workspaces, so the SCCS history file is copied to both. Integration Workspace represents the parent workspace that both Ian and Ramona use.

Ramona makes changes to the file, creating two new deltas: 1.3 and 1.4, and then puts the file back into the integration workspace (with the Putback transaction). Configuring appends the two new deltas to the parent SCCS delta tree.

Rather than replacing the destination workspace version of the SCCS history file with the source's version, the new deltas are added to the destination SCCS history file to preserve administrative information such as access lists.

In the meantime, Ian also changes the file (creating three new deltas: 1.3, 1.4, and 1.5) and now attempts to put back the file into the integration workspace.

Configuring blocks the Ian's Putback transaction of because the files are in conflict. Ramona's changes that she put back would be overwritten. Ian must first incorporate the changes made by Ramona into his work.

Ian brings over the file that now contains the changes made by Ramona into his workspace from the integration workspace. The deltas that Ramona created are added into the child SCCS history file by Configuring.

The delta tree brought down from the parent is unchanged in the child. The new deltas created in the child are attached as an SCCS branch to the last delta that the child and parent had in common; the deltas from the child are assigned new SIDs accordingly. The deltas are renumbered using the SCCS branch-numbering algorithm that derives the SID from the point at which it branches. In this case, the branch is attached to SID 1.2; the first delta is renumbered to 1.2.1.1. The last delta created in the child (1.2.1.3, formerly 1.5) is still the default delta. Therefore, any new deltas that Ian creates in the child before the conflict is resolved are added to the child line of work, and not the trunk (the parent line of work).

Ian resolves the conflict in his workspace using the Resolve transaction (see Resolving Differences for details regarding conflict resolution). Ian uses the Resolve transaction to help him decide how to merge the versions of the file represented by SIDs 1.2.1.3 and 1.4. When he commits the changes, the Resolve transaction places the newly merged contents into a new delta 1.5:

• The new delta, 1.5, is contained in a circle because Ian created it.
• The newly created delta is now the default location for any new work Ian creates.

With the conflict resolved, Ian puts back the file into the integration workspace. The branch and the newly created delta are added to the SCCS history file in the integration workspace.

Ramona makes another change to the file in her workspace, creating delta 1.5. She attempts to put back the new work to the integration workspace, but the Putback transaction is blocked because it conflicts with the newly merged delta 1.5 that Ian had put back.

Ramona brings over the changed file into her workspace where its deltas are added into the child SCCS history file and renumbered by Configuring.

As in the previous case, Configuring appends the delta that Ramona created to the last common delta on the delta tree trunk as a branch and renumbers it appropriately. 1.5 becomes 1.4.1.1. 1.4.1.1 remains the default delta. Any new deltas created in the child before the conflict is resolved will be added to the branch.

Using the Resolve transaction, Ramona resolves the conflict merging the differences between 1.5 and 1.4.1.1 to create the new delta 1.6:

• The newly created merged contents are added as a new delta to the parent delta 1.6.
• The new delta is owned by Ramona, who owns the workspace.
• The new delta becomes the default delta; therefore, new work in the child will now be added beneath it.

This merge example has shown what happens when you have an integration workspace and two child workspaces owned by different developers. The developers bring over copies of the same file from the integration workspace and independently change the file. When they attempt to put their changes back, conflicts occur. Configuring manages deltas to ensure that no one's changes are overwritten and manipulates the SCCS history file so that the file history is accurate and complete.

About SCCS Mergeable IDs

This section explains why SCCS Mergeable IDs (SMIDs) are necessary, how to translate SCCS delta IDS (SIDs) to SMIDs, and how to translate SMIDs to SIDs.

The use of SMIDs ensures that every delta is uniquely identifiable, even if its SID is changed. A SMID is a number generated using the Xerox Secure Hash Function. When you use Freezepointing to create a freezepoint file, it calculates the SMID for both the current delta and the root delta in the SCCS history file. Using both of these values, Freezepointing can identify a delta in a file even if its SID has been changed.

Why SMIDs are Necessary

When Configuring encounters a file conflict during a Bringover Update transaction (file is changed in both the parent and child workspaces), it merges the new deltas from the parent workspace into the SCCS history file in the child. When this merge occurs, the deltas that were created in the child are moved to an SCCS branch off of the delta that both deltas have in common (common ancestor).

When Configuring relocates the child deltas to a branch, it changes their SID. If SIDS were used in freezepoint files to identify deltas, this relocation would invalidate the information contained in the freezepoint file. For that reason, SIDs cannot be used to identify deltas after conflicting SCCS histories have been merged.

SMID/SID Translation

You can translate SMIDs into SIDs and SIDs into SMIDs using the freezept sid and freezept smid commands. This is useful if you want to write your own scripts or programs to track deltas.

Translating SIDs to SMIDs

Use the freezept smid command to translate SIDs to SMIDs. The syntax is:

freezept smid [-w workspace] [-r SID] [-a] file

• Use the -r option to specify the SID (in file file) for which you want to calculate a SMID.
• Use the -a option to calculate a SMID for all of the SIDS in file.
• For convenience, you can use the -s option to specify a directory from which file is relative.

Examples

example% freezept smid -r 1.38 module.c SID 1.38 = SMID "f5b67794 705f0768 a89b1f4 588de104"

example% freezept smid -a bringover.1 SID 1.1 = SMID "b05b0a2f 1db5246e 1a466014 707e38f5" SID 1.2 = SMID "d6a5c61f 5634f0ef 9847a080 d0d7b212" SID 1.2 = SMID "e31acdd5 6c1232e2 9e81c287 1edb2f41" SID 1.3 = SMID "c34c91b4 a818622a 2457356a 489b2728" SID 1.4 = SMID "98c0fd8d 889563fb cf722c2b 6afc9636" SID 1.5 = SMID "b1e24be3 752fec3e df2d2717 a9b3f1fa" SID 1.6 = SMID "2b93d39 1ea2f6ba 9814320c bc609acb" SID 1.7 = SMID "1db7d640 42b0f009 35c60d7b b230bd85" SID 1.8 = SMID "906dfe9a ca7e2d6c a64da5be 4baef254"

Translating SMIDS to SIDS

Use the freezept sid command to translate SMIDs to SIDs. The syntax is:

freezept sid [-w workspace] [-m "SMID"] [-a] file

• Use the -m option to specify the SMID (in file file) for which you want to calculate a SID.
• Use the -a option to calculate a SID for all of the deltas in file.
• For convenience, you can use the -s option to specify a directory from which file is relative.

  ---

  Note – Because the SMID contains white space, you must enclose it within quotation marks.

  ---

Examples

example% freezept sid -m "64fdd0df de9d7dd de75812 23da96aa" module.c SMID "64fdd0df de9d7dd de75812 23da96aa" = SID 1.36

example% freezept sid -a bringover.1 SMID "b05b0a2f 1db5246e 1a466014 707e38f5" = SID 1.1 SMID "d6a5c61f 5634f0ef 9847a080 d0d7b212" = SID 1.2 SMID "e31acdd5 6c1232e2 9e81c287 1edb2f41" = SID 1.2 SMID "c34c91b4 a818622a 2457356a 489b2728" = SID 1.3 SMID "98c0fd8d 889563fb cf722c2b 6afc9636" = SID 1.4 SMID "b1e24be3 752fec3e df2d2717 a9b3f1fa" = SID 1.5 SMID "2b93d39 1ea2f6ba 9814320c bc609acb" = SID 1.6 SMID "1db7d640 42b0f009 35c60d7b b230bd85" = SID 1.7 SMID "906dfe9a ca7e2d6c a64da5be 4baef254" = SID 1.8 SMID "77481e8a 61542339 cc28f532 e5fc6389" = SID 1.9 SMID "cb97c9a6 d0342cf6 19b7b743 2436ca1c" = SID 1.10 SMID "46de4131 b95b9973 93958a07 b960074c" = SID 1.11