Introduction

StarTeam has revolutionized software configuration management (SCM) applications by saving your company time, money, and code integrity. Since StarTeam’s inception, we have learned from our own experiences and that of our customers about the best ways to install, configure and use StarTeam. We’d like to share this knowledge and information with you. This document includes:

Ø       StarTeam Overview
A general description and introduction to the StarTeam product line.

Ø       The StarTeam Model
An overview of the object-model used in StarTeam which reviews the differences between project-oriented systems like StarTeam and file-oriented systems like PVCS, Visual SourceSafe, and MKS.

Ø       Software Development Processes
A review of some of the basic processes used in software development and how StarTeam supports these processes.

Ø       Capability Maturity Model
Some techniques for those organizations that strive for compliance with the Software Engineering Institute’s Capability Maturity Model.

Ø       Use Cases
A number of technique examples from our users and technical support team.

Ø       Tips
A number of usage tips from our users and technical support team.

We will continuously update this document with the latest information. We also welcome you to send us your real-life examples, experiences, comments and suggestions that will allow us to improve this document and encourage collaboration. Send us an email: StarTeam-Support@fox.se.

StarTeam Overview

The StarTeam product line is comprised of the StarTeam VirtualTeam Server and its clients: StarTeam, StarDisk, Universal Edition, and Web Connect. When the administrator sets up the StarTeam VirtualTeam Server, s/he configures the server using the database of choice (Microsoft Access, Microsoft SQL Server, IBM DB2, Informix, Sybase SQL Server, or Oracle). Users can be located at one site or widely dispersed across the United States or across the globe. Users access StarTeam VirtualTeam Server via one of the clients: StarTeam, StarDisk, Universal Edition, or Web Connect.

StarTeam, a Windows application, provides an intuitive GUI that displays the project, views, folders, files, etc. The tabbed panes make navigation and deployment easy whether you’re working on bug fixes (change requests), product discussions (topics), work assignments (tasks) or developing code (files). StarTeam integrates with many popular IDEs, for example, Microsoft’s Developer Studio, PowerBuilder, Delphi, and Oracle. It interoperates with PVCS and SourceSafe allowing you to convert existing SCM projects to StarTeam. It also offers a command-line interface.

StarDisk allows users to access file revisions over TCP/IP networks through a virtual StarDisk drive. StarDisk’s integration with Windows Explorer provides transparent access to some of the benefits of StarTeam.

The Universal Edition makes the command-line interface available on platforms that support Java version 1.1 or higher. This allows UNIX users to access StarTeam.

Web Connect users access project repositories via a standard web browser. Web Connect allows users to check files in and out of a StarTeam, PVCS or VSS repository, as well as, create, edit and report on change requests and participate in team discussions.

Customized clients can also be created using StarTeam’s SDK.

StarTeam is ideal for all types of businesses. Some of our diversified customers include Anderson Consulting, Lockheed Martin, and Frito-Lay.

The StarTeam Model

To make the best use of StarTeam in your software development process, you need to become familiar with StarTeam terminology. These terms may seem foreign at first, but you will discover that the StarTeam model is more applicable to your business practices than the models found in earlier generations of SCM systems. Also, the flexibility of the StarTeam model allows you to finally manage all of your information assets, source code as well as documentation, through a single coherent system.

The StarTeam Repository

The backbone of the StarTeam system is the StarTeam repository, which is supported by the StarTeam VirtualTeam Server. This repository is an object-oriented data store that supports object versioning, linking and configurations. Any object, known as a StarTeam item, stored in the repository has its history recorded so that a prior state of the item may be retrieved and restored. StarTeam items may be linked to any other item in the repository so that the relationships between the various information assets can be maintained and used in your work processes. Configurations containing many items can be created, maintained and restored through the services of the StarTeam repository.

Client Server Architecture

Access to the StarTeam repository is through the StarTeam VirtualTeam Server. This means that your archive files are fully protected. Products such as PVCS, MKS and SourceSafe require that the revision archives be accessible by all users as shared files. This makes these archives, and the information assets they store, also accessible to attack by computer viruses or disgruntled employees. With StarTeam, the only process that needs to access these archives is the StarTeam VirtualTeam Server.

All StarTeam clients, whether it is the StarTeam Window GUI, command-line interface, IDE integrations, StarDisk, or a custom application using the StarTeam SDK, communicate with the StarTeam VirtualTeam Server using TCP/IP. StarTeam, the Windows application, can also use NetBEUI, IPX/SPX or Named Pipes. Since StarTeam has been optimized for the Internet, remote users can access the StarTeam repository knowing that all data transfer is compressed and encrypted.

A final consideration when reviewing the StarTeam Client Server Architecture is that StarTeam lets you decide on the database to use. You can select from Microsoft Access, Oracle, Microsoft SQL Server, Sybase SQL Server, Informix and IBM DB2, all industry standard databases that should be familiar to your Database Administrator. For the first time, you can pick the database that is your corporate standard for managing your information assets.

