Sun WorkShop TeamWare: User's Guide: 5 - Starting a Project

# Starting a Project | # 5 |

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 a Non-SCCS Software Development Project to Workshop TeamWare | page 42
Starting a New Software Development Project with Workshop TeamWare | page 43
Product Release Considerations | page 47

## 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. Execute the Create Workspace command item in the File menu, specifying the top-level directory as your workspace. The Create Workspace command creates the `Codemgr_wsdata` directory under the top-level directory.

  4. Begin using the Bringover Create transaction to form a workspace hierarchy. See "Configuring a Workspace Hierarchy" on page 44 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" on page 86 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 Workshop TeamWare

To move an existing project into Workshop TeamWare do the following:

  1. Use the Create Workspace command item in the File menu to create your project's top-level directory (with its `Codemgr_wsdata` directory)

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

  3. Start Workshop Versioning and select Check In New.

    Select the files you want to include in the development project, and enter an initial comment.

## Converting an RCS Project to Workshop TeamWare

rcs2ws is a program that produces a CodeManager 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`.

To convert files,`rcs2ws` invokes the RCS`co` command and the SCCS `admin`, `get` and`delta` commands. These commands will be found using the user's `PATH` variable. If the SCCS commands can't be found, then they will be sought in the `/usr/ccs/bin` directory.

| ### How to Use rcs2ws

  1. Type `rcs2ws -p` [parentdir] -n [files or directory] at the prompt.

    The `` the`-p` option is required to name the RCS source hierarchy , the `-n` option allows you to see what would be done withouut actually doing anything. This will specify the value of the shell environment variable as `CODEMGR_WS`. If the current directory is contained within a workspace, the containing workspace is used as the child workspace. If workspace does not exist, `rcs2ws` will create it.

  If you wish to designate the child workspace, use the `-w` option. See man `rcs2ws` (1). If all is as you wish, go on to Step 2.

  2. Reenter 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)

### Further User Notes

- The "." directory may be used to specify that every RCS file under parentdir should be converted.

- Relative files names are interpreted as being relative to parentdir.

- Directories are searched recursively.

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

- `CODEMGR_WS` variable contains the name of a user's default workspace. The workspace specified by `CODEMGR_WS` is automatically used if the `-w` option is not specified.

## Starting a New Software Development Project with Workshop TeamWare

To start a new project with Workshop TeamWare do the following:

  1. Use the Create Workspace command item in the File menu 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. Begin using the Bringover Create transaction to form a workspace hierarchy. See "Configuring a Workspace Hierarchy" on page 44, for guidelines regarding workspace hierarchies.

  4. 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 inter-workspace 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" on page 66 for details. You can also refer to the Sun WorkShop TeamWare: Solutions Guide for examples.

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

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

### 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:

- Each new workspace consumes disk space.

- Developers who ought regularly to be looking at one another's work may find it harder to do so because they do not put back to the same integration workspace

- Integration of the subintegration workspaces to the higher integration workspace can become more complicated than more frequent, smaller integrations.

## 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. The Sun WorkShop TeamWare: Solutions Guide presents several ways to structure project hierarchies.

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

> Note - You can use the reparenting feature to transfer data between release workspaces directly. See "A Reparenting Example" on page 68 for details. Refer also to the Sun WorkShop TeamWare: Solutions Guide for workspace hierarchy strategies.

## 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 do the following:

- Check in files under SCCS
- Check out and lock a version of the file for editing
- Retrieve copies of any version of the file from SCCS history
- Visually peruse the branches of an SCCS history file
- Back out changes to a checked-out copy
- Inquire about the availability of a file for editing
- Inquire about differences between selected versions using Filemerge
- Display the version log summarizing executed commands

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).