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:

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

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.

Use Cases

StarBase realizes that each company’s work environment has unique structures, policies, processes and software development lifecycles. Our goal is to model your SCM methodology within StarTeam. The following is a brief introduction to some Use Cases that our current customers use and the best way to apply these using StarTeam.

I. Release Development and Main Development

You do not have to freeze the baseline during release activities with StarTeam. StarTeam handles release development and main development in a number of ways. The following brief scenarios may be familiar.

Sample Scenario 1

During the development cycle both Joyce and Mike have code changes that need to be checked into StarTeam for Release 1. Joyce finishes her work for Release 1 a couple of weeks before Mike. While Mike is still working on his changes, Joyce needs to continue working on her files for the next release without affecting Release 1. How do you ensure that the items Joyce checks into StarTeam will not stop continued development in the main baseline? And, when Mike is done with his changes, how will they be incorporated in Release 1?

Using a New View to Resolve Scenario 1

One way to handle this scenario is to create a new, but perhaps temporary, view into which Joyce checks her additional changes. Later these changes can be merged back into the baseline, if and when appropriate.

Using Labels to Resolve Scenario 1

Another way to handle this scenario is by using of revision labels and view labels. A revision label provides a convenient way to identify a revision or a small set of revisions using the revision label’s name. This is primarily used for files.

A view label applies to the latest revisions of all the items in a view. For example, when the project reaches a particular milestone (such as beta), you might create a view label. Then you can configure the view to return to the way it was at the time the label was applied, check out revisions as a group using that label, create a new view based on the label, or assign the label to a promotion state.

In this scenario, Joyce and Mike would perform the following steps:

1.       

After Joyce is done with her changes for Release 1, she creates a revision label for her files (called Beta Release 1) and continues developing for the next release.

2.        When Mike completes his changes for Release 1, he creates a view label (called Prod Release 1).

3.        Mike then (using StarTeam 4.1) selects File >Select>By Label… to find Joyce’s revision label (called Beta Release 1).

4.       

Once the queried files are selected  (Beta Release 1), Mike moves the view label (Prod Release 1) from the tip revision of each of these files to the revision that has the label Beta Release 1 using the Attach a Label dialog.

Sample Scenario 2

Mike is the project coordinator and StarTeam administrator for a group that is simultaneously releasing software to production and developing new releases. How does Mike handle the project releases while allowing other development to continue on the main baseline?

Using Promotion States to Resolve Scenario 2

StarTeam uses labels, promotion states and branched views to allow for continuous baseline development during release engineering activities. The steps in this process are:

1.        Create a view label when development is complete. For example, you might name the view label Release Candidate.

2.        Select Promotion…from the View menu. From the Promotion dialog, create various promotion states (for example, Testing, QA, and Release).

3.        Select Promotion…from the View menu to promote the Release Candidate view label through the various states until it reaches the final state, the Release state.

4.        Create a branched view derived from the current view and assign this configuration to a promotion state. In this case, the desired promotion state is Release.

A separate baseline is created for release integration and engineering while development continues in the main baseline.

II. Bug Fixes

StarTeam offers users the ability to create Fix Branches (or Maintenance Branches) from the main development baseline for the purpose of creating service packs or other bug-fix releases. After the service pack is released, you can merge the Fix Branch back to the main baseline of development.

Sample Scenario 3

During the development cycle both Joyce and Mike have changes that need to be checked into StarTeam for Release 1. Joyce realizes that there are some bug fixes she needs to make from the main baseline. However, she does not want to affect development on that baseline. How should Joyce handle these bug fixes?

Using a Fix or Maintenance Branch to Resolve Scenario 3

When maintenance and parallel development need to occur simultaneously, StarTeam recommends the use of branching and merging. The steps in this process are:

1.        From the main baseline of development, derive a new view from the current view.

2.        Permit items to branch and branch all items.

3.        Follow the wizard. (That is, give the new view a name and a new working folder. Select a configuration based on the specific date and time, label, or promotion state).

4.        Perform all of your bug fixes in the Maintenance View.

5.        Upon completion of your bug fixes, select Compare/Merge… from the View menu to merge your items back into the main baseline of development.

III. Independent Product Development

StarTeam allows users to create a separate development baseline for independent development efforts. This independent development baseline can be based on the main baseline in its current or an earlier configuration.

Sample Scenario 4

Developers Joyce and Mike are developing code for Product A in the main baseline. Tim and Jill are developing new code for Product A1. Product A and Product A1 are independent products that have their own files, tasks, topics, change requests, and labels. Tim and Jill need to create a view (from the main baseline) that permits branching. For example, Product A might be Product A1 with a few special features for a specific(but not typical) audience.

