StarTeam Configuration Best Practices - Embarcadero...

StarTeam Configuration Best Practices

Guidelines for configuring StarTeam repositories.

A Borland White Paper

By the Development Resources Platform Team

December, 2003

2

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

A Quick Tour of StarTeam Essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Objects Versus Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Lifecycle Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Server Configuration Principles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Consider Business Unit Divisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Leverage StarTeam’s Support for Distributed Teams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Don’t Partition for Internal/External Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Avoid Servers That Get Too Big . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 Share Machines When Practical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 Split-up Large Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Project Configuration Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 Keep Projects Autonomous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Example 1: A Simple Client/Server Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Example 2: An Independent Client Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Example 3: A Complex Financial Application Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Handle Cross-Project File Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Support Cross-Project Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

View Configuration Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 Understand View Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 Do’s and Don’ts of Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

DO Treat Views As “Streams” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 DO Use The Main View as the Main Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 DO Use Branch-All Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 DO Use View Labels and Promotion States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 DON’T Go Beyond 2 or 3 View Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 DON’T Use Some View Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 DON’T Use Too Many Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Use Views to Support Iterative Development Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Scenario 1: Small Development Teams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Scenario 2: Large Development Teams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 Scenario 3: Concurrent Development Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Other Tips and Techniques. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Achieve Consistent Check-in and Check-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Simplify “Merge Down” with Branch-All Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Know What Operations Are Expensive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Establish a Quick Backup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Use Merge Points Wisely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Use a Test Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

ContentsContentsContentsContents

3

1 Overview

This article provides best practices guidelines for configuring and using StarTeam repositories. Best practices means that the tips and techniques provided here have been successfully used by many StarTeam users. Since StarTeam is a highly flexible software configuration management (SCM) system, there are many ways to support specific application lifecycle management (ALM) practices. Some approaches are better than others based on experience and on “going with the grain” of StarTeam features. The intent of this article is to highlight those approaches.

This article focuses on configuration practices, which includes the creation and organization of StarTeam repositories, projects, and views. It encompasses the techniques by which these configuration features can be effectively used to support iterative development lifecycles, including concurrent development. Example scenarios are provided to illustrate how to configure StarTeam to support them.

The guidelines provided here are intended for StarTeam administrators, project managers, and developers who will advise or manage the organization of StarTeam repositories. The operative word here is guidelines – you should follow these suggestions to the degree that they match your organization’s need. Since there are countless variations of development approaches, you should expect to tailor the proposals provided here for your requirements.

The information in this article is relevant to the StarTeam 5.3 release. Be sure to consult other documentation such as the StarTeam Getting Started Guide, StarTeam User’s Guide, and StarTeam Administrator’s Guide. Also, see the article StarTeam Performance and Scalability Techniques for information on hardware options, capacity planning, and performance tuning for StarTeam deployments.

4

StarTeam Configuration Best Practices A Quick Tour of StarTeam Essentials

2 A Quick Tour of StarTeam Essentials

To use this guide, you should be familiar with basic StarTeam concepts and features. This section reviews key StarTeam features and explains how terms such as items and objects are used in the remainder of this guide.

2.1 ContainersThe most basic StarTeam concepts are “containers” that hold information objects and/or other containers. These include StarTeam server configurations, projects, and views:

! A server configuration is a single deployment instance of StarTeam. All files, change requests, and other artifacts that can be interrelated and managed as a whole reside within a single server configuration. Except for file content, all data and metadata for a server configuration are stored in a database termed the repository. File contents are managed in operating system-level files collectively known as the vault. Vault information is divided into separate areas for storing archive, cache, and attachment files. Suggestions for deciding when to create a new server configuration are discussed in section Server Configuration Principles.

! Within a server configuration, artifacts are organized into projects. Before a server configuration can be used, at least one project must be created to hold files and other objects. A server configuration can hold multiple projects, each oriented to the lifecycle needs of a specific team, application, or component. Guidelines for when you should create a new project and what it should contain are discussed in section Project Configuration Guidelines.

! Each StarTeam project can possess one of more views. Every project automatically receives a main view through which folders, files, and other objects can be organized. Additional child views can be created to represent subsets of the main project information, historic snapshots of project information, or work areas for new development work. StarTeam provides a wide range of options for view creation to support a wide range of development scenarios. Considerations for how you should use views are provided in section View Configuration Practices.

An example StarTeam server configuration is shown in Figure 1 – Example StarTeam Server Configuration. In this example, the server configuration contains two projects: Dev1, whose main view has two child views, and Doc1, whose main view has a single child view, which in turn has a third-level (grandchild) view. As shown, the development artifacts of all projects and views for the server configuration are stored in a single repository and vault.

5


Figure 1 – Example StarTeam Server Configuration

Through the remainder of this article, a server configuration is often referred to as simply a server. This is because each server configuration is often deployed on its own server machine, managed by its own StarTeam server process. However, be aware that StarTeam allows multiple server configurations and server processes on a single machine, hence the server configuration-to-machine relationship doesn’t have to be one-to-one.

2.2 ObjectsObjects are the core information artifacts within a server. Objects, also known as content objects, are versioned so that individual revisions can be accessed, labeled, branched, and so forth. The “content” of an object is stored as a series of properties, each of which has a name and a value. For each object type, you can add custom properties if you need to store more information than is available via the built-in properties. StarTeam supports the following object types:

Files: As with all SCM systems, files are the most important artifact in StarTeam. File properties contain metadata such as the Modified By property, security, and history, all of which is stored in the repository. Files also contain binary or textual data, which is stored in the vault. Files are versioned and can be branched into separate version trees. Files are supported by other configuration and management features such as links and labels.

Change Requests (CRs): StarTeam supports integrated defect and enhancement request tracking via change requests. Like files, CRs can be versioned and branched, linked, labeled and so forth. CRs are typically used to represent discrete requests such as bug reports or new feature suggestions.

Tasks: StarTeam tasks are analogous to work items found in project management systems such as Microsoft® Project. (In fact, StarTeam tasks can be synchronized with MS Project tasks.) A task typically represents a step in a larger work plan and may be assigned to multiple people. Hence, a

Server Configuration

Dev1 (project)

Dev1 (main view)

Release 1.0(child view)

Pegasus(child view)

Doc1 (project)

Doc1 (main view)

DocWork (child view)

Public Docs (grandchild view)

Database

CacheArchive Attachments

VaultRepository

6


task may be divided into subtasks and tracked via multiple work records. Tasks are versioned and can be labeled, linked, and so forth, however they do not branch like files and CRs.

Topics: A topic is a newsgroup-like message that can be posted by one user, responded to by another, and so forth. A chain of topics on a given subject create a “threaded discussion” that can be attached to a file, CR, or other object to capture a conversation important to a development activity. Like tasks, topics are versioned but do not branch.

Requirements: StarTeam supports lightweight requirements objects that can be used to document early development lifecycle steps. Requirements can be authored and utilized directly in StarTeam, or they may be imported and synchronized with objects from formal requirements management systems such as CaliberRM™. Requirement objects support versioning, linking, and labeling but do not branch.

Folders: Every view has a root folder, which typically contains a tree of subfolders beneath it. A folder can contain objects of any type, including other folders. Although folders are “containers”, they have properties and are versioned, hence they are also objects and, like files and CRs, can branch. Note that a folder’s logical “path” name is defined by prefixing its name with that of its parent folders’ names. However, the corresponding “working folder path”, which is where files within the folder are stored locally at the client, may not match the logical path name – the working folder path can be overridden on a per-folder and per-client basis.

