test

Sun WorkShop TeamWare 2.1 User's Guide

Chapter 5 Starting a Project

When you begin to use Sun WorkShop TeamWare, you are probably moving an existing software development project to TeamWare or you may be starting a new software development project. This chapter contains information about:

Moving an Existing SCCS-Based Project to Sun Workshop TeamWare

To move an existing SCCS-based software project to TeamWare do the following:

  1. Ensure that all SCCS history files (s-dot files) are in directories named SCCS and that these files are directly beneath directories containing source files.

    Configuring works only on files under SCCS version control.

  2. Be sure that your project directory structure is current and organized.

  3. Choose File > Create Workspace, specifying the top-level directory as your workspace.

    The Create Workspace command creates the Codemgr_wsdata directory under the top-level directory.

  4. Use the Bringover Create transaction to form a workspace hierarchy (see "Creating a Workspace From an Existing Hierarchy of Files ").

    See "Configuring a Workspace Hierarchy" for guidelines regarding workspace hierarchies.

If your project is structured so that compilation units can be easily grouped on a directory basis during transfer operations, you can use the default Configuring FLP. See "Grouping Files for Transfer Using File List Programs" for a description of the default FLPs.

If your project requires files to be grouped for transfer operations in special ways, you will have to write your own FLP(s).

Moving a Non-SCCS Software Development Project to Sun Workshop TeamWare

To move an existing project into Sun Workshop TeamWare:

  1. Choose File > Create Workspace to create your project's top-level directory (with its Codemgr_wsdata directory)

  2. Change to the directory where the existing development files live.

  3. Choose TeamWare > Versioning.

  4. In the Versioning window, choose Commands > Check In New

    In the Check In New Files dialog box, select the files you want to include in the development project, and type an initial comment in the Initial Comment text box.

Converting an RCS Project to Sun Workshop TeamWare

rcs2ws is a program that produces a Configuring workspace from an RCS source hierarchy. It converts a project developed in RCS (Revision Control System) and works its way down through the hierarchy to convert the RCS files to SCCS.

rcs2ws operates on RCS files under the parent directory and converts them to SCCS files, then puts the resulting SCCS files into a workspace. If a workspace doesn't already exist, it will be created. The parent directory hierarchy is unaffected by rcs2ws.

rcs2ws searches directories recursively.

To convert files, rcs2ws invokes the RCS co command and the SCCS admin, get and delta commands. These commands will be found using your PATH variable. If rcs2ws cannot find the SCCS commands, it looks for them in the /usr/ccs/bin directory.

rcs2ws does not convert RCS keywords to SCCS keywords. Keywords are treated as text in the SCCS delta.

Using rcs2ws

To use rcs2ws:

  1. Type rcs2ws -p [parent_dir] -n [files | directory] at the prompt.

    The -p option is required to name the RCS source hierarch.

    The -n option allows you to see what would be done without actually doing anything.

Relative file names are interpreted as being relative to parent_dir.

The CODEMGR_WS environment variable contains the name of a user's default workspace. This workspace is automatically used if the -w option is not specified. If you wish to designate the child workspace, use the -w option. See man rcs2ws(1).

If the current directory is contained within a workspace, the containing workspace is used as the child workspace. If workspace does not exist, rcs2ws creates it.

Note -

Use the "." directory to specify that every RCS file under parent_dir should be converted.

When all is as you wish, go on to Step 2.

  1. Type the rcs2ws command using only the -p option.

    Normally, SCCS gets (g-files) are extracted after the files are converted from RCS. If you want to halt the process, do the conversion using the -g option. (rcs2ws -g)

Starting a New Software Development Project with Sun Workshop TeamWare

To start a new project with Sun Workshop TeamWare:

  1. Choose File > Create Workspace to create your project's top-level directory (with its Codemgr_wsdata directory)

  2. Proceed as you would to set up an SCCS-based development hierarchy.

    Ensure that all SCCS history files ("s-dot-file") are in directories named SCCS located directly beneath directories that contain source files.

  3. Use the Bringover Create transaction to form a workspace hierarchy (see "Creating a Workspace From an Existing Hierarchy of Files ").

    See "Configuring a Workspace Hierarchy", for guidelines regarding workspace hierarchies.

    Note -

    The default Configuring FLP groups files recursively by directory; if you intend to use that FLP, be sure to arrange files in compilation units accordingly. If your project requires that files be grouped differently during transfer, be sure to arrange your project hierarchy in such a way that it works well with the FLP(s) you will create.

Configuring a Workspace Hierarchy

How you configure a project workspace influences the interworkspace file-transfer process and the way you prepare product releases. This section will help you choose the workspace hierarchy best suited for your project. You can change any decisions you make now regarding workspace hierarchies by using the Configuring workspace reparenting feature. See "Reparenting a Workspace" for details.

A workspace hierarchy is a chain of parent and child workspaces that is two or more layers deep. The number of layers in a hierarchy bears no relation to the number of workspaces comprising it. A parent workspace and its child comprise two layers. A parent workspace and three children also comprise two layers. A parent workspace and its child and grandchild comprise three layers. Figure 5-1 depicts a "flat" (three-tiered) hierarchy, and Figure 5-2 shows a "multitiered" (four-tiered) hierarchy.

Figure 5-1 A "Flat" (Three-Tiered) Hierarchy

Graphic

Figure 5-2 A "Multitiered" (Four-Tiered) Hierarchy

Graphic

File Transfer Considerations