Project-Orientation

Older SCM applications such as PVCS, SourceSafe and MKS, are directed towards individual files. These are referred to as file-oriented version control systems. Each file added to the system has its revisions stored in a specific archive file and this one-to-one mapping is independent of the location where the file is placed when building the application. Some of these products, such as PVCS, do not keep track of which directories the files need to be checked out to. This information is needed to correctly rebuild historic configurations of the files. In addition the only information placed under version control in these systems, as well as in some more sophisticated products such as ClearCase, CCC/Harvest and Continuus, are the revisions to the files.

StarTeam takes a project-oriented approach. In this approach, the source code and documentation files are seen as only one specific item type that makes up the complete project. In addition to the file-oriented version control features found in older products, StarTeam supports version control of the other items you need for a project, such as change requests, topics, tasks and the folder structure that stores these items. A project-oriented system also allows users to view these items in different ways depending on their role or the immediate work requirements of the project. The project-oriented approach is a superset of the features found in the products that implement the file-oriented approach to SCM.

Items

The StarTeam model uses items, such as files, change requests, topics, responses, and audit entries. The most commonly used items are versionable, that is, StarTeam stores a revision history of the item and permits you to view and compare the contents of different revisions.

Items may also be branchable; that is, the can be derived from other items that become their ancestors. Items may have several completely different revision histories with common ancestries. In the case of a text file, for example, the branched item can later be merged with the file from which it originated. For example, the development of a product for a new operating system may start with the existing files for the first operating system as its base.

The concept of branching is not often found in documentation management systems. However, this ability is fundamental to software configuration management. Developers often need to make minor or major changes while still preserving the original development path.

StarTeam’s collaborative framework architecture supports several types of items but is designed to permit the development and addition of more items based on customer demand. The following table lists the types of items found in the current release of StarTeam.

     Table 1: StarTeam Item Types

Projects

StarTeam uses projects, views and folders to organize the items stored in the StarTeam repository. A StarTeam project is best thought of as a collection of closely related views. Each view represents a configuration of items from the repository and can support a different line of development on the same code base. Folders cluster items into groups. For example, you might want to check out all the files in a folder to work on a particular feature of your product. However, there are no restrictions on items found in different projects. The items in a repository can be moved or shared between any views, regardless of the projects the items and views are found in.

Projects provide an additional layer of organization, but they allow you provide a hierarchical structure for the views as well as assign rights at the project level. How projects are used is largely up to you.

You might create a project for each product that your company produces. Or, depending on how you build your product, you might prefer to create a project for each of a product’s major components. Using a separate project for each product components provide flexibility as each component can easily be labeled, branched, and sent through its own promotion model sequence.

Views

When you open a StarTeam project, you must either accept the default (or main) view or select an alternate view. The default view for a project typically contains the configuration that is used for primary development. Additional views can be derived from, that is created based upon this view, and can take on different behaviors. The selected view presents the items found in a particular configuration.

Views typically have names such as Baseline, 4.0 Maintenance, Special 4.0 for Australia, and 5.0 New Development. They represent configurations of items and support different development baselines on the same code base. Views can be compared and merged. For example, you might want to merge files from both 4.0 Maintenance and 5.0 New Development back into the Baseline view eventually.

You can create and use views that:

Ø       Dynamically show the source code and document changes of your project.
This is the typical use of the default (or main) view in a project when the Current Configuration option is specified from the View menu’s Select Configuration command. This dynamic view shows all the items as they change and is used for collaborative development.

Ø       Reference a subset of items found in the original view.
These are often called reference views. Any change made in the new view changes the same item in the original view. This is because the subset view contains references to the original items in the original view and does not branch when changes are made. Typically reference view have names such as Development View or Documentation View, exposing only items of interest to, for example, developers or writers.

Ø       Are read-only and based upon a specific state of the original view.
This is typically done for convenience so that the revisions of items used in product releases can be easily located. For example, a 4.1 Release view might be used to rebuild 4.1 in the future or to allow a company that wants to purchase your source code to review that source code after signing a tentative agreement.

Ø       Permit branching of the items in the new view.
This view can be used to modify the items found in a specific view state without affecting the main development. This is typically done when creating and maintaining a maintenance baseline.

An important feature of a view is that you can reconfigure it to show the items as they existed in that view at an earlier point in time or based on a view label or associated promotion state. You roll back a view using the View menu’s Select Configuration command. A rolled-back view is read-only, showing a precise state of the items and no longer permitting changes to them.

Folders

Each StarTeam view contains a folder hierarchy used to organize its items. Folders reflect the logical organization of the configuration represented by the view. Folders typically have names such as Source Code, Schedules, and User Manuals. They group the items based on who needs to access them or on the closely related nature of the set of files in them. While folders can be organized into any hierarchy, the structure typically follows the structure of the working folders that the files are checked out to.