Because objects are “exposed” via items, the terms object and item are sometimes used interchangeably. However, objects and items are distinct entities, whose differences are discussed next.

2.3 Objects Versus ItemsIt is important to understand how objects are “surfaced” through views. Every content object is exposed to a view via an association object called an item (also called a view member). When a new object, say a file, is added to a view, StarTeam creates a new file object with version 1.0, and it creates a new item that “points” to that file. The item not only specifies which file is referenced, but it specifies the folder in which the file appears. So, for example, if you move the file from one folder to another, you actually modify the file item to point to a different parent folder item, but the file and folder objects are not actually modified.

The relationship between items and objects is illustrated in Figure 2 – Items Versus Objects. In this example, two views are shown, each of which points to its root folder item. Every item points to a corresponding object, which holds the object properties, and every item other than the root folder item points to a parent folder item, which designates the folder in which it resides.

7


Figure 2 – Items Versus Objects

An item created on behalf of a new object is called a parent item. A child item is created by “copying” a parent or child item, allowing the same object to be surfaced in another location. A child item points to the parent item from which it was copied. Child items are created in two situations:

! Child views: When a new view is created as a child of another view, the parent view’s items are copied to create the child view’s items. The objects themselves are not copied – the new child view items merely point to the same objects.

! Shares: An item can be explicitly copied, creating a “share” item. This is done, for example, by holding the Ctrl key and dragging an item from one folder to another in the StarTeam client. In this case, the selected item is copied, initially pointing to the same object as the original item.

The primary difference between child view items and child share items is their initial configuration. The behavior of an object is partly influenced by the configuration of the parent or child item through which it is manipulated. To understand how parent and child items behave, it is necessary to understand the separation between object and item properties:

Object properties: Most of the properties you see – name, modified by, version, data (for a file), etc. – belong to the object. When the object is modified in any way, another revision of the object is created. For example, if the current revision of a CR is 1.2 and the Responsibility property is modified, the modified CR is stored as revision 1.3. If a new version of a file currently at revision 1.4.1.2 is checked in, the new version is 1.4.1.3.

Item properties: An item contains properties that define which object is referenced, the folder in which it should appear, and how updates to the object via the item should be handled. Most of an item’s properties such as parent view and parent folder are implicitly managed by StarTeam based on client actions. There are three key item properties that affect the manipulation of the object referenced by the item:

parentitem

childitem

File

File

CR

Task

File

File

Req.

Items Objects

View 1 Folder

Folder

Folder

Folder

root folder

parent folder

View 2root folder

sharedobject

shareparent

File

8


! Object ID: This property defines the object “branch” to which the item refers. Each new object receives a unique object ID, and its revision number begins at 1.0. The object’s revision number is incremented each time it is updated (1.1, 1.2, etc.), but the object ID is not changed. Hence, the object ID referenced by an item points to the entire object branch and possibly a specific revision. When an object branches, a new object with a new object ID is created, and its revision number is extended to reflect the branch point (e.g., 1.2.1.0). An item refers to the new branch by updating the object ID to which it points.

! Behavior Configuration: This property defines whether or not the item is floating or pinned to a specific point in time. When an item’s behavior is set to floating, the item points to the tip revision of the object branch to which the item refers. When the behavior is set to a specific point in time, the item refers to the object revision that was current at that time.

! Branch-on-change: This property is only valid for a child item referencing a file or CR. It controls what happens if the object is modified via the item. If “true”, branch-on-change causes a modification to start a new branch for the object. For example, a file checked in via the item when the current revision is 1.2 will start branch 1.2.1.0. When branch-on-change is “false”, either the underlying object has already branched via this item, or updates via the item operate on the same object as the parent item, or the item is read-only (frozen).

Child view items are “automatic” shares that are created and managed by manipulating the views to which they belong. Hence, you can usually focus on managing the view itself without worrying about the child items.

However, “manual” shares that you create via UI gestures or SDK commands require more attention to item properties to understand how updates will propagate to other items in the same share tree. For example, shared item operation can be complicated when a parent item is deleted, an intermediate shared item’s behavior is changed, or the shared item is a folder. For these reasons, shares should be used cautiously. Furthermore, as will be discussed later in section Project Configuration Guidelines, shares across project boundaries should be used with even greater scrutiny.

2.4 Lifecycle FeaturesBy themselves, containers, objects, and items allow you to capture development artifacts and organize them according to the needs of your projects and teams. StarTeam provides additional core features that support processes such as builds, releases, and change management. These features focus on the development lifecycles through which information flows:

Links: StarTeam links allow arbitrary objects to be related. For example, a defect CR can be linked with the files modified to fix a defect. The link end-point objects can be pinned to a specific revision of an object, or they can float to the latest version of the object.

Labels: A specific set of object revisions can be referenced via a label. A view label typically references a specific revision of all objects in a view, while a revision label typically references specific versions of a small group of objects. StarTeam promotion states are built on top of view labels and support the notion iterative build, release, and deployment processes.

Process Rules: A project can be configured to enforce process rules, which require the use of specific CRs, tasks, or requirements as controlling items for file check-ins. When activated, process rules promote change traceability by linking new and modified files to the process items to which they are related.

9

StarTeam Configuration Best Practices Server Configuration Principles

3 Server Configuration Principles

This section provides some guidelines you should consider when deciding how many StarTeam server configurations to deploy. This section does not focus on performance and scalability considerations since these factors are covered more extensively in other articles. Use these guidelines to help answer the question “When is the right time to deploy a new StarTeam server?”

Since each server has its own database instance and vault, multiple servers increase administrative costs. On the other hand, distributing your organization’s StarTeam projects among multiple servers increases project independence and improves performance and availability factors. Below are some strategies to consider when developing your organization’s server deployment plan.

3.1 Consider Business Unit DivisionsWhen multiple business units require their own StarTeam projects, it often works well to define StarTeam servers along organizational boundaries. That is, deploy a separate StarTeam server for each major business unit or department, allowing each to access its own projects. Dividing along business unit lines isolates separate (and sometimes competing) requirements for security, backup processes, and other administrative issues. Separate servers can also help mitigate ownership or “turf” issues.

Where development lifecycle processes cross configurations, clients can open multiple projects in a single StarTeam client. “Deploying” interrelated artifacts from one project to another can also be used to address cross-configuration integration needs. This subject is discussed further in section Project Configuration Guidelines.

3.2 Leverage StarTeam’s Support for Distributed TeamsIn general, team members that require access to the same development artifacts should share a single StarTeam server. Dividing or replicating a StarTeam server solely due to geographically dispersed teams is usually not necessary. StarTeam was designed to work well over the Internet, even over slow connections. Remote developers often find that performance is adequate over long distances. Using StarTeamMPX and deploying MPX Message Brokers to regional development centers increases responsiveness even further.

3.3 Don’t Partition for Internal/External AccessIn many situations, teams both behind and outside of the corporate firewall require access to a single StarTeam server. A common practice in this scenario is to deploy the StarTeam server in the DMZ area of the firewall, placing the database on a separate server behind the firewall. Depending on the capabilities of the firewall, it may be appropriate to configure a dedicated port to the StarTeam server. Alternatively, you can install two network interface cards (NICs) on the StarTeam server machine: one “outward” facing and one “inward” facing. In this scenario, StarTeam allows specific inbound IP addresses (or address ranges) to be configured with different connection security requirements. Other security features such as strong password management and automatic account lockouts further increase the viability of using the same StarTeam repository for both internal and external developers.