The way in which you set up your workspace hierarchy can have an impact on the transfer of files up and down the hierarchy.

File System Accessibility

In order to transfer (Bringover/Putback) files between workspaces, both the parent and the child must be mounted on the same file system. The automounter can be used to connect file systems.

Flat Hierarchy vs. Multitiered Hierarchy

To properly design your workspace, you need to be aware of the advantages and disadvantages of flat and multitiered hierarchies.

Advantages of a Flat Hierarchy

A flat workspace hierarchy is one in which many developers put back files to a single integration workspace. The advantage of a flat hierarchy is that all developers have immediate access to one another's work. The moment that Jack (a developer) puts back his work to the integration workspace, Jon (another developer) can use the Bringover Update transaction to have immediate access to the changes made by Jack.

Disadvantages of a Flat Hierarchy

The disadvantage of a flat hierarchy is that time is often wasted because the integration workspace changes frequently, requiring developers to do frequent Bringover transactions, builds, and tests in order to keep their source base up-to-date. There is a cumulative effect of doing Putback transactions; the first developer to do a Putback resolves only one set of changes, the next developer resolves two, and so on till the last developer, who must resolve all of the changes that have been made within her development group.

Advantages of a Multitiered Hierarchy

The amount of time required for a developer to put her work back to the integration workspace can be sharply reduced by interposing a tier of subintegration workspaces between the integration and development level workspaces.

Whenever a developer puts back work to an integration workspace, there is some chance that the next developer to do a Putback transaction will not be able to put back their changes until they bring over the earlier changes, rebuild the modules, and test the new changes with their own--the more Putbacks that occur the higher the potential for conflict.

When many developers work on a project, the Bringover, rebuild, test cycle can become onerous and time consuming. If smaller groups of developers working on related portions of code integrate into a subintegration workspace, that workspace will be more stable and require fewer builds and less testing. Of course when the subintegration workspaces are themselves put back to their common integration area, changes made in the other development workspaces will have to be integrated. Experience has shown, however, that doing larger integrations, less frequently, is more efficient.

Disadvantages of a Multitiered Hierarchy

The disadvantages of multiplying subintegration workspaces are as follows:

Product Release Considerations

When you plan your project hierarchy structure, consider how you plan to release your product. There are a number of ways that you can structure workspace hierarchies to facilitate the preparation of major, minor, and patch releases. The following discussion presents some ideas for you to consider; your product may not lend itself to this model, or your product may have considerations that suggest an alternate scheme.

You should consider dedicating a workspace as a product release staging area for each release. "Hang" the release workspace off a top-level "product" workspace. The product workspace should be located hierarchically above the workspaces in which normal development integration is done. Locating the product workspace this way permits you to begin development of your next release without corrupting the current release.

After the files are transferred to the product workspace, you use the Bringover transaction to transfer the files down to the release workspace. The release workspace can be used to make masters and can serve as an area in which to save work for subsequent releases if necessary.

Figure 5-3 shows a hierarchy that contains a product workspace and release workspaces for six different releases.

Figure 5-3 Hierarchy with Product and Release Workspaces

Graphic

Note -

You can use the reparenting feature to transfer data between release workspaces directly. See "A Reparenting Example" for details.

Coordinating Access to Source Files

Coordinating write access to source files is important when changes will be made by several people. Maintaining a record of file updates allows you to determine when and why changes were made.

The source code control system (SCCS) allows you to control write access to source files and monitor changes made to those files. The SCCS allows only one user at a time to update a file, and it records all changes in a history file.

Versioning is a GUI to SCCS. Versioning allows you to manipulate files and perform most of the basic SCCS functions without having to know SCCS commands. It provides an intuitive method for checking files in and out, as well as displaying and moving through the history branches.

With Versioning, you can:

Versioning helps you perform these tasks and expedites the progress of concurrent development projects.

Branches

You can picture the deltas applied to an SCCS file as nodes of a tree with the initial version of the file as the root. The root delta is numbered 1.1 by default. These two parts of the SCCS delta ID (SID) are the release and level numbers. Successive deltas (nodes) are named 1.2, 1.3, and so forth. This structure is called the trunk of the SCCS delta tree. It represents the normal sequential development of an SCCS file.

It may be necessary to create an alternative branch on the tree. Branches can be used to keep track of alternate versions developed in parallel, such as for bug fixes.

The SID for a branch delta consists of four parts: the release and level numbers and the branch and sequence numbers, or release.level.branch.sequence. The branch number is assigned to each branch that is a descendant of a particular trunk delta; the first branch is 1, the next 2, and so on. The sequence number is assigned, in order, to each delta on a particular branch. Thus, 1.3.1.1 identifies the first delta of the first branch derived from delta 1.3. A second branch to this delta would be numbered 1.3.2.1 and so on.

The concepts of branching can be extended to any delta in the tree. The branch component is assigned in the order of creation on the branch, independent of its location relative to the trunk. Thus, a branch delta can always be identified from its name. While the trunk delta can be identified from the branch delta's name, it is not possible to determine the entire path leading from the trunk delta to the branch delta.

For example, if delta 1.3 has one branch, all deltas on that branch will be named 1.3.n. If a delta on this branch has another branch emanating from it, all deltas on the new branch will be named 1.3.2.n. The only information that can be derived from the name of delta 1.3.2.2 is that it is usually the second chronological delta on the second chronological branch whose trunk ancestor is delta 1.3. In particular, it is not possible to determine from the name of delta 1.3.2.2 all of the deltas between it and its trunk ancestor (1.3).