Folders can also be useful when you need to create different configurations of shared items. You can share folders, files, change requests, tasks, and topics between and within views so long as the views use the same server configuration. When a folder is shared, users of both views can access its contents, including child folders and their contents.

Sharing folders can be an important part of setting up a view. For example, suppose all products use the company’s general libraries to some extent. Even though those libraries are not maintained by the developers of a given product, the product is based on some revision of the source code in them and must be compiled with it. Therefore, some of the library folders should be shared into the product’s view.

You use Ctrl+Drag, to share a folder or an item from one location to another. By sharing, you create a reference to the original folder or item. Unless the shared folder or item’s behavior is set to branch on change, all changes to it are changes to the original.

The shared folder or item’s configuration (floating, based on a label, a promotion state, or a point in time) is initially identical in both views. However, it can be modified in either. This means that the shared items can be very different in each view. Make sure you understand sharing thoroughly before you do this.

The shared folder or item loses any labels it had in the previous view. Labels cannot be moved from view to view.

View Labels

Another feature of a StarTeam view is view labels. View labels are used to identify static configurations containing specific revisions of items in a view. When you create a view label, it stores a time stamp for the view. A view label gives you a static snapshot of the dynamic view that it was created in.

Changes can be made to the specific item revisions associated with a view label by dragging the label from one revision of an item to another in the Label pane. Typically a view label contains a small number of these label changes while the majority of the item revisions are identified by its time stamp.

Branching Views

A common operation in software development is to create a new configuration that holds branched items based on some prior static configuration. This is done whenever a user wishes to perform maintenance on a previous build of the system but does not want to affect the current development. StarTeam supports this through branched views.

Create a branched view by selecting New… from the View menu and then selecting the Permit Items To Branch Within This View check box. Selecting this option allows the new view to have a distinct and independent view label namespace and the items found in the new view will be able to branch. You can elect to have every item branch when it first changes or you can defer this decision and selectively branch items in the new view.

Users unfamiliar with the StarTeam model are often confused by the fact that the view labels from the old view are not also found in the new view. This is typically due to their familiarity with file-oriented systems and revision labels. In these systems revision labels are unique within all branches of a particular file archive. In a project-oriented system like StarTeam, each configuration space, represented by a view that permits branching, must also have a unique view label namespace. This is because the view branches when you create a new view that permits branching. In addition, each view presents only the history of the branch of the item referenced by the view and not the item’s entire history through various branches. This makes the new view an independent configuration of items and, for these reasons, the view labels found in the original view do not exist in the new view.

Merging Views

Often you will want to merge these independent branched items back into the original view or into another view. You can merge items from different views or even the same view but from different folders. The StarTeam View Compare/Merge utility performs a complete comparison of the folders, files, change requests, tasks and topics.

Linking

The ability to link any item to any other item is a powerful StarTeam feature. Many customers use this feature to record the relationships between items such as requirement documents (stored in files), specific change descriptions (stored in change requests), design discussions (stored in topics) and source code changes (stored in files). Since links can also be pinned (or attached) to specific revisions of linked items, you have an environment that provides complete tracability.

File Status

One of the more unique features of StarTeam is the “heads-up” display of file information. The File Status field provides information on the relationship between the files stored in the StarTeam repository and the files stored on your workstation. Understanding these status values and how to use this information can greatly increase your productivity. The File Status values are listed in the following table.

Table 2: File Status Descriptions

When you update the status of a file, StarTeam compares the working file with the revision you checked out and the tip (most recent) revision. For example, the file list may say that the file is Current, but someone else has just checked in a copy of it, so your status really is Out Of Date.

Updating file statuses is not the same as updating files. For example, if a file is not in your working folder, updating the status will let you know that the file’s status is Missing. It will not check out the file for you so that it is no longer missing. After all, you may not want the file on your hard drive. Normally, you use a file’s status to determine whether the file should be checked in, checked out, added, or ignored. Once you become familiar with the File Status field, you can use it to:

Ø       Check in a file if its status is Out Of Date, Missing, or Merge.

Ø       Check out a file if its status is Modified or Merge.

Ø       Add a file to StarTeam if its status is Not In View.

Ø       Know ahead of time that you need to merge workstation files during check-out.

Ø       Run Visual Diff to compare a working file that is Out Of Date with the tip revision. This lets you review the changes other team members have made before checking the tip revision out.

Ø       Check out all files from an older build by rolling back to a specific view label. (From the View menu, select Select Configuration…, then return to the current configuration to review every change made since that build was created by comparing the checked out files with their tip revisions.)

Ø       Locate small changes that cause big problems by incrementally rolling back the view and looking for files with the status Modified. Use the History tab to determine when files were changed.

Glossary