10


3.4 Avoid Servers That Get Too BigAs with all client/server applications, the demands on the StarTeam server grow as the number of artifacts and the number of concurrent users grow. Even with high-end hardware, the server’s CPU, memory, disk, and network resources are finite, and each could become a bottleneck to server responsiveness. (Even though it’s usually easy to add more disk, disk contention is still a potential bottleneck in large servers.)

Although there are no hard numbers that define when a server is “too big”, below are some numbers based on experience that suggest boundaries of what constitutes “too big”:

Your mileage will vary from these numbers depending on hardware and usage patterns. One StarTeam customer, for example, has been able to run with 3,000 registered users and 400-600 concurrent users.

3.5 Share Machines When PracticalIf your organization needs to support multiple, smaller server configurations (10-20 concurrent users each), they can be placed on the same machine. Some important points to consider in this scenario are:

! Each server configuration must be supported by a separate StarTeam server process.

! Two processes running on the same machine must accept inbound connections on different port numbers. (This is a TCP/IP restriction.)

! Each server configuration can be independently marked to have its StarTeam server process start as a service.

! Each server configuration must have its own database and vault, but the databases can be shared in the same “partition”.

For medium size server configurations (up to 50 concurrent users), the StarTeam server process, database, and vault can all reside on the same machine. As the total number of artifacts and/or concurrent user count rises, you’ll want to separate the database onto its own machine first, connected to the StarTeam server via a high-speed (100Mbit or 1Gbit) network connection.

If your organization needs to support multiple, large StarTeam servers, you can still deploy the databases on a shared machine with multiple CPUs and lots of memory, connected to the StarTeam server machines with a high-speed network (1Gbit). The vaults can also be shared on a high-speed storage device, provided it supports high concurrency (e.g., multiple controllers and/or RAID 5).

In short, you don’t have to dedicate a machine to each StarTeam server process, database, and vault, even for large installations, provided that you plan for high concurrency. See the article StarTeam Performance and Scalability Techniques for more information on hardware options, capacity planning, and performance tuning.

total # of: No problem

Getting big Probably too many

Projects 50 200 500

Views 100 400 1000

Items (all types; tips) 1,000,000 4,000,000 10,000,000

Files (tips) 500,000 2,000,000 5,000,000

Registered Users 500 1,000 2,000

Concurrent Users 100 250 1000

11


3.6 Split-up Large ServersSplitting-up an overly large server is possible, but it is not trivial. The basic process for moving a set of projects from one server to a new one is as follows:

1. Perform a full dump (DB + archive) of the server configuration to be split.

2. Restore the database and archive on a secondary system.

3. Change the server GUID on the secondary system (ask Borland support for the process to do this).

4. Delete the unwanted projects on the secondary system.

5. Run the StarTeam purge utility on the secondary system to clean-up deleted database records and vault files.

6. Verify the secondary system via vault-verify, testing, etc.

7. Deleted the original (now “cloned”) project(s) from the original server.

8. Run the purge utility on the original server to return database and archive space.

Depending on the size of the server configuration, this process can take many hours, so plan to do it over a week-end or other down time. The degree to which you succeed with this process depends largely on the autonomy of the projects that you “move”. Shares between the moved and unmoved projects will reduce the amount of infor-mation that can be cleaned-up during the purge. This is one reason for keeping projects autonomous, which is discussed more in the next section.

12

StarTeam Configuration Best Practices Project Configuration Guidelines

4 Project Configuration Guidelines

As with servers, when to create and how to organize StarTeam projects is an essential decision. The number of projects in a server and the number of artifacts managed in each affects issues ranging from performance to ease of administration. Here are some guidelines for deciding how to set-up your projects.

4.1 Keep Projects AutonomousThe time-honored programming tenets of high cohesion and low coupling apply to StarTeam projects as well. The more independent your StarTeam projects are, the easier they are to secure, administer, and even separate from the original StarTeam configuration if necessary. Keeping projects autonomous means keeping cross-project links and shares to a minimum, avoiding them completely if possible. Below are some guidelines for deciding what should be in the same project:

! A project should be used to manage the lifecycle artifacts of a cohesive application set or application component set. Examples are a commercial software product or a foundation library package. Multiple application or component sets can be managed in a single project if they are interrelated and generally enhanced and released together.

! A project should include all of the artifacts required to manage the lifecycle of the supported applications or components. This includes early lifecycle artifacts such as requirements documents, modeling diagrams, and design documents, as well as construction phase artifacts such as source files.

! A project should include artifacts authored in lifecycle phases, and non-authored artifacts required to perform authoring. This includes, for example, all files authored by the IDEs such as workspace/project files, source code, and resource files. It also includes “input files” such as .h, .lib, .jar, or .dll files that are authored or generated elsewhere but required by the project’s IDEs or build processes. Input files may originate from third parties or from other projects in the same or other StarTeam configurations. (Transferring artifacts from one project to another is discussed further later.)

! Files directly generated from authored files such as .obj, .class, and .lib files generally do not need to be checked into the project. However, it is common practice to check-in “final” binaries such as .jar, .war, and .exe files that are delivered to other projects, engineering test, QA, or other deployment phases. The need to place generated files under version control is highly dependent on your own development, testing, and release methodologies.

! A project should have a long-term view of the products or components it supports. That is, it should house all artifacts generated over multiple iterations through the lifecycle. This means that the project supports multiple versions of its applications or components, representing the complete history of those modules. How views are used to support specific lifecycle activities and releases is discussed in section View Configuration Practices.

! StarTeam works best when the supplemental objects (CRs, tasks, topics, and requirements) related to a project’s files are stored in the same project. This allows, for example, a CR to be entered, tracked, and linked to the files in the same project to which the CR is related. This approach requires some special considerations for activities such as “CR triaging” and cross-project reporting. These issues are discussed later.

13


Some customers have attempted to use projects to separate development phases (e.g., design and development) or development artifact types (e.g., files and CRs). The artifacts are then interrelated by sometimes heavy use of links or shares. However, experience has found that copious use of shares – especially cross-project shares – results in difficulties in version control, reporting, security, and even performance. Evidence suggests that artifacts that are related to the same applications and components, though of different types and/or lifecycle relevance, are more effectively managed in the same project.

4.1.1 Example 1: A Simple Client/Server Application

Scenario: A commercial software application consists of a server written in C++ and a single client, also written in C++. Furthermore, the client and server modules share a fair amount of source code and IDE projects that generate common DLLs. The client and server modules are generally enhanced and released together.

In this scenario, a single StarTeam project should be used to manage the combined files of both the client and server modules. The sharing of source code and shared release schedules suggest that the modules are cohesive parts of a single application. Requirements, design documents, CRs, and other objects required for all lifecycle phases of the client and server modules should be managed in the same project.

4.1.2 Example 2: An Independent Client Module

Scenario: A new Java client application is developed that uses the same server described in Example 1. Building and compiling the Java client requires some of the header files and one of the DLLs used by the server to produce a JNI wrapper, but no other source files. Furthermore, the Java application accesses other third-party servers and is generally enhanced and released on independent schedules from those used by the client/server modules.