Using a New Branch to Resolve Scenario 4

When developing an independent product based on an existing product, StarTeam recommends creating a branching view. Each item in the new view should branch when that item changes in the new view. The steps to ensure this are:

1.        From the main baseline, derive a new view from the current view.

2.        Permit items to branch and branch all items.

3.        Follow the wizard. (That is, give the new view a name and a new working folder. Select a configuration based on the specific date and time, label, or promotion state).

4.        Check out the files in the new view, change them as appropriate and check them back in.

IV. Common Component Library Development

Often companies have products with components that share libraries of common source code files. The common source code files need to be included in the build for each of the components that use them. Users will need to create a project to store only those common libraries. Breaking up a product into separate components greatly enhances the flexibility of each integrated component, which can be easily labeled, branched, and sent through it's own promotion model sequence independently of any other component in the product.

Figure 5: Project Hierarchies that Share Common Code Files

Figure 5 represents three independent StarTeam projects[1]. The Common project contains source code that is shared with each of the three projects (A - C)[2]. You can access the shared source code from any project.

You can set up the shared folders so that any change made to the source code in any of the shared projects or from the Common project immediately updates all the projects. You can also force changes made to the common code by project developers to remain only in the project in which the code was changed. You do this by not setting or by setting the Branch On Change behavior option, respectively.

You can roll back the shared folders to use earlier versions of the common source code within a given project. However, you cannot roll the shared folders back based on a label or promotion state because separate projects (and views) do not share view labels or promotion states.

Projects A through C can be components of the same product or separate products, depending on your needs. The next few sections explain how to build Projects A through C (shown in Figure 5) at one time when they are components of one product. [3]

Setting up the Build Process

When each component is an independent StarTeam project, you can easily label, branch and promote items without affecting other components/products. However, some additional work is required to check out all the components to create the end product. The easiest way to combine these projects is to create a build process using the StarTeam command line.

Checking Out by Build Label

Figure 6 is an example of a batch file that generates a build of the product composed of separate components, each of which is stored in a different project. Each component/project is checked out based on its build label: Project A uses its Build 5 view label; Project B uses its Build 2 view label; and Project C uses its Build 3 view label. The check out process retrieves only the revisions of the files with the correct build label. All files from all projects are checked out to "C:\production build". This batch file compiles the projects and creates one single product. To reuse this build without having to remember what label was used for each component, check build.bat into StarTeam and assign it a build label. In the future, if you want to recreate this build, check out build.bat from StarTeam and execute it. Be aware that if you have shared folders of common source code that the following example checks that code out three times to three different locations. You may have to make allowances for this.

Figure 6: Build.bat

@ccho off

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project A/Project A" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 5" *

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project B/Project B" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 2" *

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project C/Project C" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 3" *

Checking Out by Promotion State