In this scenario, it is reasonable to use a separate StarTeam project to manage the Java client’s artifacts. The latest header files and generated DLL needed by the Java client are checked into a “external components” folder by the build process used in the client/server project. All CRs, tasks, and other lifecycle objects related to the Java client are managed in the same project.

4.1.3 Example 3: A Complex Financial Application Suite

Scenario: A complex application suite consists of a set of foundation components and nearly 100 separate applications, divided into five functional areas: accounting, insurance, forecasting, etc. The applications are developed by different teams and all use the foundation components, which are jointly maintained by the development teams. Applications within a functional area are highly interrelated, but applications between functional areas are fairly independent. The foundation component library is enhanced and released on its own schedule, but the entire application suite is released as a commercial product in coordinated releases.

Although the entire application suite is interrelated, multiple projects should be used due to the overall application suite size. The foundation components are managed in one project, and each of the five functional areas utilize a separate project to manage the corresponding applications (six projects total). The foundation project is enhanced, built, and then “deployed” to each of the functional area projects by checking in generated jar files. Each development team generally opens only one project to perform their normal work. However, a special build script (using the StarTeam SDK) is used to extract files from multiple projects and generate “whole suite” builds. The build script also automates the management of common view labels and promotion states across projects.

14


4.2 Handle Cross-Project File DependenciesWhen projects are highly cohesive, cross-project dependencies will be minimal, yet cross-project file relationships may still occur. Some files, either authored or generated, may need to be used in multiple projects.

The impulsive way to handle this situation may be to share the codependent files from one project to another. On the surface, this approach works, but experience has shown that cross-project sharing is problematic for several reasons:

! If a share’s behavior is configured to “floating”, changes from the parent project flow into the child project immediately, sometimes at inconvenient times. Many StarTeam users find that they need to manage the update propagation on a more scheduled basis.

! If a share’s behavior is configured to a specific timestamp, it must be occasionally adjusted to allow updates to propagate. This makes the shared item read-only, and continually adjusting the configuration timestamp for a large number of shares can become burdensome.

! If a share’s branch-on-change property is set to “true” (perhaps accidentally), and a change is made to the child share, the object will branch in the child project. This severs the share from the parent object and is difficult to reverse. If the child share is a folder, an innocuous change such as modifying the working folder will cause the folder object to branch.

! When an update is made to an item that participates in a share tree, every item in the tree must be locked. As the share tree grows, update performance is impacted proportionately.

! Normally, when obsolete views and projects are deleted, the StarTeam purge utility can be used to return unused database records and archive files. However, shares used by a deleted project or view can prevent the purge utility from achieving the expected reduction in database and archive size. In short, it might not be possible to reduce the size of servers that use cross-product sharing.

Because of these reasons, other techniques have proven to be more effective at handling cross-project file dependencies. Below are some alternatives to sharing that work in different situations:

! Deployment approach: If a project “owns” a set of files that must be checked into other projects, you can establish a process in which the files are periodically “deployed”. This means that the file set is checked into the target project(s) on an as-needed basis, perhaps by a script. Often, a build script is a good place to embed the deployment task, especially if the file(s) to be deployed are generated by the build.

! Configuration approach: Sometimes the codependent files don’t need to be checked into each project, but they need to participate in a common process such as a build or delivery process. In these cases, a simple XML file can be constructed that defines the files that participate in process. If the file is checked into an established location and updated when the configuration changes, then build, release, or other scripts can check-out the XML file, parse it, and base their processing on its instructions.

! Link approach: In lieu of shares, links can be used to connect objects across servers. Links do not possess many of the problems exhibited by shares, and they can be pinned, unpinned, and moved to refer to different object revisions. The downside of using links is that they are un-typed, not versioned, and possess no properties other than a link comment to distinguish them from other links that may be present.

In the end, shares still may be the most appropriate way to expose files from one project to another, but the above approaches should be considered first.

15


4.3 Support Cross-Project ActivitiesRegardless of how you partition your projects, you may find that certain lifecycle activities span multiple projects. Some examples of these scenarios and how they can be addressed are provided below:

! Multi-project builds: Build procedures that require files from multiple projects can use the StarTeam SDK, which can open multiple projects at the same time. Alternatively, iterative calls to the StarTeam command line tool (stcmd) can be used to check-out files from each of the required projects.

! Defect triaging: When a new defect is discovered, it is often entered as a CR before the module that must be repaired is known. This means that, if CRs are normally managed in the project containing the files that will be modified, a paradox exists in determining where to create the CR in the first place. A project leader or other person usually “triages” the CR by assigning it to whoever he or she thinks should handle it. As the CR is analyzed and addressed, the module that is ultimately modified to address it may not be known for a while. A simple solution for this scenario is to place all CRs in a well known place (perhaps a “new defects” project) and “move” (not copy) them to the appropriate project as needed.

! Cross-project reporting: Currently, StarTeam does not provide built-in, cross-project reports. Consequently, if you want to generate reports such as “all open CRs across all projects” or “cross-server file metrics”, your best option is to use the StarTeam SDK to write simple reporting apps in Java, VB, or your favorite language of choice.

16

StarTeam Configuration Best Practices View Configuration Practices

5 View Configuration Practices

Views are one of the most important configuration concepts in StarTeam. They represent “portals” into project artifacts that can serve a wide range of development process activities. Views can be likened to a Swiss army knife that offers many tools and options to suit a wide range of needs, but you have to be careful – a couple of the blades can really cut you!

In this section, the basic view types and their general characteristics are discussed. Also provided are some basic view “do’s and don’ts” and suggestions on how views can be used to address various development lifecycle scenarios.

5.1 Understand View TypesThere are many types of views whose functionality varies based on the options used to create them. Some view types are useful for specific situations; some views are rarely useful. Since view behavior is based on the options used to create them, view types are not formally defined, which can make them a little confusing. Below is one way to break-down view types and describe their general functionality:

! Non-derived view: This is also called a “blank” view. It is not derived from any existing views, rather it starts out empty. If only new folders, files, and other objects are added to it, it effectively acts like a project except that, as a view, it still “belongs” to the project from which it was created. If objects that originate elsewhere are shared into a non-derived view, it acts like an arbitrary assembly of objects. The shared items can float and therefore updated, or they can be fixed and therefore read-only. Non-derived views are rarely used.

! Derived view: A derived view is created with some other view as the “perspective”. One of the perspective view’s folders is chosen as the root of the derived view, hence the derived view is a “window” into the objects at which it is rooted. However, a derived view has many different behaviors and uses depending on other options:

! Reference view: A reference view is a derived view that is a pure subset of the objects that are exposed through it. That is, the parent and reference view refer to the exact same objects, so changes though one affect the other view. Items in a reference view do not branch, hence reference views are also called “non-branching views”. The reference view utilizes the same view labels as its parent. Reference views can be further divided into two types:

" Updateable reference view: The items in an updateable reference view “float” to the tip revision of corresponding objects, hence the objects can be updated via the reference view. These changes appear immediately in the parent view as well. In practice, updateable reference views are rarely used. They can be confusing since updates to the reference view flow through to the parent view and vice versa. The “sub-setting” ability of the reference view may be useful in some cases, but similar functionality can be accomplished with security settings.

" Read-only reference view: The items in a read-only reference view are read-only and hence can’t be modified via the view. Some or all of the view’s items configuration may be “floating”, allowing changes from the (updateable) parent view to show through. Conversely, items can be pinned to a specific configuration and hence won’t reflect changes to the underlying objects unless the item configuration(s) are changed. Both pinned and floating read-only views are occasionally useful for read-only applications such as build scripts.

! Variant view: In contrast to a reference view, a variant view is not a pure subset of its parent view. Instead, the objects to which it refers may branch when updated, although each item’s branch-on-change behavior can be set individually. Consequently, variant views are also called “branching views”. How the view’s items are initially configured cause variant views to behave in very different ways:

17


" Branch-none view: If a variant view’s items are initially configured with branch-on-change set to “false”, it acts like a reference view, except that the view doesn’t share labels with its parent. If the view’s item configurations are set to “float”, updates through those items will float to the parent. (This is sometimes called a “floating view”.) If item configurations are configured to a specific timestamp, those items will be read-only. Some users have tried to create branch-none views and hand-tweak item configuration and branch-on-change, but this approach has proven tricky at best and sometimes disastrous. Consequently, branch-none variant views are not advised.

" Branch-all view: Branch-all variant views are perhaps the most useful of all views. All items are initialized with branch-on-change set to “true”, hence they can be updated regardless of their configuration. Setting the item’s initial configuration to floating versus a specific timestamp makes the view useful in different ways. This topic is discussed further under Development Scenarios.

The basic properties and usefulness of the various view types are summarized in the following table:

5.2 Do’s and Don’ts of ViewsIrrespective of view type, below are some general do’s and don’ts to consider when creating and managing views.

5.2.1 DO Treat Views As “Streams”

Treat each view as a “stream” for a specific lifecycle activity. The view may receive lots of updates, few updates, or none at all depending on the type of activity it supports.

View type

Referenceversus Variant

Shares labels with parent view

Items can branch

Items can be updated Usefulness

Non-derived N/A N/A Only if shared Yes Low

Updateable reference view

Reference Yes No Yes Low

Read-only reference view

Reference Yes No No Medium (for read-only applications)

Branch-none view

Variant No Initially No Only if floating

Medium (tricky to manage)

Branch-all view

Variant No Yes Yes High

18


5.2.2 DO Use The Main View as the Main Baseline

Use the main view as the project’s “production” baseline. As such, it will accumulate all artifacts for the applications or components supported by the project. Depending on your lifecycle model and the size of your development team, changes can be made in a variety of ways, as discussed later. However, changes eventually migrate “up” to the main view.

5.2.3 DO Use Branch-All Views

Make branch-all views your primary workhorse. Use reference views for read-only activities such as build scripts.

5.2.4 DO Use View Labels and Promotion States

View labels and promotion states are easy to use and efficient. With a view label you can quickly mark all artifacts in a view, perform check-outs and builds based on the label, and adjust the revision of individual files that are included in the label. Promotion states allow you to define logical lifecycle states such as engineering test or release candidate and map each one to a view label, which can be adjusted or easily “promoted” to the next state. New views can also be created based on view labels and promotion states.

5.2.5 DON’T Go Beyond 2 or 3 View Levels

Views are generally only needed as immediate children of the main view. Third-level (grandchild) views are occasionally necessary. View levels deeper than 3 probably mean you probably aren’t using views efficiently.

5.2.6 DON’T Use Some View Types

Don’t use non-derived views, floating views, or updateable reference views except in very special circumstances where you thoroughly understand the behavior of these view types and that behavior best matches your use case.

5.2.7 DON’T Use Too Many Views

Views are somewhat “heavyweight” objects: They can take many minutes to create when derived from an existing view with many items, and they typically add thousands of new child items to the database. It’s safe to up to several hundred views in a single StarTeam server, but you don’t want to have thousands of views. This means that views don’t work well as a “personal workspace” for individual developers.

19


5.3 Use Views to Support Iterative Development ScenariosThis section describes various iterative development scenarios and suggests how views can be used to support each one. For each scenario, the following assumptions are made:

! The main view is used for the production baseline.

! The project is configured to enforce process items, hence a CR, task, or requirement object is created for each “unit” of work. A “unit” is loosely defined to be the amount encompassing the check-in of a related set of files.

! View labels (and possibly promotion states) are used for routine builds. This means, for example, that a nightly view label is applied from which a build is generated and then tested. View labels, promotion states, and process items are used to support “intra view” update steps.

5.3.1 Scenario 1: Small Development Teams

For small development teams and/or short-term work activities, developers can use the main view directly. Child views are created when a release milestone is reached and subsequently used for release maintenance. The small team development scenario is illustrated in Figure 3 - Small Team Development Scenario.

Figure 3 - Small Team Development Scenario

The activities used to follow this development scenario are summarized below:

! When a modification (“mod”) is needed, a developer checks-out the required files from the main view, locking those that will be modified. After making local work file changes, including the creation of any new files needed, the developer performs sufficient unit testing to ensure that files can be released to other developers. When finished, the developer checks-in the new and modified files while unlocking, using a process item to link the revisions to the applicable CR, task, or requirement.

! An automated script (not depicted) runs periodically and creates a new view label. Check-outs are made from the label to perform builds and launch test suites.

! When the main development stream reaches a release milestone (e.g., after code complete), a branch-all variant view is created from a specific view label (e.g., “Build 5.3.142 Release

MainView

check-in with process item and unlock

mod

check-out with lock

mod mod mod

supportpatch

Support View for release 1.1

supportpatch

mod mod

supportpatch

branch-all view createdfrom view label

Support View for release 1.0

20


Candidate”) or promotion state (e.g. “Integration Test”). The variant view is used as a support view, since the only changes made to it will be critical defect fixes. Primary development continues in the main view.

! If a change made to the support view is deemed applicable to other (future) releases, it is merged “up” into the main view as well (not depicted). View compare/merge is usually not required for this since the main view continues to evolve while the support view remains relatively constant with respect to a specific release. Instead, individual files are merged up to the release view.

! This process repeats for each major release, creating multiple support views over time.

Sometimes, the support view itself may be split off to a third-level view, for example to support service packs. This should be rare, however. If many server pack support views are created, causing lots of per-file merging one of the other iterative development scenarios may be more appropriate.

5.3.2 Scenario 2: Large Development Teams

If your organization has longer-term work activities that are typically performed sequentially, you may not want to allow changes directly to the main view due to the periods of potential instability that may occur. Instead, you may want each project to reach a stable point (e.g., unit test or integration test) before it is released to the main view. To support this model, when a new work activity starts, you can create an activity view. (The term “activity” is used to avoid confusion with the term “project”, although “project view” is also an apt name.) An activity view is a branch-all variant view whose item configurations are set to “floating”. Hence, changes in the parent view will be propagate “down” to the child view. However, as a variant view, the activity view will branch any item if it is modified through that view.

When the activity reaches the appropriate milestone (e.g., passes integration test), it is released to the main view by performing a child-to-main view compare/merge (“merge up”). The activity view then becomes inactive and may eventually be deleted. This model isolates changes for major new activities from the main view.

The activity view scenario is depicted in Figure 4 - Activity View development.

Figure 4 - Activity View development

MainView

Activity View 1

mod mod mod

branch-all view createdfrom view label

supportpatch

Support View for R1.0

Activity View 2

mod mod mod

merge “up”

supportpatch

Support View for R1.1

Activity View 3

21


When one or more sequential activities have been merged into the main view, a support view as described in the previous section is created for release-specific maintenance.

5.3.3 Scenario 3: Concurrent Development Activities