You can quickly create a current build of your product by checking out files by promotion state. The advantage is that you do not have to set up the items with the appropriate labels for each component. While this can be a great time saver, remember that promotion states float. So using this batch file to generate a build today could generate a different build tomorrow, depending on what labels have been assigned to which promotion states. Figure 7 demonstrates a three-step promotion model for each project. (For more information about setting up a promotion model, see Chapter 9: “Using Promotion States” in the StarTeam User's Guide.) Each promotion state is assigned a corresponding build label. To quickly check out the current production version of your product, run a batch file (see Figure 8: production.bat) that checks out all files from each sub-component currently in the Release promotion state.

Figure 7: Three-step Promotion Model

                                        Project A                           Project B                   Project C

Release                          Build 7                               Build 4                       Build 5

QA                                  Build 6                               Build 3                       Build 4

Testing                          Build 5                               Build 2                       Build 3

Figure 8: Production.bat

@echo off

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project A/Project A" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Release" *

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project B/Project B" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Release" *

stcmd co -p "Administrator:Administrator@Whitestar:49201/Project C/Project C" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Release" *

Running production.bat produces an identical check out to build.bat. However, if the Release promotion state is assigned a new build label, then running production.bat will generate a new build and build.bat would not. To easily roll back to previous builds, it is important to construct and use both batch files. Check the .bat files into StarTeam for repeated use.

V. Configuration Identification Reports

StarTeam allows its customers to create configuration identification reports for builds and/or projects. A configuration identification report indicates what files have changed, been added, or been deleted since the previous build.

The following procedures walk you through the steps for creating such a report. You create a filter (which can be reused for all configuration identification reports), display the correct files in the files list, apply the filter, and generate the report.

Creating a Filter

The filter you create will be similar to the filter described in the following dialog.

1.        Create a filter named Configuration Index / Version Description Document.

a.        Select the Files tab to display the files list.

b.       Select FileðFiltersðFilters… to display the Filters dialog.

c.        Click New… to display the New Filters dialog.

d.      

Name the filter; make it public if it will be used by more users than yourself; click OK.

2.        Specify the fields to be displayed.

a.        Click Fields… to display the Show Fields dialog.

b.      

Select Name, Status, Folder, View, and any others of interest; click OK.

3.        Sort and group by Status.

a.        Click Sort, Group….to display the Sort and Group dialog.

b.      

Sort and group the files by Status; click OK.

4.        Create a query that will locate all files whose status is not current

a.        Click Query to display the Queries dialog.

b.       Click New… to display the New Query dialog.

c.       

Create a condition that locates all statuses except the current status; click OK.

Displaying Modified Files and Generating the Report

1.        Check out all the files based on a particular build (for example, build 2).

NOTE:  Delete all items from the directories/folders to be used in the check-out process prior to checking out the build.

2.        Roll the view back based to the previous build label (for example, build 1).

a.        Select ViewðSelect Configuration… to display the View Configuration dialog.

b.       Configure the view to the previous build label.

3.        Some file statuses will change from Current to Modified for files that were modified in build 2, to Not In View for files added to build 2, and to Missing for files deleted from build 2.

4.        Apply your new filter (Configuration Index / Version Description Document) to eliminate all files that still have the status current (if any) and to group the files for your report.

5.        Select FileðReports… to display the Reports dialog.

6.        Click Generate to create a default report.

VI. Staging

Many content managers use staging to assist in the software development life cycle (SDLC) process. For example, content managers usually have three stages: development, test, and production. They move content from one stage to another as it is developed, tested, and put onto the production server. This may involve managing three computers, one serving each stage of the process, with VSS installed on each computer.

Instead of managing three computers with VSS installed on each, you can use StarTeam to manage one computer using one project with three StarTeam views (as explained below). This reduces the number of administrative and management tasks.

The three views are separated logically into different web root folders, and a single web server can reference them. The files can be checked out manually from each view to separate working folders/directories. This is acceptable practice for intranets or any inside-the-firewall web application. Because of the high traffic and external-to-the-firewall location of a consumer web site, a consumer web site’s production server is often on a separate computer. However, StarTeam views still makes content management easier.

The following example has a phase for each stage. It uses the StarDraw sample project in which you create both views and promotion states.

Phase 1: Creating Promotion States for Your Stages

1.        Open the StarDraw project to its root view.

2.        Create the following promotion states in StarDraw (using ViewðPromotion…).

·         Production—Assign the label New Step 6 to this state.

·         Test— Assign the label New Step 7 to this state.

·         Development— Assign to this state.

NOTE:   As you create the promotion states, there will probably be states for which no view labels currently exist. Use for these states. You can assign a view label to a state when the files associated with that view label meet the criteria required by the state. If you prefer, you can promote the view label from the preceding state to the label-less state.

TIPS:            

·         Use the Move Up and Move Down buttons to rearrange the states. They should be in order from last to first (final state down to initial state).

·         Click Reset to reread the list of states from the server. This reverts to the states that were available when you opened this dialog or when you last clicked Apply.

·         Click Edit... to change the selected state’s name, description, or view label.

·         Click Delete... to delete the selected state from the list.

Phase 2:   Creating a View for the Test Stage

1.        From StarDraw’s root view, select ViewðNew… and create a new view.

2.        By default, the Derive New View From Current View check box is selected. Click Next.

3.        Name this view Test then click Next.

4.        By default, the StarDraw folder and all its child folders will be in the new view. Click Next.

5.        Change the working folder/directory (just in case the testing group needs to check out some files). Click Finish.

6.        Configure the view to show all the files, etc. with the promotion state Test:

a.        Select ViewðSelect Configuration….

b.       Select the Promotion State Configuration option button.

c.        Select the promotion state Test from the list box.

NOTE:   You will need to set access rights to this view so that only the testing group can view and modify its change requests, tasks and topics.

Phase 3:   Creating a View for the Production Stage

1.        From StarDraw’s root view, select ViewðNew… and create a new view.

2.        By default, the Derive New View From Current View check box is selected. Leave it selected.

3.        Also select the Read-only check box. Click Next.

4.        Name this view Production then click Next.

5.        By default, the StarDraw folder and all its child folders will be in the new view. Click Next.

6.        Change the working folder. Click Finish.

7.        Configure the view to show all the files, etc. with the promotion state Production:

a.        Select ViewðSelect Configuration….

b.       Select the Promotion State Configuration option button.

c.        Select the promotion state Production from the list box.

NOTE:   You will need to set certain rights to this view so that only the production group can view files.

Glossary