In large development environments, development projects often are not sequential. Instead, you may need to launch multiple concurrent activities that must eventually be joined and then released together. Each activity must not only pass its own development and testing stages, but it must also pass integration testing with other activities before it can be released to the main baseline. In these environments, merging activity views directly into the main view may result in unacceptable periods of instability.

In this scenario, two changes from the previous example are suggested. First, the activity view should be created as a branch-all variant view whose item configurations are initially set to a known view label. Periodically, the activity view can “rebase” with the main view by merging “down” from the main view, causing the item configurations to move forward in time. This allows changes from other activities that have been merged into the main view to be merged back into the activity view on a controlled based.

Second, when multiple activities are ready to be merged together, a “release” view is created. (A release view could also be called “candidate release” view.) Like the activity views, the release view should be a variant branch-all view whose items are initially based on a known configuration (e.g., view label). Each activity view targeted for the same release is then merged into the release view using view compare/merge. After the activity-to-release “sibling” merges are complete, the release view undergoes integration testing. Changes required as a result of testing are made in the release view. Eventually, when the release is approved, it is merged “up” to the main view. In this scenario, a separate support view is usually not needed since the release view can assume the role of the maintenance stream.

The concurrent development scenario is depicted in Figure 5 - Concurrent Development.

Figure 5 - Concurrent Development

A1 (R3)

A2 (R1)

A6 (R4)

A4 (R4)

R2 R3R1

R4

Key:• An (x): Activity View targeted for release x• Rn: Release View for release n• Activity views are branch-all float views• Release views are branch-all fixed views• All views are 2nd level child views

= merge from main to child view

= merge from child view to siblingview or main view

MainView

mod

mod

mod

merge “down”

A3 (R2) A5 (R3)

22


Key points of this example concurrent development scenario are summarized below:

! A new activity view (prefixed “A”) is created whenever a new major activity is launched. An activity view is a branch-all variant view with configured (non-floating) item configurations.

! A new release (prefixed “R”) is created when the first activity is ready to be “delivered” to the release stream. A release view is created in the same manner as an activity view.

! Before an activity view is merged into a release view, it is first “rebased” with the main view to accept any recent changes (e.g., other releases or “mod” changes). This is accomplished by a “catch-up” merge down, denoted by the downward-pointing dashed arrows.

! Similarly, after all activity views have been merged into their target release view, the release view is rebased with the main view.

! A release view is “deployed” by merging into the main view. This is done by performing a merge “up”, denoted by the upward-pointing dashed arrows. The release view then changes roles as a support view.

! Minor changes (“mods”) are made directly to the corresponding view – activity, release, or main – using process rules for control.

By adjusting the procedures for creating and managing activity and release views, you can tailor this process to match the concurrent development needs of your environment. The more sophisticated your development process, the greater your need is to tailor the process to your requirements.

23

StarTeam Configuration Best Practices Other Tips and Techniques

6 Other Tips and Techniques

6.1 Achieve Consistent Check-in and Check-outIn all of the above scenarios, developers can use various StarTeam features to allow or avoid conflicts with other developers on the same files (in the same view). In a low-contention environment, developers can check-out files without locks, modify them, “refresh” to identify and resolve merge conflicts, and then check-in modified files.

In higher contention environments, your developers may want more assurance of:

! Consistent check-out: getting consistent sets of files during check-out, that is, avoiding files that are a partial set of someone else’s check-in, and

! Consistent check-in: avoiding check-in conflicts that arise when someone else is checking-in an overlapping set of files

The easiest way to achieve both needs is “by convention”. Each developer exclusively locks all files before checking them in, and unlocks them when they are “complete”, either at check-in or soon thereafter. Correspondingly, each developer exclusively locks all files before checking them out, and unlocks them when complete. If a developer can not get all the locks at once, they are potentially about to interfere with another developer, so they unlock files they currently have locked, wait a bit (probably talk with the developer they are conflicting with), and then try again. One implication of this “by convention” approach is that a developer could be blocked while waiting for another developer to finish-up.

A more formal way to enforce consistent check-outs is using “view configuration”. To ensure consistent check-outs without locks, a developer can temporarily change their view configuration to a known “stable” point. In some organizations, a nightly build process creates a view label when the server is not used or lightly used. To temporarily change the view configuration from the Win32 or cross-platform client, select “View | Select Configuration | Labeled Configuration” and choose the latest build label. (Alternatively, choose a timestamp or promotion state.) The view will switch to show the item states at the selected time, and “consistent” check-outs can be performed from there. Note that the view configuration change is only at the client – the underlying “real” view is not modified. Also, note that “rolled-back” views are read-only: they must be reset to the “current” configuration before new/modified files can be checked-in. An implication to be aware of with this approach is that the time to switch the configuration can take a few seconds to a few minutes on very large views.

6.2 Simplify “Merge Down” with Branch-All ViewsIf you use a branch-all variant view with item configurations set to a specific timestamp, you may periodically want to “rebase” the view by performing a “merge down” from the main view. This can be done with the view compare/merge tool. However, when a branch-all variant view is used as an “activity” view, many files will not have been modified and hence will not have been branched. In this case, the non-branched files can be more quickly rebased with the main view by simply altering their configuration timestamp. Using the Win32 client, this shortcut can be performed with the steps below:

! Right-click the column heading again and select “Sort and Group”. Click “Show Advanced Fields”.

! Change the sorting/grouping order so that the display groups by Branch State followed by whatever else you normally like to see (e.g., sort by status, then name, etc.) Click OK. You’ll see all the files that have not yet branched grouped together under “Not Branched”.

! Right-click the non-branched files and select “Advanced->Behavior”. On the Configuration tab, change the Configuration date to a new timestamp (e.g., the latest view label) and click OK.

24


An example of the Win32 client UI to perform these steps is shown in Figure 6 - Simple "Rebase" of Non-branched Files.

Figure 6 - Simple "Rebase" of Non-branched Files

This effectively rebases all non-branched items to a newer configuration from the parent view. This is faster than view compare/merge and allows you to rebase the view on a controlled basis. The branched files, of course, have to be merged separately. It is also helpful to set-up custom filters with the appropriate sort and group behaviors to make this easy.

6.3 Know What Operations Are ExpensiveMost of the day-to-day StarTeam operations you need to perform are fairly quick. However, a few functions are considerably more expensive on the StarTeam server and can impact the responsiveness of all users if performed often or during peak periods. If possible, these operations should be scheduled for off-peak periods.

! Create derived view: Creating a derived view requires copying each item from the parent view to the child view. Consequently, new views created from large parent views can require thousands of new items to be created, causing the server to become heavily loaded until the new view is created. During that time, other users can experience response delays. It is best to schedule new view creation for off-peak hours.

! Roll-back view: Temporarily rolling-back a client view can cause a momentary surge in server processing in order to fetch the item revisions for the new rolled-back view.

! Label exceptions: When a new view label is created, it “includes” all revisions of each item that were in place as of a specific timestamp. The revision of individual objects that are attached to that view can be adjusted independently, but each such adjustment creates a “label exception” object. As a view label receives more exceptions, the time to retrieve objects based on that label

Create a filter togroup by Branch State

Change non-brancheditems’ configurationtime to known point

25


are impacted. If many adjustments are expected, it is better to create new view labels, which are inexpensive.

! Security log: Because its contents are not cached and require bulk database queries, the security log requires significant resources for large repositories. Only examine the security log when necessary.

6.4 Establish a Quick Backup ProcedureTo backup a StarTeam server configuration, the repository database and vault archive must be copied to backup media, and they must be in a consistent state. Consequently, updates must not be occurring to the server while the backup is in progress. Despite this requirement, you can use a backup procedure that minimizes downtime, often only a few minutes. Try the procedure outlined below, which can be performed manually or automatically using a script:

1. Lock the StarTeam server process via the Server Administrator or the StarTeam command line (“stcmd server-mode -mode lock…”). This command locks out regular StarTeam users but keeps the StarTeam server active.

2. Initiate a disk-to-disk dump of the configuration’s database. Ideally, use a “scratch disk” (one that is not in use) as the dump target, allowing concurrent I/Os between the source and target disks.

3. Simultaneously, initiate a disk-to-disk “differential dump” of the configuration’s archive and attachments folders. A differential dump makes the target folder the same as the source folder, copying or deleting the minimum set of files. If the archive and cache folders are on separate disks, the cache disk is a good candidate for the dump target since the cache disk is not in while the server is locked. This allows concurrent I/O activity between the dump source and target folders.

4. When the database dump and differential archive/attachments dump are both complete, unlock the server process via the Server Administrator or the StarTeam command line (“stcmd server-mode -mode unlock…”). The StarTeam server is now ready to use.

5. After unlocking the server process, copy the database and archive/attachments dumps from their target locations to tape or other removable media. (Remember to include the StarbaseServer.ini file in this process.) This process may take considerably longer than the initial disk-to-disk dumps, but the server remains available while it is in progress.

In this process, disk-to-disk copies speed-up the backup process considerably compared to disk-to-tape backup. Furthermore, a differential dump of the archive, which typically contains the most data to backup, is much faster than a whole-archive copy since a relatively small portion of the archive is typically updated between backups. To take advantage of the speedier differential dump technique, you have to leave the target archive folder in place after the dump is complete. One benefit, however, is that the target archive folder represents a copy of the most recent archive dump. There are several commercially-available tools that perform differential disk-to-disk dumps.

Storing the database vault and archive on specialized “network appliance” servers also provides opportunities for fast backup.

6.5 Use Merge Points WiselyWith large development teams or those that require concurrent development, view merging is a necessity. StarTeam provides three facilities for performing view comparing and merging, each serving a slightly different need:

! Win32 Client: The StarTeam Win32 client provides a built-in view compare/merge facility. It provides graphical comparison and merging, with per-item and per-folder interaction, allowing you to carefully control which items are compared and how each difference is resolved.

26


! Cross-platform Client: The StarTeam cross-platform client provides a View Manager tool that also allows has a graphical interface. View Manager provides less granular control for resolving item differences, but it allows you to perform folder/view comparisons in bulk, and it can attempt to resolve merges automatically.

! ViewMerge Utility: ViewMerge is a command-line utility that provides even less granular control of view comparison and merging, but it allows completely unattended operation, e.g., view a batch script.

All three merge facilities support the notion of merge points. Merge point functionality has two parts:

1. Recording merge points when items are merged: When recording is enabled, the revision numbers of the two items resolved via a merge operation is recorded in a merge point object.

2. Using merge points for comparing items and performing new merges: If merge point usage is enabled, the last recorded merge point between two items is used to determining if either or both items has changed. Furthermore, when a merge tool such as Visual Merge is launch to perform a merge on a text file, the revision of one of the files (usually the source file) is used as the least common ancestor (LCA) to perform a 3-way merge. When merge point usage is not enabled, the LCA is determined by finding the last branch point common to the two files.

In section View Configuration Practices, periodic “downward” merges are needed for activity views and release views. Since the purpose of these merges is to “catch up” the child view with any new changes in the parent view, merge points provide an excellent method to track and resolve only those changes that have occurred since the last merge. Consequently, you should both record and use merge points for performing these “downward” merges.

In contrast, however, you will also need to perform “upward” merges from an activity or release view to the main view. For these merges, you want the “change perspective” to be from the true LCA or original branch point common to each item. Consequently, you should not record or use merge points when merging in the “upward” direction.

6.6 Use a Test ServerA simple but often overlooked measure you can take to smooth out administrative operations in your environment is to deploy a StarTeam server configuration as a test server. Your test server can use lower-cost hardware than your production server, but it should be capable of running on a backup copy of your production server. With this capability, your test server can provide many useful benefits, including:

! You can test new SDK applications, workflow rules, release procedures, and so forth on the test server without fear of unwanted side-effects to your production server.

! The test server can be used to stage new releases of StarTeam and simulate upgrade and migrate operations before applying them to the production server.

! The test server can be used for training new developers and administrators.

! Your organization’s backup and recovery procedures can be tested. And, once you’re sure your emergency procedures are functional, you can use the test server as a backup machine in the event of a catastrophic failure to the production machine.

27

StarTeam Configuration Best Practices Glossary

7 Glossary

activity view A branch-all variant view that is a child of a project’s main view, used to support a specific development activity such as a new application or a significant application enhancement. All items in an activity view have branch-on-change set to true, but they may use either floating or pinned configuration depending on the needs of the development activity. Note that the concept of an activity view is specific to this article.

application lifecycle management (ALM)

The end-to-end process by which software applications are developed. ALM includes all development phases such as requirements specification, modeling and design, software development, and testing. Development organizations use different ALM models to suit their needs in terms of iterative and concurrent development, quality control, and resource utilization.

archive The portion of a StarTeam configuration’s vault that contains the data of all versioned files. The archive consists of OS-level files stored in a configurable directory. The archive must be included when the configuration is backed-up.

attachment A non-versioned file that is “attached” to a CR or other object as ancillary information. Attachment files are stored by the StarTeam server in a separate vault folder. The files within the attachments folder must be included when the configuration is backed-up.

behavior configuration (or item configuration)

The item property that determines whether the item points to the most recent (tip) revision or a specific revision of the referenced object. When an item’s configuration is set to floating, it references the tip revision of the underlying object. Otherwise, the configuration is pinned to a specific label, promotion state, or timestamp so that the item refers to a fixed revision of the object.

branch-on-change The item property that indicates if the underlying object should branch if it is modified via the item. Branch-on-change can only be “true” for items that point to a folder, file, or change request, and only when the item is a child item, is not frozen, and has not yet branched.

cache The portion of a StarTeam configuration’s vault that contains uncompressed, whole revisions of versioned files. The cache is used to accelerate the performance of file check-outs, and its size can be limited. Since everything in the cache can be recreated from data within the archive, the cache is discardable and does not have to be included in backups.

change request (CR) An object that represents a defect report, enhancement request, or other change management artifact. A CR contains properties such as Synopsis, Description, Priority, and Addressed In Build. Change requests are versioned and can branch.

child item An item created by copying an existing item from one folder to another folder, possibly in a different view. The original item becomes the parent item, and new child item maintains a reference to it. Child items are created when a child view is created and when an item is shared into a new location.

child view A view other than a project’s main view. A child view is a second-level view if it is created directly under the main view, a third-level view if it is created as a child of a second-level view, and so forth.

28


derived view A child view that is created as a descendant of its parent view. As compared to a non-derived view, a derived view contains all or a portion of its parent view’s items. A derived view may be a reference view or a variant view.

file In addition to its normal meaning, a file in StarTeam is a versioned object. Each file object has properties such as Name, Modified By, and Size. A file’s property values are stored in the repository, but the data of each revision is stored in the archive.

floating A possible value of an item’s configuration behavior property. An item whose behavior is floating refers to the latest (tip) revision of the underlying object. In contrast, see pinned.

floating view A variant view whose item’s initial configuration behavior is set to floating and whose branch-on-change property is set to “false”. Changes to items within a floating view flow up to the parent view; conversely, changes to the parent view are immediately visible in the floating view. For these reasons, floating views can be confusing and should be used with great care.

folder In addition to its normal meaning, a folder in StarTeam is a versioned object. A folder has properties such as Name and Default Working Folder. Folder changes are versioned, and a folder can branch.

item (or view member) An association entity between an object and a view. An object is “surfaced” to a view via an item that specifically relates the view and object. Items have properties such as configuration behavior and branch-on-change that control which object revision is referenced and how it is managed via the view. Item changes are versioned, allowing views to be rolled back to arbitrary points in time.

label A name that identifies a specific set of objects within the same view. Labels are used to associate files, CRs, and other objects that are related in some way such as belonging to the same release. StarTeam supports two types of labels: view labels and revision labels.

link A binary association between two arbitrary objects. Links are typically used to relate a process item to the files that were modified to fulfill the process item. However, links can be used for other purposes. Each link “end point” can be pinned to a specific revision of its associated object or float to the tip revision.

main view The initial view automatically created when a new project is created. The main view can have one or more child views, but it has no parent view.

merge point A database record that specifies the exact revision of two files that were merged. Merge points can be recorded and/or used by the various StarTeam view merge utilities.

non-derived view (or blank view)

A view that is neither a main view nor a child view. Except for a root folder, a non-derived view is initially empty, and items must be explicitly added to or shared into it. Non-derived views are marginally useful.

object (or content object) An object is a versioned entity that contains “content”, consisting of properties. Each property has a name and value; changes to one or more of an object’s properties cause a new revision of the object to be created. Objects are “surfaced” through views via items.

29


parent item An item that is shared from one location to another, thereby creating a child item. Changes to a parent item may propagate to its child items depending on the behavior configuration of each child item.

parent view A view that was used as the source to create a new child view. The child view will contain all or a subset of the parent view’s items.

pinned A possible value of an item’s behavior configuration that indicates that a specific revision of the item’s associated object is referenced. Compare to the floating configuration.

process item A CR, task, or requirement that is used to associate file changes with a specific work activity. A project can use process rules to require the use of process items for new file revisions.

process rule A project property that defines if and how process items are used to control new file revisions. When in force, process rules cause automatic links to be created between the active process item and new files and new file revisions.

project The primary container type used to manage artifacts with a StarTeam server configuration. A configuration can contain multiple projects, each of which has a single main view and optionally one or more child views. In addition to its own views, each project has certain properties such as process rules that control its use.

promotion state An enumerated name that is used to assist with build management, workflow, and content deployment. Promotion states are user-defined, unique to each view, and possess an explicit order. Each promotion state is mapped to a specific view label, which can be changed to “promote” new object revisions to the corresponding state.

reference view (or non-branching view)

A child view that is created as pure subset of its parent view. Items within a reference views do not branch and refer to exactly the same objects as their parent view counterparts. Reference views are occasionally useful to create a subset perspective of some other view.

repository Formally, the portion of a StarTeam server configuration that is stored in a database. (The vault constitutes the remainder of the server configuration.) Informally, the term repository is sometimes used to refer to the entire server configuration.

revision label A label that typically identifies a small set of objects that share a common purpose (e.g., a set of file revisions that implement a specific feature). Revision labels are less commonly used than view labels.

root folder The parent-most folder of a given view. Every view is created with a root folder, into which objects, including other folders, can be added.

server configuration A StarTeam deployment instance, consisting of a repository and a vault. A server configuration, is the highest-level StarTeam “container”. A server configuration must have at least one project in order to store information.

software configuration management (SCM)

The practice of managing software artifacts (source and binary files, change requests, design documents, etc.) to support software management. SCM tools such as StarTeam provide facilities for versioning, branching, and merging; defect and enhancement request management; task definition and management; and other activities.

30


share An item that has been copied from one location to another, for example by dragging it from one folder to another in the Win32 client with the Ctrl key pressed. The original (shared) item becomes the parent item, while the newly-copied item becomes a child item, initially pointing to the same revision of the same object. A parent item and the child items created by sharing it constitute a “share tree”.

subtask A task that is subordinate to another task, thereby representing a subset of the parent task’s work.

support view A branch-all variant view that is a child of a project’s main view, used for maintenance work of a specific release. A child view may initially begin as an activity view and switch roles to a support view after the activity is complete and therefore typically merged back to the main view. All items in a support view have branch-on-change set to true, and items that have not branched use a pinned configuration to prevent changes to parent items from flowing downward. Note that the concept of a support view is specific to this article.

task An object that represents a specific unit of work activity. (A task is analogous to the same term used in project management systems such as MS Project.) Compared to a CR, a task typically represents a longer-term activity and hence may have subtasks that break the corresponding work into smaller units. A task can have work records that record completion of related work steps. Tasks are versioned, but they do not branch.

topic An object that represents a newsgroup-like message, typically created by a user relevant to a specific development activity. Topics tied to the same conversation constitute a “threaded conversation” that can be linked to a CR or task to which the conversation is related. Topics are versioned but do not branch.

vault The portion of a StarTeam server configuration that holds managed file contents. The vault consists of OS-level files that are organized into three separate directories that hold different types of files: archive, cache, and attachments.

variant view (or branching view)

A child view that allows its items to branch. Depending on the configuration behavior of its items and how it is used, a variant view may serve as an activity view, support view, or for some other purpose. Compare to a reference view.

view A “window” into a project that holds objects for a specific purpose. Every new project begins with a main view that holds the project’s initial objects. Additional child views can be created to support specific development activities or user communities. A reference view holds a pure subset of its parent’s objects, while a variant view may vary from its parent with the objects and object revisions that it contains. Objects are surfaced through views via items.

view label A label that is created at the view level, thereby referencing a specific revision of most or all objects within the view. A view label may optionally be designated as a “build label”. The revision of each file, CR, and other objects included in the view label may be adjusted, and objects can be attached to or detached from a view label.

work record A completed unit of work for a specific task. A developer working on a task typically adds work records to the task as development steps are complete, eventually allowing the task to be marked as “finished”.

31


Copyright Notice

Made in Borland® Copyright © 2003 Borland Software Corporation. All rights reserved. All Borland brand and product names are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries. Microsoft, Windows, and other Microsoft product names are trademarks or registered trademarks of Microsoft Corporation in the U.S. and other countries. Linux is a registered trademark of Linus Torvalds. All other marks are the property of their respective owners. Corporate Headquarters: 100 Enterprise Way, Scotts Valley, CA 95066-3249 • 831-431-1000 • www.borland.com • Offices in: Australia, Brazil, Canada, China, Czech Republic, France, Germany, Hong Kong, Hungary, India, Ireland, Italy, Japan, Korea, the Netherlands, New Zealand, Russia, Singapore, Spain, Sweden, Taiwan, the United Kingdom, and the United States. •

StarTeam Configuration Best Practices - Embarcadero...

Documents

Transcript of StarTeam Configuration Best Practices - Embarcadero...